diff --git a/CNAME b/CNAME new file mode 100644 index 0000000..62c4181 --- /dev/null +++ b/CNAME @@ -0,0 +1 @@ +nest-native.dev \ No newline at end of file diff --git a/ideas/01-production-reference-app.md b/ideas/01-production-reference-app.md new file mode 100644 index 0000000..b69d43b --- /dev/null +++ b/ideas/01-production-reference-app.md @@ -0,0 +1,99 @@ +# Production Reference App + +**Project type:** New project. + +**Suggested repository:** `nest-native/reference-app` or `nest-native/nest-native-reference` + +## Summary + +Build a real production-shaped application that uses the Nest Native libraries +together, especially `nest-drizzle-native` and `nest-trpc-native`. + +The goal is not another small sample. The goal is a credible reference app that +answers the question maintainers and teams actually ask: + +> Can I trust this stack in a serious NestJS application? + +## Community Pain + +Most library samples are too small. They prove an API call, but not the +operational shape of a real backend: + +- feature modules +- auth and authorization +- request-scoped context +- transactions across services +- database migrations +- health checks +- tests with real database behavior +- deployment steps +- typed client consumption +- production documentation + +Developers can understand a library API and still hesitate because they cannot +see how the pieces behave together in an application. + +## Proposed App Shape + +A compact but realistic SaaS-style application: + +- accounts or organizations +- users and memberships +- roles or permissions +- projects/tasks/tickets +- audit log or activity feed +- transactional workflows +- admin-only endpoints +- typed frontend or typed client smoke checks + +The app should avoid demo-only gimmicks. It should feel like a small backend a +team could adapt. + +## Libraries Demonstrated + +- `nest-drizzle-native` for database registration, repositories, transactions, + migrations, named clients if needed, and testing utilities +- `nest-trpc-native` for decorator-first routers, procedures, enhancers, typed + client generation, and Nest dependency injection +- standard NestJS guards, pipes, interceptors, filters, request scope, and + lifecycle hooks + +## What It Should Prove + +- A transaction can span multiple services without passing `tx` through every + method. +- DTO validation and tRPC/Zod style validation can coexist without making one + mandatory everywhere. +- Repository classes remain thin homes for query code, not an Active Record + rewrite. +- Health/readiness, migrations, CI, and release checks have a clear production + path. +- The typed client story remains ergonomic. + +## Suggested Milestones + +1. Scaffold a minimal Nest app with Drizzle and tRPC. +2. Add database schema, migrations, and seed data. +3. Add auth context and request-scoped user/tenant providers. +4. Add core modules: users, organizations, projects, audit log. +5. Add transactional workflow: invite user, create project, record audit event. +6. Add tests: unit, integration, real DB, typed client checks. +7. Add deployment documentation and Docker/Kubernetes examples. +8. Add a README that explains architecture decisions without becoming a book. + +## Success Criteria + +- A new user can clone the app, run tests, and understand the architecture in + under an hour. +- The app reveals real improvements or gaps in the existing libraries. +- Any library fixes discovered are handled in separate PRs, not mixed into the + reference app. + +## Why This Is Worth Doing + +This is probably the highest-value next step. It strengthens both existing +libraries and creates a proof artifact for the whole Nest Native philosophy. + +It also protects us from building unnecessary APIs. If the reference app feels +good with the current libraries, avoid adding helpers. If it feels repetitive in +specific places, those are the right candidates for future API design. diff --git a/ideas/02-transactional-outbox.md b/ideas/02-transactional-outbox.md new file mode 100644 index 0000000..b8c69da --- /dev/null +++ b/ideas/02-transactional-outbox.md @@ -0,0 +1,126 @@ +# Transactional Outbox Pattern + +**Project type:** New project, with integration samples in existing projects. + +**Possible future project:** `nest-native/nest-outbox-native` + +**Integration targets:** `nest-drizzle-native`, `nest-trpc-native`, and ordinary +NestJS applications. + +## Summary + +Explore a Nest-native transactional outbox package for reliable side-effect +orchestration. + +This goes beyond `nest-drizzle-native` scope. The Drizzle library can prove the +database transaction foundation, and the tRPC library can prove a typed +mutation boundary, but outbox processing itself is a separate concern. + +## Community Pain + +Backend teams often need to perform a database write and then trigger a side +effect: + +- publish an event +- send an email +- enqueue a job +- sync data to another system +- call a webhook + +The dangerous version is: + +1. write to the database +2. send the message immediately +3. later discover the transaction rolled back + +Or the opposite: + +1. commit the database change +2. crash before sending the message + +The transactional outbox pattern solves this by writing the side effect intent +inside the same transaction, then processing it after commit. + +## Why It Fits Nest Native + +The outbox pattern fits the broader Nest Native philosophy because it connects +several production concerns without hiding them: + +- tRPC or REST receives the typed application command +- `@Transactional()` owns the workflow boundary +- repositories write domain rows and outbox rows in the same transaction +- a worker processes committed outbox records +- retries and idempotency are explicit +- no side effects happen before the database commit is durable + +## Proposed First Proof + +Start with a small proof app or reference-app slice, not a new package API: + +- `nest-trpc-native` exposes a mutation +- `nest-drizzle-native` persists the domain row and outbox row +- an app-owned worker processes committed events +- tests prove rollback safety and retry behavior + +Scenario: + +- create an account +- insert an outbox event in the same transaction +- simulate rollback and prove no event is processed +- commit and prove the event is picked up +- mark event processed +- retry failed events safely + +## Minimal Schema + +- `accounts` +- `outbox_events` + +Outbox fields: + +- `id` +- `topic` +- `payload` +- `status` +- `attempts` +- `available_at` +- `processed_at` +- `created_at` + +## Documentation Topics + +- why not publish inside the transaction method +- how to keep payloads safe and versioned +- idempotency keys +- retry strategy +- worker ownership +- poison message handling +- observability +- when a queue is still needed + +## Possible Public API + +Only after proof-first validation: + +- `OutboxModule` +- `OutboxRepository` +- `OutboxProcessor` +- `@OutboxHandler('topic')` +- retry and idempotency helpers + +But this should not be rushed. A premature package could become too opinionated +about queues, retries, serialization, and deployment. + +## Success Criteria + +- The proof proves rollback safety with a real database. +- The docs explain the pattern without pretending the library owns every queue + strategy. +- The implementation remains small enough that application teams can adapt it + before a reusable package exists. + +## Why This Is Worth Doing + +This solves a real production problem that sits between database transactions, +API boundaries, workers, and side effects. It deserves its own project if the +proof shows enough repeated shape to justify a package. diff --git a/ideas/03-create-nest-native-app.md b/ideas/03-create-nest-native-app.md new file mode 100644 index 0000000..c695039 --- /dev/null +++ b/ideas/03-create-nest-native-app.md @@ -0,0 +1,107 @@ +# Create Nest Native App + +**Project type:** New project, later. + +**Suggested repository:** `nest-native/create-nest-native-app` + +## Summary + +Build a project generator or CLI that scaffolds production-minded Nest Native +applications. + +This should not be the next immediate project. It becomes valuable after the +reference app and more samples prove which architecture choices are stable. + +## Community Pain + +Starting a serious Nest app involves many decisions: + +- database integration +- transaction pattern +- migrations +- validation style +- OpenAPI or tRPC +- testing +- CI +- deployment +- health checks +- package manager +- folder structure + +Most starters are either too minimal or too opinionated. A Nest Native +generator could give users a curated, production-shaped starting point. + +## Possible User Flow + +```bash +npm create nest-native-app +``` + +Prompts: + +- project name +- package manager +- database driver +- Drizzle only, tRPC only, or both +- REST/OpenAPI, tRPC, or mixed +- class-validator DTOs or Zod opt-in +- include Docker/deployment files +- include GitHub Actions CI +- include example auth/context + +## First Template + +Start with one strong template instead of many weak ones: + +- NestJS 11 +- Node 20+ +- `nest-drizzle-native` +- SQLite/libSQL local development +- optional PostgreSQL production recipe +- migrations +- health checks +- tests +- CI + +Add tRPC only after the Drizzle-only template feels excellent. + +## What It Should Generate + +- `src/app.module.ts` +- database module +- schema/migrations folder +- health endpoints +- one feature module with repository/service/controller or router +- test setup +- CI workflow +- README with exact commands +- deployment notes + +## Risks + +- CLI maintenance can become expensive. +- Too many options can make the generated app inconsistent. +- Templates can drift from library best practices. +- Users may expect the CLI to solve application architecture decisions that + should remain app-owned. + +## Readiness Criteria + +Do not start this until: + +- the production reference app exists +- core samples are stable +- docs have settled +- common project structure decisions are clear +- release and update process for templates is understood + +## Success Criteria + +- A new user can generate an app and run tests in minutes. +- Generated code looks like something we would maintain ourselves. +- The template reinforces Nest Native philosophy instead of hiding it. + +## Why This Is Worth Doing + +If the ecosystem grows, a generator can dramatically reduce onboarding +friction. But it should come after the architecture is proven, not before. diff --git a/index.html b/index.html index a5078a9..48e7160 100644 --- a/index.html +++ b/index.html @@ -121,22 +121,6 @@

nest-trpc-native

-
-
-

Exploration

-

nest-prisma-native

-

- A feasibility track for a thin, Prisma-respecting Nest - integration focused on clients, repositories, transactions, - testing, and error mapping. -

-
-
- - GitHub - -
-
@@ -154,8 +138,8 @@

Feel native. Stay honest.

It should also respect the tool it integrates. Drizzle should still feel SQL-first. tRPC should still preserve end-to-end type safety. - Future Prisma work should keep the generated client visible and - trusted. + Future integrations should only exist when they solve a real gap + without hiding the underlying tool.