create-bcp-app 0.3.0 → 0.3.2

package/README.md

@@ -10,7 +10,7 @@ npm run dev
 
 ## Project-local BCP CLI
 
-Generated npm scripts use the project-local framework CLI:
+Generated npm scripts use the local framework CLI:
 
 ```json
 {
@@ -64,17 +64,17 @@ Select storage provider:
 
 New projects include `bcp.project.json`.
 
-Example for the `0.3.0` target:
+Example for the `0.3.1` target:
 
 ```json
 {
   "schemaVersion": 1,
   "framework": "bcp",
   "projectName": "my-app",
-  "frameworkPackage": "npm:@chidchanun/bcp@0.3.0",
+  "frameworkPackage": "npm:@chidchanun/bcp@0.3.1",
   "createdWith": {
     "package": "create-bcp-app",
-    "version": "0.3.0"
+    "version": "0.3.1"
   },
   "packageManager": "npm",
   "presets": {
@@ -88,9 +88,9 @@ Example for the `0.3.0` target:
 
 This manifest records scaffold identity only. Do not place secrets in it.
 
-## BCP Application Platform — 0.3.0+
+## Application Platform
 
-Applications can optionally centralize server infrastructure through `bcp/application`:
+Applications can centralize server infrastructure through `bcp/application`:
 
 ```ts
 import {
@@ -103,21 +103,99 @@ export const app =
     });
 ```
 
-Register existing provider-native services:
+Existing BCP subsystem APIs remain independently usable.
+
+## Dependency Injection & Service Container — 0.3.1+
+
+Typed dependencies use `bcp/container`:
+
+```ts
+import {
+    createServiceToken,
+    provideFactory,
+    provideValue,
+} from "bcp/container";
+
+const configToken =
+    createServiceToken<{
+        apiUrl: string;
+    }>("config");
+
+const repositoryToken =
+    createServiceToken<UserRepository>(
+        "user-repository"
+    );
+
+export const app =
+    createApp({
+        name: "my-app",
+        providers: [
+            provideValue(
+                configToken,
+                {
+                    apiUrl: "https://api.example.com",
+                }
+            ),
+            provideFactory(
+                repositoryToken,
+                [
+                    configToken,
+                ] as const,
+                (_context, [config]) =>
+                    createRepository(
+                        config.apiUrl
+                    )
+            ),
+        ],
+    });
+```
+
+Resolve from server/application code:
+
+```ts
+const repository =
+    await app.container.resolve(
+        repositoryToken
+    );
+```
+
+Supported lifetimes:
+
+```text
+singleton
+scoped
+transient
+```
+
+For request/job/test boundaries:
 
 ```ts
-app.provide(
-    "database",
-    database
-);
-
-app.provide(
-    "cache",
-    cache
-);
+const scope =
+    app.createScope({
+        name: "request:123",
+    });
 ```
 
-Register long-running lifecycle resources:
+Testing overrides:
+
+```ts
+const testScope =
+    app.createScope({
+        name: "test",
+        overrides: [
+            provideValue(
+                mailerToken,
+                fakeMailer
+            ),
+        ],
+    });
+```
+
+DI is optional. Existing `app.services` and plugin service registries remain supported.
+
+## Lifecycle resources
+
+Long-running infrastructure still uses Deployment Platform resources:
 
 ```ts
 app.addResource({
@@ -137,14 +215,10 @@ app.addResource({
 });
 ```
 
-Application startup orders plugins before infrastructure resources and the application start hook. Shutdown reverses dependency order.
-
-Existing `bcp/database`, `bcp/jobs`, `bcp/workflow`, `bcp/events`, `bcp/realtime`, `bcp/cache`, `bcp/plugins`, `bcp/observability` and `bcp/deployment` APIs remain usable independently.
+In `0.3.1`, the DI container remains active until application resources and plugins have stopped, then disposes injected services in reverse creation order.
 
 ## Database presets
 
-Database choices add starter configuration and the matching driver:
-
 - MySQL: `mysql2`
 - PostgreSQL: `pg`
 - SQLite: `better-sqlite3`
@@ -157,72 +231,21 @@ For MySQL, PostgreSQL and SQLite, generated `lib/database.ts` exposes BCP databa
 
 The JWT Cookie preset creates starter authentication code. BCP supports revocable session stores, permission/policy authorization, route guards and same-origin/CSRF helpers.
 
-## Background jobs, workflows and events
-
-```ts
-import {
-    createJobQueue,
-    createJobScheduler,
-} from "bcp/jobs";
-import {
-    createWorkflow,
-} from "bcp/workflow";
-```
-
-Durable Redis-compatible queues/schedules, workflow orchestration and transactional outbox/event delivery are available without forcing a Redis client dependency.
+## Jobs, workflows, events and realtime
 
-## Realtime
-
-```ts
-import {
-    createRealtime,
-} from "bcp/realtime";
-
-export const realtime =
-    createRealtime();
-```
-
-BCP does not install a WebSocket server library. Applications adapt their provider to `RealtimeSocket`; SSE is built in.
+Use `bcp/jobs`, `bcp/workflow`, `bcp/events` and `bcp/realtime` directly or register selected instances with the Application Platform/DI container.
 
 ## Testing
 
-`bcp/testing` provides request/route/page/auth/database/middleware/jobs/workflow/outbox/realtime test harnesses and does not require Jest or Vitest.
+`bcp/testing` provides framework-native request/route/page/auth/database/middleware/jobs/workflow/outbox/realtime helpers. DI scope overrides complement these helpers for application-level dependency replacement.
 
 ## Plugins
 
-`bcp/plugins` provides dependency ordering, module composition, lifecycle hooks, config parsing, shared services and async hooks. Plugin definitions/modules can be passed directly to `createApp()`.
-
-## Cache Platform v2
+`bcp/plugins` remains available for reusable plugin/module lifecycle composition. Plugin definitions/modules can be passed to `createApp()`.
 
-```ts
-import {
-    createCacheStore,
-} from "bcp/cache";
-
-export const cache =
-    createCacheStore();
-```
+## Observability and deployment
 
-Multi-instance applications can use Redis-compatible cache and lock adapters for distributed cache-fill coordination.
-
-## Observability Platform v3
-
-```ts
-import {
-    createTracer,
-} from "bcp/observability";
-
-export const tracer =
-    createTracer({
-        serviceName: "my-app",
-    });
-```
-
-Tracing supports W3C `traceparent`, correlation IDs, request middleware, explicit carriers and provider-neutral exporters.
-
-## Deployment Platform v2
-
-`bcp/deployment` remains available for applications that want to own resource lifecycle directly. `bcp/application` reuses the same resource/readiness/diagnostics model when using the Application Platform.
+`bcp/observability` provides metrics/tracing. `bcp/deployment` remains available when an application wants to own resource lifecycle directly; `bcp/application` reuses its readiness/diagnostics/shutdown model.
 
 ## Application packaging
 
@@ -231,9 +254,7 @@ npm run build
 npm run package
 ```
 
-The deployment package excludes application `devDependencies` and project `.env` values. Supply secrets through the deployment environment.
-
-BCP `0.3.0` prepared framework packages add compiled `application.mjs` to the compiled ESM server-runtime set.
+BCP `0.3.1` prepared packages include compiled `container.mjs` and `application.mjs` server runtimes. Project `.env` files and application devDependencies are excluded from deployment packages.
 
 ## Project generators
 
@@ -261,5 +282,5 @@ npm run generate -- migration create_users
 For prerelease/local package verification:
 
 ```bash
-npx create-bcp-app my-app --bcp file:../chidchanun-bcp-0.3.0.tgz
+npx create-bcp-app my-app --bcp file:../chidchanun-bcp-0.3.1.tgz
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-bcp-app",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "Create a new BCP Framework application.",
   "type": "module",
   "license": "MIT",

package/template/README.md

@@ -27,7 +27,7 @@ npm run update
 
 Generated projects include `bcp.project.json` with non-secret scaffold metadata. Commit it with the project, but never put passwords, tokens or access keys in it.
 
-## Application Platform — BCP 0.3.0+
+## Application Platform — BCP 0.3.x
 
 For applications with several server subsystems, `bcp/application` provides one optional composition root:
 
@@ -42,14 +42,84 @@ export const app =
     });
 ```
 
-Register shared service instances before startup:
+## Dependency Injection — BCP 0.3.1+
+
+Use `bcp/container` for typed application dependencies:
+
+```ts
+import {
+    createServiceToken,
+    provideFactory,
+    provideValue,
+} from "bcp/container";
+
+const configToken =
+    createServiceToken<{
+        apiUrl: string;
+    }>("config");
+
+const clientToken =
+    createServiceToken<ApiClient>(
+        "api-client"
+    );
+
+export const app =
+    createApp({
+        name: "bcp-app",
+        providers: [
+            provideValue(
+                configToken,
+                {
+                    apiUrl: "https://api.example.com",
+                }
+            ),
+            provideFactory(
+                clientToken,
+                [
+                    configToken,
+                ] as const,
+                (_context, [config]) =>
+                    createApiClient(
+                        config.apiUrl
+                    )
+            ),
+        ],
+    });
+```
+
+Resolve typed services:
+
+```ts
+const client =
+    await app.container.resolve(
+        clientToken
+    );
+```
+
+Provider lifetimes are `singleton`, `scoped` and `transient`.
+
+For request/job/test scopes:
+
+```ts
+const scope =
+    app.createScope({
+        name: "request:123",
+    });
+```
+
+Testing overrides can replace selected providers within a child scope without changing the root application container.
+
+The legacy Plugin Platform registry remains supported:
 
 ```ts
 app.provide("database", database);
-app.provide("cache", cache);
 ```
 
-Register lifecycle-owned resources:
+Use typed `ServiceToken<T>` providers for new application dependency injection code.
+
+## Lifecycle resources
+
+Long-running infrastructure uses `app.addResource()`:
 
 ```ts
 app.addResource({
@@ -69,13 +139,13 @@ app.addResource({
 });
 ```
 
-Then start the application runtime from your server/bootstrap composition code:
+Then start the application runtime from server/bootstrap code:
 
 ```ts
 await app.start();
 ```
 
-Existing plugin modules can be passed directly to `createApp()`. Existing subsystem APIs remain available independently when a centralized application runtime is unnecessary.
+BCP `0.3.1` keeps the DI container alive until application resources/plugins have stopped, then disposes resolved services in reverse creation order.
 
 ## Authentication and authorization
 
@@ -83,25 +153,11 @@ JWT Cookie projects can use `createAuth()` and optional `AuthSessionStore` revoc
 
 ## Database
 
-MySQL, PostgreSQL and SQLite projects expose the BCP database platform through `bcp/database`.
-
-## Jobs, scheduling and workflows
-
-```ts
-import {
-    createJobQueue,
-    createJobScheduler,
-} from "bcp/jobs";
-import {
-    createWorkflow,
-} from "bcp/workflow";
-```
-
-Durable jobs support leases, heartbeat, stale recovery and DLQ. Workflows support sequential/parallel steps, retries, persisted delays and compensation.
+MySQL, PostgreSQL and SQLite projects expose database primitives through `bcp/database`.
 
-## Transactional events
+## Jobs, workflows and events
 
-Use `bcp/events` when business data and an integration event must commit in the same SQL transaction. The outbox dispatcher can deliver through durable jobs or an application publisher after commit.
+Use `bcp/jobs`, `bcp/workflow` and `bcp/events` independently or compose instances through the Application Platform.
 
 ## Realtime
 
@@ -118,58 +174,35 @@ BCP does not install a WebSocket server library. Adapt the selected provider thr
 
 ## Testing
 
-`bcp/testing` provides request/route/page/auth/database/middleware/jobs/workflow/outbox/realtime/SSE test helpers without requiring Jest or Vitest.
+`bcp/testing` provides framework-native server test helpers. `bcp/container` child-scope overrides can replace application dependencies during tests.
 
 ## Plugins
 
-`bcp/plugins` provides reusable server-side plugins/modules, dependency ordering, lifecycle hooks, config parsing, shared services and awaited hooks. Plugin definitions/modules can also be composed by `bcp/application`.
-
-## Cache Platform v2
+`bcp/plugins` provides reusable server-side plugins/modules, dependency ordering, lifecycle hooks, config parsing, shared services and awaited hooks.
 
-```ts
-import {
-    createCacheStore,
-} from "bcp/cache";
-
-export const cache =
-    createCacheStore();
-```
-
-Use Redis-compatible cache/lock adapters for multi-instance cache-fill coordination when needed.
-
-## Observability Platform v3
-
-```ts
-import {
-    createTracer,
-} from "bcp/observability";
-
-export const tracer =
-    createTracer({
-        serviceName: "bcp-app",
-    });
-```
+## Cache and observability
 
-Tracing supports AsyncLocalStorage context, W3C `traceparent`, correlation IDs, request tracing, trace carriers and provider-neutral exporters.
+`bcp/cache` provides provider-neutral cache/lock primitives. `bcp/observability` provides metrics, health and tracing.
 
 ## Deployment lifecycle
 
-`bcp/deployment` remains available when the project wants direct lifecycle ownership. `bcp/application` reuses the same resource/readiness/diagnostics model and adds application/plugin composition around it.
+`bcp/deployment` remains available for direct lifecycle ownership. `bcp/application` composes the same readiness/diagnostics/shutdown model.
 
-Application Platform startup order is:
+Application startup order in `0.3.1` is:
 
 ```text
 application setup
+container
 plugins
 resources
 application start
 ```
 
-Shutdown reverses resource dependencies before disposing the application.
+Shutdown reverses deployment dependencies, then runs application disposal.
 
 ## API baseline
 
-BCP `0.3.0` preserves the public `0.2.19` entrypoints and adds `bcp/application`. Application code should import documented public `bcp/*` entrypoints and avoid private framework `packages/*` paths.
+BCP `0.3.1` advances `0.3.0` additively with `bcp/container`. Application code should use documented public `bcp/*` entrypoints and avoid private framework `packages/*` paths.
 
 ## Production build
 
@@ -184,9 +217,9 @@ npm start
 npm run package
 ```
 
-BCP excludes project `.env` files and application `devDependencies` from the deployment package. Supply secrets through the deployment environment.
+BCP excludes project `.env` files and application `devDependencies` from deployment packages. Supply secrets through the deployment environment.
 
-BCP 0.3.0 adds compiled `application.mjs` to the main compiled server-runtime entrypoints.
+Prepared `0.3.1` packages include compiled `container.mjs` and `application.mjs` runtimes.
 
 ## Direct CLI usage