@bloomneo/appkit 1.2.9 → 1.5.2

package/dist/util/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/util/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,MAAM,SAAS,GAAG,wDAAwD,CAAC;AAE3E,MAAM,OAAO,WAAY,SAAQ,KAAK;IAC3B,MAAM,CAAS;IACf,OAAO,CAAS;IAEzB,YAAY,MAAc,EAAE,OAAe,EAAE,IAAa;QACxD,MAAM,GAAG,GAAG,IAAI,CAAC,CAAC,CAAC,GAAG,SAAS,IAAI,IAAI,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;QACtD,KAAK,CAAC,sBAAsB,MAAM,KAAK,OAAO,UAAU,GAAG,EAAE,CAAC,CAAC;QAC/D,IAAI,CAAC,IAAI,GAAG,aAAa,CAAC;QAC1B,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,OAAO,GAAG,GAAG,CAAC;IACrB,CAAC;CACF;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,UAAU,CAAC,MAAc,EAAE,OAAe,EAAE,IAAa;IACvE,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IACnC,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,EAAE,EAAE,CAAC;QACxC,MAAM,GAAG,GAAG,IAAI;YACd,CAAC,CAAC,sBAAsB,OAAO,iBAAiB,IAAI,EAAE;YACtD,CAAC,CAAC,sBAAsB,OAAO,eAAe,CAAC;QACjD,MAAM,IAAI,WAAW,CAAC,MAAM,EAAE,GAAG,EAAE,uBAAuB,CAAC,CAAC;IAC9D,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,WAAW,CACzB,MAAc,EACd,IAAY,EACZ,KAA2B,EAC3B,IAAa;IAEb,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QAC1C,MAAM,GAAG,GAAG,IAAI;YACd,CAAC,CAAC,KAAK,IAAI,mBAAmB,IAAI,EAAE;YACpC,CAAC,CAAC,KAAK,IAAI,iBAAiB,CAAC;QAC/B,MAAM,IAAI,WAAW,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IACrC,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,SAAS,CAAC,MAAc,EAAE,OAAe,EAAE,IAAa;IACtE,IAAI,OAAO,CAAC,GAAG,CAAC,QAAQ,KAAK,YAAY;QAAE,OAAO;IAClD,MAAM,GAAG,GAAG,IAAI,CAAC,CAAC,CAAC,GAAG,SAAS,IAAI,IAAI,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;IACtD,sCAAsC;IACtC,OAAO,CAAC,IAAI,CAAC,sBAAsB,MAAM,KAAK,OAAO,UAAU,GAAG,EAAE,CAAC,CAAC;AACxE,CAAC"}

package/dist/util/util.js

@@ -152,7 +152,7 @@ export class UtilClass {
         }
         // Performance warning for large arrays
         if (this.config.performance.enabled && array.length > this.config.performance.chunkSizeLimit) {
-            console.warn(`[VoilaJSX Utils] Chunking large array (${array.length} items). Consider streaming or pagination.`);
+            console.warn(`[Bloomneo Utils] Chunking large array (${array.length} items). Consider streaming or pagination.`);
         }
         const result = [];
         for (let i = 0; i < array.length; i += size) {

package/examples/.env.example

@@ -0,0 +1,80 @@
+# Bloomneo AppKit — canonical environment template
+#
+# Copy this to `.env` in your project root and fill in real values.
+# All env vars use the BLOOM_ prefix. The legacy VOILA_ prefix from
+# @voilajsx/appkit was removed in 1.5.2 — there is no fallback.
+#
+# Generate secrets with: openssl rand -base64 32
+
+# ──────────────────────────────────────────────────────────────────────
+# REQUIRED for production
+# ──────────────────────────────────────────────────────────────────────
+
+# JWT signing key for authClass.get().signToken() / verifyToken()
+# Minimum 32 characters.
+BLOOM_AUTH_SECRET=replace-me-with-openssl-rand-base64-32
+
+# Prisma connection string. Any Prisma-supported URL works.
+DATABASE_URL=postgresql://user:pass@localhost:5432/myapp
+
+# CSRF token signing for securityClass.get().csrf() / requireCsrf()
+# Minimum 32 characters.
+BLOOM_SECURITY_CSRF_SECRET=replace-me-with-openssl-rand-base64-32
+
+# AES-256-GCM encryption key for securityClass.get().encrypt() / decrypt()
+# Exactly 64 hex characters (32 bytes).
+BLOOM_SECURITY_ENCRYPTION_KEY=replace-me-with-openssl-rand-hex-32
+
+# ──────────────────────────────────────────────────────────────────────
+# OPTIONAL — auto-scaling kicks in when set
+# ──────────────────────────────────────────────────────────────────────
+
+# Distributed cache + queue + events (memory by default)
+# REDIS_URL=redis://localhost:6379
+
+# Cloud storage (local disk by default)
+# AWS_S3_BUCKET=my-bucket
+# AWS_REGION=us-east-1
+# AWS_ACCESS_KEY_ID=...
+# AWS_SECRET_ACCESS_KEY=...
+
+# Cloudflare R2 (alternative to S3)
+# R2_BUCKET=my-bucket
+# R2_ACCOUNT_ID=...
+# R2_ACCESS_KEY_ID=...
+# R2_SECRET_ACCESS_KEY=...
+
+# Production email (console transport by default)
+# RESEND_API_KEY=re_...
+# or
+# SMTP_HOST=smtp.example.com
+# SMTP_PORT=587
+# SMTP_USER=...
+# SMTP_PASS=...
+
+# Multi-tenant database filtering
+# When set to "auto", database queries auto-filter by tenant_id.
+# BLOOM_DB_TENANT=auto
+
+# Per-organization databases (multi-org SaaS)
+# Each ORG_<NAME> is a separate connection string used by databaseClass.org('<name>').get()
+# ORG_ACME=postgresql://acme.aws.com/prod
+# ORG_GLOBEX=postgresql://globex.aws.com/prod
+
+# Background queue persistence (memory by default)
+# BLOOM_QUEUE_DB=true   # use database-backed queue when REDIS_URL not set
+
+# Logger transports
+# BLOOM_LOGGER_FILE_PATH=/var/log/myapp.log
+# BLOOM_LOGGER_HTTP_URL=https://logs.example.com/ingest
+# BLOOM_LOGGER_WEBHOOK_URL=https://hooks.slack.com/services/...
+
+# Service identification (used by logger metadata)
+# BLOOM_SERVICE_NAME=myapp
+# BLOOM_SERVICE_VERSION=1.0.0
+
+# Default user password for seeds (development only)
+# DEFAULT_USER_PASSWORD=changeme123
+
+# Frontend API key (for browser → API auth — generated by `appkit generate app`)
+# BLOOM_FRONTEND_KEY=bloom_<random>

package/examples/README.md

@@ -0,0 +1,16 @@
+# Examples
+
+One minimal `.ts` file per module. Each example is the smallest runnable shape
+of the canonical pattern — copy, modify the data, ship.
+
+For composed multi-module patterns (auth-protected CRUD, multi-tenant API,
+file upload + queue, real-time chat), see [`../cookbook/`](../cookbook/).
+
+## Conventions
+
+- Always import from `@bloomneo/appkit` (or the subpath form).
+- Always use `xxxClass.get()` to obtain a module instance.
+- Always cache the module instance at module scope, not inside route handlers.
+- Use semantic error throwers (`error.badRequest()`, `error.unauthorized()`),
+  never `throw new Error(...)` in route handlers.
+- See [`.env.example`](./.env.example) for the canonical environment template.

package/examples/auth.ts

@@ -0,0 +1,228 @@
+/**
+ * CANONICAL PATTERN — JWT auth with role-based middleware.
+ *
+ * Verified against src/auth/README.md (lines 426-479: API Reference)
+ * and src/auth/auth.ts (real public method signatures).
+ *
+ * Two token types: LOGIN tokens for users, API tokens for services.
+ * Middleware chains: `requireLoginToken()` FIRST, then `requireUserRoles()`
+ * — never the reverse, never standalone, never with API tokens.
+ *
+ * Required env: BLOOM_AUTH_SECRET (min 32 chars)
+ */
+
+import { authClass } from '@bloomneo/appkit/auth';
+import type {
+  ExpressRequest,
+  ExpressResponse,
+  ExpressMiddleware,
+} from '@bloomneo/appkit/auth';
+
+const auth = authClass.get();
+
+// ── Token generation ────────────────────────────────────────────────
+
+// Login token: for human users (web/mobile login). 7-day expiry typical.
+const loginToken: string = auth.generateLoginToken(
+  {
+    userId: 123,
+    role: 'user',
+    level: 'basic',
+  },
+  '7d',
+);
+
+// API token: for services / webhooks / integrations. 1-year expiry typical.
+//
+// IMPORTANT: the role.level you pass MUST exist in the configured role
+// hierarchy or generateApiToken throws "Invalid role.level". The default
+// hierarchy ships with `user.basic` → `admin.system` (9 user roles, no
+// service roles). For service tokens you have two options:
+//
+//   1. Use one of the default roles (e.g. `admin.system`) — what we do here.
+//   2. Register custom service roles via the BLOOM_AUTH_ROLES env var, e.g.
+//      BLOOM_AUTH_ROLES=user.basic:1,...,service.webhook:10
+//      and then pass `role: 'service', level: 'webhook'` here.
+//
+// Option 1 is simpler when the API token holder needs full system access.
+// Option 2 is correct when you want narrower scopes for different services.
+const apiToken: string = auth.generateApiToken(
+  {
+    keyId: 'webhook_payment_service',
+    role: 'admin',
+    level: 'system',
+  },
+  '1y',
+);
+
+// ── Middleware (use these in route definitions) ─────────────────────
+
+// 1. Authenticate ANY logged-in user
+const protectAuthenticated: ExpressMiddleware = auth.requireLoginToken();
+
+// 2. Require specific user role (chained AFTER requireLoginToken)
+const requireAdmin: ExpressMiddleware = auth.requireUserRoles(['admin.tenant']);
+
+// 3. Require any of multiple roles (OR semantics)
+const requireAdminOrOrg: ExpressMiddleware = auth.requireUserRoles([
+  'admin.tenant',
+  'admin.org',
+]);
+
+// 4. Require specific permissions (AND semantics across the array)
+const requireUserManagement: ExpressMiddleware = auth.requireUserPermissions([
+  'manage:users',
+  'edit:tenant',
+]);
+
+// 5. API token authentication (services only — DO NOT chain with requireUserRoles)
+const protectApi: ExpressMiddleware = auth.requireApiToken();
+
+// ── Route handlers (called by Express after middleware passes) ──────
+
+// Login handler: bcrypt check + token issue
+async function loginHandler(req: ExpressRequest, res: ExpressResponse) {
+  const { email, password } = (req.body ?? {}) as { email?: string; password?: string };
+
+  // Look up the user from your database. Placeholder.
+  const user = {
+    id: 1,
+    email,
+    passwordHash: '$2b$10$placeholder',
+    role: 'user',
+    level: 'basic',
+  };
+
+  const valid = await auth.comparePassword(password ?? '', user.passwordHash);
+  if (!valid) {
+    res.status?.(401).json?.({ error: 'Invalid credentials' });
+    return;
+  }
+
+  const token = auth.generateLoginToken({
+    userId: user.id,
+    role: user.role,
+    level: user.level,
+  });
+
+  res.json?.({ token });
+}
+
+// Registration handler: bcrypt hash + token issue
+async function registerHandler(req: ExpressRequest, res: ExpressResponse) {
+  const { email, password } = (req.body ?? {}) as { email?: string; password?: string };
+  const hashedPassword = await auth.hashPassword(password ?? '');
+  // Save { email, password: hashedPassword } to your database. Placeholder.
+  void hashedPassword;
+  void email;
+  const newUserId = 42;
+
+  const token = auth.generateLoginToken({
+    userId: newUserId,
+    role: 'user',
+    level: 'basic',
+  });
+
+  res.json?.({ token });
+}
+
+// Authenticated handler: extract user safely from req
+function profileHandler(req: ExpressRequest, res: ExpressResponse) {
+  const user = auth.user(req);  // null-safe; non-null after requireLoginToken
+  if (!user) {
+    res.status?.(401).json?.({ error: 'Not authenticated' });
+    return;
+  }
+  res.json?.({ user });
+}
+
+// ── Programmatic role hierarchy check (outside middleware) ──────────
+
+const orgIncludesTenant: boolean = auth.hasRole('admin.org', 'admin.tenant');  // true
+const userIsAdmin: boolean = auth.hasRole('user.basic', 'admin.tenant');       // false
+
+// ── Verify a token manually (outside middleware) ────────────────────
+//
+// `verifyToken` is what the middleware uses internally. You normally don't
+// call it yourself — `requireLoginToken()` and `requireApiToken()` handle
+// it for you. Use this only when you need to validate a token in a
+// non-Express context (e.g. WebSocket auth, queue worker auth, scheduled
+// task auth). Throws on bad token; never returns null.
+function verifyTokenManually(rawToken: string) {
+  try {
+    const payload = auth.verifyToken(rawToken);
+    // payload.userId is set for login tokens; payload.keyId is set for API tokens.
+    // payload.type tells you which: 'login' or 'api_key'.
+    return payload;
+  } catch (e) {
+    // Possible messages: 'Token has expired', 'Invalid token',
+    // 'Token must be a string', 'Token verification failed: ...'
+    return null;
+  }
+}
+
+// ── Permission check with inheritance (auth.can) ────────────────────
+//
+// `can` checks fine-grained permissions on a user payload. Permission format
+// is `action:scope` (e.g. 'edit:tenant', 'manage:users'). Inheritance rule:
+// `manage:scope` automatically grants `view:scope`, `edit:scope`,
+// `delete:scope`, etc. for the same scope.
+//
+// Use this inside a route handler AFTER `requireLoginToken()` middleware
+// has validated the user and attached the payload.
+function permissionCheckHandler(req: ExpressRequest, res: ExpressResponse) {
+  const user = auth.user(req);
+  if (!user) {
+    res.status?.(401).json?.({ error: 'Not authenticated' });
+    return;
+  }
+
+  // Check if the user can edit their tenant. Returns true if the user has
+  // 'edit:tenant' OR 'manage:tenant' (manage inherits all actions).
+  const canEdit: boolean = auth.can(user, 'edit:tenant');
+  if (!canEdit) {
+    res.status?.(403).json?.({ error: 'Cannot edit tenant' });
+    return;
+  }
+
+  res.json?.({ allowed: true });
+}
+
+// ── Express wiring (commented — uncomment in your app) ──────────────
+//
+//   import express from 'express';
+//   const app = express();
+//
+//   app.post('/login', loginHandler);
+//   app.post('/register', registerHandler);
+//
+//   // User route: login + role required
+//   app.get(
+//     '/admin/users',
+//     auth.requireLoginToken(),
+//     auth.requireUserRoles(['admin.tenant']),
+//     profileHandler,
+//   );
+//
+//   // API route: API token only (no user roles)
+//   app.post('/webhook/payment', auth.requireApiToken(), (req, res) => {
+//     res.json({ ok: true });
+//   });
+
+export {
+  auth,
+  loginToken,
+  apiToken,
+  protectAuthenticated,
+  requireAdmin,
+  requireAdminOrOrg,
+  requireUserManagement,
+  protectApi,
+  verifyTokenManually,
+  permissionCheckHandler,
+  loginHandler,
+  registerHandler,
+  profileHandler,
+  orgIncludesTenant,
+  userIsAdmin,
+};

package/examples/cache.ts

@@ -0,0 +1,36 @@
+/**
+ * CANONICAL PATTERN — cache.getOrSet for "fetch once, cache the result".
+ *
+ * Copy this file when you need to cache anything. The getOrSet pattern is
+ * the right answer 90% of the time — never write the cache-check-then-fetch
+ * pattern manually.
+ *
+ * Set REDIS_URL in .env to upgrade from in-process memory to distributed
+ * Redis cache. Same code works for both — no changes needed.
+ */
+
+import { cacheClass, databaseClass, errorClass } from '@bloomneo/appkit';
+
+const error = errorClass.get();
+const database = await databaseClass.get();
+
+// Custom namespace isolates this cache from others (default is 'app').
+const cache = cacheClass.get('users');
+
+// ── Cached database query ─────────────────────────────────────────────
+export const listProductsRoute = error.asyncRoute(async (req, res) => {
+  const products = await cache.getOrSet(
+    'products:list',
+    () => database.product.findMany({ where: { published: true } }),
+    300, // 5 minutes
+  );
+  res.json({ products });
+});
+
+// ── Manual operations (use sparingly — getOrSet is preferred) ────────
+export async function manualCacheExample() {
+  await cache.set('foo', 'bar', 60);                       // 1 minute TTL
+  const v = await cache.get('foo');                        // → 'bar'
+  const exists = v !== null;                               // presence check: get() returns null on miss
+  await cache.delete('foo');                               // delete() — not del()
+}

package/examples/config.ts

@@ -0,0 +1,45 @@
+/**
+ * CANONICAL PATTERN — type-safe environment variable access.
+ *
+ * Copy this file when you need to read configuration. Always go through
+ * configClass.get() instead of touching process.env directly — config
+ * validates types, provides defaults, and supports the BLOOM_* prefix
+ * convention.
+ *
+ * Read AGENTS.md for the full env var reference.
+ */
+
+import { configClass } from '@bloomneo/appkit';
+
+const config = configClass.get();
+
+// ── Read string config (with default) ───────────────────────────────
+const apiHost = config.get('api.host', 'localhost');
+const dbUrl = config.get('database.url');                  // throws if not set
+
+// ── Read typed config ───────────────────────────────────────────────
+// config.get() returns the value as-is. Cast to number/boolean yourself.
+const port = Number(config.get('api.port') ?? 3000);
+const debugMode = config.get('app.debug') === 'true';
+
+// ── Environment detection ───────────────────────────────────────────
+// isDevelopment() / isProduction() / isTest() live on configClass, NOT on the
+// instance returned by configClass.get(). Always call them via configClass.*.
+if (configClass.isDevelopment()) {
+  console.log('Running in dev mode');
+}
+if (configClass.isProduction()) {
+  // tighter security defaults, etc.
+}
+
+// ── Validate required env vars at startup ───────────────────────────
+// Call this once in your server bootstrap. Throws with a clear error message
+// listing every missing variable.
+config.validateRequired([
+  'BLOOM_AUTH_SECRET',
+  'DATABASE_URL',
+  'BLOOM_SECURITY_CSRF_SECRET',
+  'BLOOM_SECURITY_ENCRYPTION_KEY',
+]);
+
+export { config, apiHost, dbUrl, port, debugMode };

package/examples/database.ts

@@ -0,0 +1,69 @@
+/**
+ * CANONICAL PATTERN — multi-tenant database access.
+ *
+ * Verified against src/database/README.md (Core API + LLM Guidelines sections)
+ * and src/database/index.ts.
+ *
+ * Three core methods:
+ *   • databaseClass.get()         → tenant-aware client (single user mode)
+ *   • databaseClass.getTenants()  → unfiltered client (admin / cross-tenant)
+ *   • databaseClass.org('name').get() / .getTenants() → per-org databases
+ *
+ * Required env: DATABASE_URL
+ * Optional env: BLOOM_DB_TENANT=auto (enables multi-tenant filtering)
+ */
+
+import { databaseClass } from '@bloomneo/appkit/database';
+
+// ── Normal user access (auto-filtered by tenant when BLOOM_DB_TENANT=auto) ──
+async function listUsers() {
+  const database = await databaseClass.get();
+  // Returns only rows belonging to the current tenant.
+  // The shape of `database.user` matches your Prisma / Mongoose model.
+  // Placeholder query — replace with your actual model.
+  const users = await (database as any).user?.findMany?.() ?? [];
+  return users;
+}
+
+// ── Admin: cross-tenant query (unfiltered) ──────────────────────────
+async function listAllUsersAcrossTenants() {
+  const dbTenants = await databaseClass.getTenants();
+  const allUsers = await (dbTenants as any).user?.findMany?.() ?? [];
+  return allUsers;
+}
+
+// ── Admin: per-tenant analytics ─────────────────────────────────────
+async function tenantAnalytics() {
+  const dbTenants = await databaseClass.getTenants();
+  const stats = await (dbTenants as any).user?.groupBy?.({
+    by: ['tenant_id'],
+    _count: { _all: true },
+  }) ?? [];
+  return stats;
+}
+
+// ── Multi-org: per-organization database ────────────────────────────
+// Set ORG_ACME=postgresql://acme.aws.com/prod in .env, then:
+async function listAcmeUsers() {
+  const acmedatabase = await databaseClass.org('acme').get();
+  const users = await (acmedatabase as any).user?.findMany?.() ?? [];
+  return users;
+}
+
+// ── Multi-org admin: all tenants in a single org ────────────────────
+async function acmeTenantStats() {
+  const acmeDbTenants = await databaseClass.org('acme').getTenants();
+  const stats = await (acmeDbTenants as any).user?.groupBy?.({
+    by: ['tenant_id'],
+    _count: { _all: true },
+  }) ?? [];
+  return stats;
+}
+
+export {
+  listUsers,
+  listAllUsersAcrossTenants,
+  tenantAnalytics,
+  listAcmeUsers,
+  acmeTenantStats,
+};

package/examples/email.ts

@@ -0,0 +1,53 @@
+/**
+ * CANONICAL PATTERN — send email with auto-scaling provider.
+ *
+ * Copy this file when you need to send email. Default is console (logs to
+ * terminal — perfect for development). Set SMTP_HOST + SMTP_USER + SMTP_PASS
+ * to use SMTP. Set RESEND_API_KEY to use Resend.
+ *
+ * Same code works for all three providers — no changes needed.
+ */
+
+import { emailClass, errorClass } from '@bloomneo/appkit';
+
+const email = emailClass.get();
+const error = errorClass.get();
+
+// ── Plain text email ────────────────────────────────────────────────
+export async function sendWelcomeEmail(toAddress: string, userName: string) {
+  await email.send({
+    to: toAddress,
+    subject: 'Welcome to MyApp',
+    text: `Hi ${userName},\n\nThanks for signing up!\n\n— The Team`,
+  });
+}
+
+// ── HTML email with plain-text fallback ─────────────────────────────
+export async function sendInvoiceEmail(toAddress: string, invoiceUrl: string) {
+  await email.send({
+    to: toAddress,
+    subject: 'Your invoice is ready',
+    text: `Your invoice: ${invoiceUrl}`,
+    html: `<p>Your invoice: <a href="${invoiceUrl}">${invoiceUrl}</a></p>`,
+  });
+}
+
+// ── Templated email ─────────────────────────────────────────────────
+// EmailData (used by email.send()) only accepts: to, from, subject, text,
+// html, attachments, replyTo, cc, bcc — it has no template/data fields.
+// Use email.sendTemplate() for template-driven emails.
+export async function sendPasswordResetEmail(toAddress: string, resetLink: string) {
+  await email.sendTemplate('password-reset', {
+    to: toAddress,
+    resetLink,
+    expiresIn: '1 hour',
+  });
+}
+
+// ── Inside a route handler ──────────────────────────────────────────
+export const sendNotificationRoute = error.asyncRoute(async (req, res) => {
+  const { to, message } = req.body;
+  if (!to || !message) throw error.badRequest('to and message required');
+  await email.send({ to, subject: 'Notification', text: message });
+  res.json({ sent: true });
+});

package/examples/error.ts

@@ -0,0 +1,50 @@
+/**
+ * CANONICAL PATTERN — semantic HTTP errors + centralized middleware.
+ *
+ * Copy this file when you need error handling in routes. The pattern:
+ *   1. Wrap async route handlers in error.asyncRoute(...)
+ *   2. Throw semantic errors (badRequest, unauthorized, notFound, etc.)
+ *      — never `throw new Error(...)` in route handlers
+ *   3. Mount error.handleErrors() as the LAST middleware in the Express stack
+ *
+ * The asyncRoute wrapper catches the throw, and handleErrors() converts
+ * the semantic error into the right HTTP status + JSON response.
+ */
+
+import express from 'express';
+import { errorClass, databaseClass } from '@bloomneo/appkit';
+
+const error = errorClass.get();
+const database = await databaseClass.get();
+const app = express();
+
+// ── Routes use asyncRoute + semantic error throws ───────────────────
+app.get('/api/users/:id', error.asyncRoute(async (req, res) => {
+  const id = Number(req.params.id);
+  if (!Number.isFinite(id)) throw error.badRequest('id must be a number');
+
+  const user = await database.user.findUnique({ where: { id } });
+  if (!user) throw error.notFound('User not found');
+
+  res.json({ user });
+}));
+
+app.post('/api/admin', error.asyncRoute(async (req, res) => {
+  if (req.body.role !== 'admin') throw error.forbidden('Admin role required');
+  // ...
+}));
+
+// ── Available semantic error throwers ───────────────────────────────
+//
+//   throw error.badRequest('message')        → 400
+//   throw error.unauthorized('message')      → 401
+//   throw error.forbidden('message')         → 403
+//   throw error.notFound('message')          → 404
+//   throw error.conflict('message')          → 409
+//   throw error.tooMany('message')           → 429  (rate limiting)
+//   throw error.serverError('message')       → 500
+//   throw error.internal('message')          → 500  (alias for serverError)
+//   throw error.createError(503, 'message')  → any code
+
+// ── MOUNT error.handleErrors() LAST in the middleware stack ─────────
+app.use(error.handleErrors());

package/examples/event.ts

@@ -0,0 +1,42 @@
+/**
+ * CANONICAL PATTERN — pub/sub events with auto-scaling backend.
+ *
+ * Copy this file when you need events. Default is in-process memory (single
+ * Node process). Set REDIS_URL to distribute events across processes / servers
+ * — same code works in both modes.
+ *
+ * Use namespaces (eventClass.get('users')) to isolate event streams.
+ */
+
+import { eventClass, loggerClass } from '@bloomneo/appkit';
+
+const events = eventClass.get('users');  // namespaced
+const logger = loggerClass.get('events');
+
+// ── Subscribe to a single event ─────────────────────────────────────
+events.on('user.created', async (data) => {
+  logger.info('New user', { userId: data.userId });
+  // ...trigger welcome email, analytics, etc.
+});
+
+// ── Subscribe to a wildcard pattern ─────────────────────────────────
+events.on('user.*', async (eventName, data) => {
+  logger.debug(`User event: ${eventName}`, data);
+});
+
+// ── Emit an event from a route handler ──────────────────────────────
+import { errorClass } from '@bloomneo/appkit';
+const error = errorClass.get();
+
+export const createUserRoute = error.asyncRoute(async (req, res) => {
+  // ...create the user in the database
+  const newUser = { id: 123, email: req.body.email };
+
+  await events.emit('user.created', {
+    userId: newUser.id,
+    email: newUser.email,
+    timestamp: new Date(),
+  });
+
+  res.json({ user: newUser });
+});