@chidchanun/bcp 0.2.14 → 0.2.16

package/docs/plugin-module-platform.md

@@ -0,0 +1,391 @@
+# Plugin & Module Platform
+
+BCP `0.2.15` adds the server-only `bcp/plugins` entrypoint for composing framework/application extensions with explicit dependencies and lifecycle control.
+
+## Import
+
+```ts
+import {
+    createPluginHost,
+    defineModule,
+    definePlugin,
+} from "bcp/plugins";
+```
+
+`bcp/plugins` is server-only and cannot be imported from page/client bundles.
+
+## Define a plugin
+
+```ts
+export const databasePlugin =
+    definePlugin({
+        name: "database",
+
+        async setup(context) {
+            context.services.provide(
+                "database",
+                db
+            );
+        },
+
+        async start() {
+            await db.connect();
+        },
+
+        async stop() {
+            await db.disconnect();
+        },
+    });
+```
+
+A plugin can expose four lifecycle hooks:
+
+```text
+setup()
+start()
+stop()
+dispose()
+```
+
+`setup()` prepares dependency wiring and shared services. `start()` begins runtime work. `stop()` shuts active work down. `dispose()` releases setup-level resources when the host closes.
+
+## Dependency ordering
+
+```ts
+const jobsPlugin =
+    definePlugin({
+        name: "jobs",
+        requires: [
+            "database",
+        ],
+    });
+```
+
+The host resolves required dependencies before dependents:
+
+```text
+database
+   ↓
+jobs
+   ↓
+workflow
+```
+
+Startup follows this order. Shutdown and disposal run in reverse order.
+
+Missing required dependencies throw `PluginDependencyError` before lifecycle execution begins.
+
+Dependency cycles are rejected:
+
+```text
+a -> b -> c -> a
+```
+
+Optional dependencies participate in ordering only when they are registered:
+
+```ts
+definePlugin({
+    name: "metrics-addon",
+    optional: [
+        "observability",
+    ],
+});
+```
+
+## Create a host
+
+```ts
+const host =
+    createPluginHost({
+        plugins: [
+            databasePlugin,
+            jobsPlugin,
+        ],
+    });
+
+await host.start();
+```
+
+For graceful shutdown:
+
+```ts
+await host.stop();
+await host.close();
+```
+
+`close()` is idempotent. If the host is still started it stops the runtime before disposal.
+
+## Modules
+
+A module is a named bundle of plugin definitions.
+
+```ts
+export const backendModule =
+    defineModule({
+        name: "backend",
+        plugins: [
+            databasePlugin,
+            jobsPlugin,
+            workflowPlugin,
+        ],
+    });
+
+const host =
+    createPluginHost({
+        modules: [
+            backendModule,
+        ],
+    });
+```
+
+Modules do not create a second lifecycle system. They only group plugins; dependency resolution still occurs globally across the host.
+
+You can also register before setup begins:
+
+```ts
+host.use(databasePlugin);
+host.use(backendModule);
+```
+
+Registration is locked after setup starts so runtime dependency graphs cannot change underneath active plugins.
+
+## Typed plugin configuration
+
+A plugin can parse its own configuration:
+
+```ts
+const httpPlugin =
+    definePlugin<{
+        port: number;
+    }>({
+        name: "http",
+
+        config: {
+            port: 3000,
+        },
+
+        schema: {
+            parse(value) {
+                const port =
+                    Number(
+                        (
+                            value as {
+                                port?: unknown;
+                            }
+                        )?.port
+                    );
+
+                if (!Number.isInteger(port)) {
+                    throw new Error(
+                        "port must be an integer"
+                    );
+                }
+
+                return {
+                    port,
+                };
+            },
+        },
+
+        setup(context) {
+            console.log(
+                context.config.port
+            );
+        },
+    });
+```
+
+Application-level host configuration overrides the plugin default:
+
+```ts
+const host =
+    createPluginHost({
+        plugins: [
+            httpPlugin,
+        ],
+        configs: {
+            http: {
+                port: 8080,
+            },
+        },
+    });
+```
+
+A schema may be an object with `parse()` or a parser function.
+
+## Shared service registry
+
+Plugins can publish typed application services:
+
+```ts
+setup(context) {
+    context.services.provide(
+        "mailer",
+        mailer
+    );
+}
+```
+
+A dependent plugin can consume the service:
+
+```ts
+setup(context) {
+    const mailer =
+        context.services.get<Mailer>(
+            "mailer"
+        );
+}
+```
+
+Available operations:
+
+```text
+provide()
+get()
+optional()
+has()
+delete()
+keys()
+```
+
+Duplicate `provide()` calls are rejected unless `{ replace: true }` is explicit.
+
+String and Symbol service keys are supported.
+
+## Asynchronous extension hooks
+
+The host also exposes a small asynchronous hook bus:
+
+```ts
+const unsubscribe =
+    context.hooks.on<{
+        userId: number;
+    }>(
+        "user.created",
+        async event => {
+            await sendWelcomeEmail(
+                event.userId
+            );
+        }
+    );
+```
+
+Emit from another plugin:
+
+```ts
+await context.hooks.emit(
+    "user.created",
+    {
+        userId: 42,
+    }
+);
+```
+
+Handlers run in registration order and are awaited. The hook bus is intended for in-process extension points, not durable event delivery.
+
+Use `bcp/events` for durable integration events that must survive process failure.
+
+## Lifecycle failure behavior
+
+If a plugin fails during `start()`, plugins that already started in that transition are stopped in reverse order before `PluginLifecycleError` is propagated.
+
+```text
+database start ✅
+jobs start ✅
+workflow start ❌
+
+rollback:
+jobs stop
+database stop
+```
+
+This prevents partially-started application runtimes from being left active after a startup failure.
+
+Lifecycle records can be inspected:
+
+```ts
+host.plugin("jobs");
+host.plugins();
+```
+
+States include:
+
+```text
+registered
+setting-up
+ready
+starting
+started
+stopping
+stopped
+failed
+```
+
+## Relationship to existing BCP platforms
+
+`bcp/plugins` composes services; it does not replace their own durability/lifecycle contracts.
+
+```text
+Plugin Host
+   |
+   +-- Database plugin ------> bcp/database
+   +-- Jobs plugin ----------> bcp/jobs
+   +-- Workflow plugin ------> bcp/workflow
+   +-- Events plugin --------> bcp/events
+   +-- Realtime plugin ------> bcp/realtime
+   +-- Observability plugin -> bcp/observability
+```
+
+A plugin can wrap any existing BCP subsystem and expose the resulting instance through the service registry.
+
+## Production guidance
+
+Keep plugin names stable because dependency declarations reference names.
+
+Prefer explicit required dependencies instead of relying on registration order.
+
+Use plugin configuration parsing near the plugin boundary so invalid configuration fails before startup.
+
+Use `dispose()` for resources created during setup, and `stop()` for active runtime processes such as workers, schedulers and network listeners.
+
+Do not use the hook bus as a durable message broker. Use Transactional Outbox/Jobs for delivery guarantees.
+
+## 0.2.15 scope
+
+Included:
+
+```text
+bcp/plugins
+definePlugin()
+defineModule()
+createPluginHost()
+required dependencies
+optional dependencies
+topological ordering
+cycle detection
+setup/start/stop/dispose lifecycle
+reverse shutdown
+startup rollback
+plugin state records
+config parser/schema contract
+host config overrides
+service registry
+async hook bus
+server-only boundary
+compiled plugins.mjs
+unit tests
+prepared package smoke
+```
+
+Not included yet:
+
+```text
+automatic npm plugin discovery
+remote plugin loading
+sandboxed/untrusted plugins
+hot plugin replacement
+plugin marketplace
+CLI plugin install command
+```
+
+Those can be added later without changing the core host contract.

package/docs/releases/0.2.15.md

@@ -0,0 +1,118 @@
+# BCP Framework 0.2.15 — Plugin & Module Platform
+
+**Release state:** unreleased
+
+BCP `0.2.15` adds a server-only plugin/module composition layer through `bcp/plugins`.
+
+## Highlights
+
+- new `bcp/plugins` public entrypoint,
+- `definePlugin()` plugin definitions,
+- `defineModule()` named plugin bundles,
+- `createPluginHost()` lifecycle orchestration,
+- required and optional plugin dependencies,
+- deterministic topological dependency ordering,
+- dependency cycle and missing-dependency errors,
+- setup/start/stop/dispose lifecycle hooks,
+- reverse shutdown/disposal ordering,
+- startup rollback when a dependent plugin fails,
+- inspectable plugin runtime state,
+- plugin-local config parser/schema contract,
+- host-level config overrides,
+- shared string/Symbol service registry,
+- asynchronous in-process hook bus,
+- server-only browser boundary,
+- compiled `plugins.mjs` npm runtime,
+- unit and prepared-package smoke coverage.
+
+## Public API
+
+```ts
+import {
+    createPluginHookBus,
+    createPluginHost,
+    createPluginServiceRegistry,
+    defineModule,
+    definePlugin,
+    PluginDependencyError,
+    PluginLifecycleError,
+} from "bcp/plugins";
+```
+
+## Dependency lifecycle
+
+```text
+database
+   ↓
+jobs
+   ↓
+workflow
+```
+
+Startup follows dependency order. Stop/dispose runs in reverse order.
+
+If a plugin fails during startup, already-started plugins from that transition are stopped before the failure is propagated.
+
+## Modules
+
+Modules are composition bundles rather than a second runtime:
+
+```ts
+const backend =
+    defineModule({
+        name: "backend",
+        plugins: [
+            databasePlugin,
+            jobsPlugin,
+            workflowPlugin,
+        ],
+    });
+```
+
+All plugins still share one host-level dependency graph.
+
+## Configuration
+
+Plugin definitions can provide defaults and a parser/schema. `PluginHostOptions.configs` can override raw configuration per plugin before parsing.
+
+Invalid configuration fails at the plugin setup boundary.
+
+## Extension services
+
+`PluginServiceRegistry` provides explicit shared service lookup between plugins.
+
+`PluginHookBus` provides awaited in-process extension hooks. It is not a durable event system; `bcp/events` remains the durable integration-event platform.
+
+## Package/runtime contract
+
+The prepared npm package exposes:
+
+```text
+bcp/plugins
+  types   -> packages/client/src/plugins.ts
+  browser -> packages/client/src/server-only.browser.mjs
+  default -> packages/client/src/plugins.mjs
+```
+
+`plugins.mjs` is compiled during package preparation.
+
+## Compatibility
+
+`0.2.15` has no intentional breaking changes from `0.2.14`.
+
+Existing BCP entrypoints remain supported.
+
+## Validation
+
+Before publishing:
+
+```bash
+npm run typecheck
+npm run test:unit
+npm run test:integration
+npm run test:e2e
+npm run test:package
+npm run rc:check
+```
+
+Do not tag or publish until the exact final release commit passes the full RC sequence.

package/docs/releases/0.2.16.md

@@ -0,0 +1,147 @@
+# BCP Framework 0.2.16
+
+**State:** unreleased
+
+## Cache Platform v2
+
+`0.2.16` upgrades the existing `bcp/cache` public entrypoint with provider-neutral asynchronous cache storage, distributed lock contracts, Redis-compatible reference adapters, cache-stampede protection and metrics integration.
+
+The existing `cache()`, `dedupe()`, `revalidateTag()` and `revalidatePath()` APIs remain available with their previous process-local behavior.
+
+## New public APIs
+
+```ts
+createCacheStore()
+createMemoryCacheAdapter()
+createMemoryCacheLockAdapter()
+createRedisCacheAdapter()
+createRedisCacheLockAdapter()
+createCacheMetrics()
+```
+
+New public contracts include:
+
+```text
+CacheAdapter
+CacheAdapterEntry
+CacheAdapterSetOptions
+CacheLockAdapter
+CacheStore
+CacheStoreOptions
+CacheStoreSetOptions
+CacheGetOrSetOptions
+CacheStoreStats
+CacheMetricsSink
+CacheMetricsRegistryLike
+RedisCacheCommandClient
+RedisCacheAdapterOptions
+RedisCacheLockAdapterOptions
+```
+
+## Cache-aside loading
+
+`CacheStore.getOrSet()` provides a framework-native cache-aside primitive.
+
+Within one process it deduplicates concurrent loaders for the same key. With a shared `CacheLockAdapter`, multiple BCP instances coordinate cache fills through distributed leases.
+
+## Distributed lock behavior
+
+The built-in lock implementations support:
+
+- acquire with owner identity and TTL
+- compare-and-release
+- optional compare-and-extend
+- heartbeat renewal while a loader is active
+- contention wait/poll against shared cache state
+- explicit timeout failure with `onLockTimeout: "error"`
+- availability-oriented unlocked fallback by default after timeout
+
+Distributed locks reduce duplicate cache fill work. They are not a substitute for database transactions or uniqueness constraints protecting business invariants.
+
+## Redis-compatible adapters
+
+BCP still does not depend on a Redis package.
+
+Applications provide a minimal command client:
+
+```ts
+interface RedisCacheCommandClient {
+    sendCommand(
+        command: string[]
+    ): Promise<unknown>;
+}
+```
+
+The default namespace is `bcp:{cache}` so related keys share a Redis Cluster hash slot.
+
+The reference adapter uses Lua for record/index changes, tag invalidation, lock release and lock renewal.
+
+Applications remain responsible for Redis authentication, TLS, Cluster/Sentinel configuration, reconnect behavior and connection shutdown.
+
+## TTL and invalidation
+
+Cache Store v2 supports:
+
+- millisecond TTL via `ttlMs`
+- tag invalidation
+- hierarchical path invalidation
+- adapter-wide clear
+- optional provider entry counts
+
+The older `cache()` API continues to accept `revalidate` in seconds for compatibility.
+
+## Observability
+
+`createCacheMetrics()` adapts Cache Store events to `bcp/observability`'s existing `MetricsRegistry` contract.
+
+Default metric families:
+
+```text
+bcp_cache_operations_total{event="..."}
+bcp_cache_in_flight
+```
+
+## Published runtime
+
+The prepared npm package now compiles `bcp/cache` to:
+
+```text
+packages/client/src/cache.mjs
+```
+
+The prepared package export points runtime imports at this compiled file while preserving `cache.ts` as the public type source.
+
+## Testing
+
+The `0.2.16` suite adds coverage for:
+
+- TTL expiration
+- tag/path invalidation
+- store statistics
+- local in-flight deduplication
+- cross-store distributed stampede protection
+- lock timeout errors
+- BCP metrics registry integration
+- Redis command/namespace contract
+- compiled prepared-package runtime smoke
+
+## Compatibility
+
+`0.2.16` has no intentional breaking changes from `0.2.15`.
+
+Existing application calls using the original cache APIs do not need to migrate.
+
+## Release validation
+
+Before publishing:
+
+```bash
+npm run typecheck
+npm run test:unit
+npm run test:integration
+npm run test:e2e
+npm run test:package
+npm run rc:check
+```
+
+Tag and publish only the exact commit that passes the complete RC sequence.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chidchanun/bcp",
-  "version": "0.2.14",
+  "version": "0.2.16",
   "description": "BCP Framework - a React full-stack framework with file-based routing, SSR, APIs, middleware, islands, caching and standalone production builds.",
   "type": "module",
   "license": "MIT",
@@ -38,7 +38,7 @@
     },
     "./cache": {
       "types": "./packages/client/src/cache.ts",
-      "default": "./packages/client/src/cache.ts"
+      "default": "./packages/client/src/cache.mjs"
     },
     "./config": {
       "types": "./packages/client/src/config.ts",
@@ -87,6 +87,11 @@
       "browser": "./packages/client/src/server-only.browser.mjs",
       "default": "./packages/client/src/testing.mjs"
     },
+    "./plugins": {
+      "types": "./packages/client/src/plugins.ts",
+      "browser": "./packages/client/src/server-only.browser.mjs",
+      "default": "./packages/client/src/plugins.mjs"
+    },
     "./observability": {
       "types": "./packages/client/src/observability.ts",
       "browser": "./packages/client/src/server-only.browser.mjs",

package/packages/bundler/src/client-boundary.ts

@@ -33,6 +33,7 @@ const SERVER_ONLY_IMPORTS =
         "bcp/events",
         "bcp/realtime",
         "bcp/testing",
+        "bcp/plugins",
         "bcp/observability",
     ]);