create-bcp-app 0.2.6 → 0.2.8

package/README.md

@@ -92,10 +92,10 @@ Example:
   "schemaVersion": 1,
   "framework": "bcp",
   "projectName": "my-app",
-  "frameworkPackage": "npm:@chidchanun/bcp@0.2.6",
+  "frameworkPackage": "npm:@chidchanun/bcp@0.2.8",
   "createdWith": {
     "package": "create-bcp-app",
-    "version": "0.2.6"
+    "version": "0.2.8"
   },
   "packageManager": "npm",
   "presets": {
@@ -326,6 +326,74 @@ import {
 
 Authorization and CSRF checks must remain on the server; hiding UI controls in client code is not an authorization boundary.
 
+## Observability — 0.2.7+
+
+Generated projects can opt into process-local metrics and health/readiness without adding another dependency:
+
+```ts
+import {
+    createHealthRegistry,
+    createMetricsRegistry,
+    createRequestMetricsMiddleware,
+} from "bcp/observability";
+
+export const metrics =
+    createMetricsRegistry();
+
+export const health =
+    createHealthRegistry();
+
+export const requestMetrics =
+    createRequestMetricsMiddleware(
+        metrics
+    );
+```
+
+Expose metrics from an application API route with `createMetricsResponse(metrics)`. The response uses Prometheus-compatible text format.
+
+Health endpoints can return `health.response()`, which uses HTTP `200` when all checks pass and `503` when any dependency check fails or times out.
+
+The default HTTP request metrics use `method` and `status` labels only. Raw paths are intentionally excluded to avoid high-cardinality metric series.
+
+`bcp/observability` is server-only. Protect metrics and operational health detail with an appropriate network or authorization boundary when needed.
+
+## Background jobs — 0.2.8+
+
+Generated projects can create a server-only background job queue without adding another package:
+
+```ts
+import {
+    createJobQueue,
+} from "bcp/jobs";
+
+export const jobs =
+    createJobQueue();
+```
+
+Register handlers and enqueue work:
+
+```ts
+jobs.register(
+    "email.welcome",
+    async ({ payload }) => {
+        await sendWelcomeEmail(
+            payload.userId
+        );
+    }
+);
+
+await jobs.enqueue(
+    "email.welcome",
+    {
+        userId: 42,
+    }
+);
+```
+
+Workers support concurrency, delayed jobs, retry/backoff and cancellation. The default memory adapter is process-local and should be replaced with a durable `JobQueueAdapter` for multi-process/container production workloads that must survive restarts.
+
+`bcp/jobs` is server-only and must not be imported into page/client bundles.
+
 ## Application Packaging — 0.2.4+
 
 Generated projects include:
@@ -407,5 +475,5 @@ npx create-bcp-app my-app --yes
 The `--bcp` option is mainly for prerelease/local package verification:
 
 ```bash
-npx create-bcp-app my-app --bcp file:../chidchanun-bcp-0.2.6.tgz
+npx create-bcp-app my-app --bcp file:../chidchanun-bcp-0.2.8.tgz
 ```

package/package.json

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

package/template/README.md

@@ -94,6 +94,76 @@ import {
 
 Authorization must always be enforced server-side. Client UI visibility is not a security boundary.
 
+## Observability — BCP 0.2.7+
+
+Create process-local metrics and health/readiness registries:
+
+```ts
+import {
+    createHealthRegistry,
+    createMetricsRegistry,
+    createRequestMetricsMiddleware,
+} from "bcp/observability";
+
+export const metrics =
+    createMetricsRegistry();
+
+export const health =
+    createHealthRegistry();
+
+export const requestMetrics =
+    createRequestMetricsMiddleware(
+        metrics
+    );
+```
+
+Expose Prometheus-compatible metrics with `createMetricsResponse(metrics)` from a server API route.
+
+Use `health.response()` for readiness endpoints. It returns HTTP `200` when all checks pass and `503` when a check fails or times out.
+
+The default request metrics use bounded `method` and `status` labels and do not include raw paths.
+
+Protect operational endpoints when their contents should not be public.
+
+## Background jobs — BCP 0.2.8+
+
+Create a server-only background queue:
+
+```ts
+import {
+    createJobQueue,
+} from "bcp/jobs";
+
+export const jobs =
+    createJobQueue();
+```
+
+Register and enqueue work:
+
+```ts
+jobs.register(
+    "email.welcome",
+    async ({ payload }) => {
+        await sendWelcomeEmail(
+            payload.userId
+        );
+    }
+);
+
+await jobs.enqueue(
+    "email.welcome",
+    {
+        userId: 42,
+    }
+);
+```
+
+Workers support delayed jobs, retry/backoff, cancellation and configurable concurrency.
+
+The default memory adapter is process-local and not durable. For production jobs that must survive restarts or run across multiple processes/containers, implement `JobQueueAdapter` with shared durable infrastructure.
+
+`bcp/jobs` is server-only and cannot be imported into page/client bundles.
+
 ## Generate framework files
 
 BCP can generate common project files: