@getstrata/core 2.0.3 → 2.0.4

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # @getstrata/core changelog
 
+## 2.0.4
+
+- Place cache rollout guidance beside outbox docs without overlapping API additions
+
 ## 2.0.3
 
 - Persist transactional events with leased tenant-aware SQL outbox workers

package/dist/core/database/baseRepository.d.ts

@@ -21,6 +21,8 @@ declare class BaseRepository<TEntity extends object, PrimaryKey extends keyof TE
     protected readonly table: TableDefinition<TEntity, PrimaryKey>;
     protected readonly connection: DatabaseConnection;
     constructor(table: TableDefinition<TEntity, PrimaryKey>, connection?: DatabaseConnection);
+    private assertTransactionalEvent;
+    private runModelMutation;
     count(options?: ExtendedQueryOptions<TEntity>): Promise<number>;
     findAll(options?: ExtendedQueryOptions<TEntity>): Promise<TEntity[]>;
     paginate(options: {

package/dist/core/events/eventBus.d.ts

@@ -1,6 +1,10 @@
 type EventListener = (payload: unknown) => void | Promise<void>;
 declare class EventBus {
     constructor();
+    private readonly transactionalListeners;
+    listenTransactional(event: string, listener: EventListener): () => void;
+    hasTransactionalListeners(event: string): boolean;
+    dispatchTransactional(event: string, payload: unknown): Promise<void>;
     private readonly listeners;
     on(event: string, listener: EventListener): () => void;
     listen(event: string, listener: EventListener): () => void;

package/dist/core/events/outbox/index.d.ts

@@ -30,6 +30,7 @@ declare class SqlOutbox {
     private readonly maxPayloadBytes;
     private readonly tenantResolver;
     constructor(options: SqlOutboxOptions);
+    hasListener(name: string, event?: string): boolean;
     publish(name: string, payload: unknown, options?: {
         id?: string;
         version?: number;

package/dist/core/openapi/registeredRoute.d.ts

@@ -1,6 +1,45 @@
+/** JSON Schema keywords remain extensible; metadata cannot contain executable values. */
+type OpenApiJson = null | boolean | number | string | OpenApiJson[] | {
+    [key: string]: OpenApiJson | undefined;
+};
+type OpenApiSchema = boolean | {
+    [keyword: string]: OpenApiJson | undefined;
+};
+interface OpenApiParameter {
+    name: string;
+    in: "header" | "query" | "path" | "cookie";
+    required?: boolean;
+    description?: string;
+    schema: OpenApiSchema;
+}
+interface OpenApiMediaType {
+    schema?: OpenApiSchema;
+    example?: OpenApiJson;
+}
+interface OpenApiResponse {
+    description: string;
+    content?: Record<string, OpenApiMediaType>;
+}
+interface OpenApiOperation {
+    summary?: string;
+    description?: string;
+    operationId?: string;
+    tags?: string[];
+    deprecated?: boolean;
+    parameters?: OpenApiParameter[];
+    requestBody?: {
+        required?: boolean;
+        description?: string;
+        content: Record<string, OpenApiMediaType>;
+    };
+    responses?: Record<string, OpenApiResponse>;
+    security?: Array<Record<string, string[]>>;
+}
+type OpenApiRouteMap = Record<string, Partial<Record<"GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS", OpenApiOperation>>>;
 interface RegisteredRoute {
     method: string;
     path: string;
     middleware: string[];
+    openApi?: OpenApiOperation;
 }
-export type { RegisteredRoute };
+export type { OpenApiJson, OpenApiMediaType, OpenApiOperation, OpenApiParameter, OpenApiResponse, OpenApiRouteMap, OpenApiSchema, RegisteredRoute, };

package/dist/entries/audit/exportAuditLogs.js

@@ -58,6 +58,24 @@ var init_tenantContext = __esm(() => {
 // ../../src/core/events/eventBus.ts
 class EventBus {
   constructor() {}
+  transactionalListeners = new Map;
+  listenTransactional(event, listener) {
+    const handlers = this.transactionalListeners.get(event) ?? new Set;
+    handlers.add(listener);
+    this.transactionalListeners.set(event, handlers);
+    return () => {
+      handlers.delete(listener);
+      if (!handlers.size)
+        this.transactionalListeners.delete(event);
+    };
+  }
+  hasTransactionalListeners(event) {
+    return (this.transactionalListeners.get(event)?.size ?? 0) > 0;
+  }
+  async dispatchTransactional(event, payload) {
+    for (const listener of this.transactionalListeners.get(event) ?? [])
+      await listener(payload);
+  }
   listeners = new Map;
   on(event, listener) {
     return this.listen(event, listener);

package/dist/entries/auth/scimAuthMiddleware.js

@@ -155,6 +155,24 @@ var init_tenantContext = __esm(() => {
 // ../../src/core/events/eventBus.ts
 class EventBus {
   constructor() {}
+  transactionalListeners = new Map;
+  listenTransactional(event, listener) {
+    const handlers = this.transactionalListeners.get(event) ?? new Set;
+    handlers.add(listener);
+    this.transactionalListeners.set(event, handlers);
+    return () => {
+      handlers.delete(listener);
+      if (!handlers.size)
+        this.transactionalListeners.delete(event);
+    };
+  }
+  hasTransactionalListeners(event) {
+    return (this.transactionalListeners.get(event)?.size ?? 0) > 0;
+  }
+  async dispatchTransactional(event, payload) {
+    for (const listener of this.transactionalListeners.get(event) ?? [])
+      await listener(payload);
+  }
   listeners = new Map;
   on(event, listener) {
     return this.listen(event, listener);

package/dist/entries/jobs/exportAuditLogsJob.js

@@ -58,6 +58,24 @@ var init_tenantContext = __esm(() => {
 // ../../src/core/events/eventBus.ts
 class EventBus {
   constructor() {}
+  transactionalListeners = new Map;
+  listenTransactional(event, listener) {
+    const handlers = this.transactionalListeners.get(event) ?? new Set;
+    handlers.add(listener);
+    this.transactionalListeners.set(event, handlers);
+    return () => {
+      handlers.delete(listener);
+      if (!handlers.size)
+        this.transactionalListeners.delete(event);
+    };
+  }
+  hasTransactionalListeners(event) {
+    return (this.transactionalListeners.get(event)?.size ?? 0) > 0;
+  }
+  async dispatchTransactional(event, payload) {
+    for (const listener of this.transactionalListeners.get(event) ?? [])
+      await listener(payload);
+  }
   listeners = new Map;
   on(event, listener) {
     return this.listen(event, listener);

package/dist/entries/openapi/generator.js

@@ -168,7 +168,7 @@ var PUBLIC_ROUTE_DESCRIPTIONS = {
   "GET /scim/v2/Groups": "SCIM list groups (departments)"
 };
 function toOpenApiPath(path) {
-  return path.replace(/:([A-Za-z_]+)/g, "{$1}");
+  return path.replace(/:([A-Za-z_][A-Za-z0-9_]*)/g, "{$1}");
 }
 function toRelativeApiPath(path) {
   const prefix = apiPrefix();
@@ -196,6 +196,16 @@ function requiresBearerAuth(path, method) {
   }
   return relative.startsWith("/auth/") || relative.startsWith("/users/me") || path.startsWith("/users/me") || relative === "/user" || relative.startsWith("/integrations/") || relative.startsWith("/audit-logs") || ["POST", "PATCH", "PUT", "DELETE"].includes(method);
 }
+var DEFAULT_RESPONSES = {
+  "200": { description: "OK" },
+  "201": { description: "Created" },
+  "204": { description: "No Content" },
+  "400": { description: "Bad Request" },
+  "401": { description: "Unauthorized" },
+  "403": { description: "Forbidden" },
+  "404": { description: "Not Found" },
+  "422": { description: "Validation Error" }
+};
 function generateOpenApiSpec(routes) {
   const paths = {};
   for (const route of routes) {
@@ -206,16 +216,8 @@ function generateOpenApiSpec(routes) {
     paths[openApiPath][method] = {
       summary: description,
       ...requiresBearerAuth(route.path, route.method) ? { security: [{ bearerAuth: [] }] } : {},
-      responses: {
-        "200": { description: "OK" },
-        "201": { description: "Created" },
-        "204": { description: "No Content" },
-        "400": { description: "Bad Request" },
-        "401": { description: "Unauthorized" },
-        "403": { description: "Forbidden" },
-        "404": { description: "Not Found" },
-        "422": { description: "Validation Error" }
-      }
+      ...route.openApi,
+      responses: route.openApi?.responses ?? structuredClone(DEFAULT_RESPONSES)
     };
   }
   return {
@@ -297,10 +299,38 @@ function renderTypeScriptSdk(spec, prefix = apiPrefix()) {
     "  }",
     ""
   ];
+  const contracts = Object.fromEntries(Object.entries(spec.paths).map(([path, methods]) => [
+    path,
+    Object.fromEntries(Object.entries(methods).filter(([, value]) => {
+      const operation = value;
+      return operation.parameters || operation.requestBody || operation.operationId || JSON.stringify(operation.responses) !== JSON.stringify(DEFAULT_RESPONSES);
+    }))
+  ]).filter(([, methods]) => Object.keys(methods).length));
+  if (Object.keys(contracts).length)
+    lines.splice(1, 0, `  static readonly operationContracts = ${JSON.stringify(contracts)} as const;`);
   for (const [path, methods] of Object.entries(spec.paths)) {
     const requestPath = toRequestPath(path, prefix);
-    for (const method of Object.keys(methods)) {
+    for (const [method, operation] of Object.entries(methods)) {
+      const metadata = operation;
+      const headers = metadata.parameters?.filter((parameter) => parameter.in === "header") ?? [];
       const functionName = toMethodName(method, path, prefix);
+      const pathParameters = metadata.parameters?.filter((parameter) => parameter.in === "path") ?? [];
+      const queryParameters = metadata.parameters?.filter((parameter) => parameter.in === "query") ?? [];
+      const groups = [
+        { field: "operationHeaders", parameters: headers },
+        { field: "operationPath", parameters: pathParameters },
+        { field: "operationQuery", parameters: queryParameters }
+      ].filter((group) => group.parameters.length);
+      if (groups.length) {
+        const type = groups.map((group) => `${group.field}${group.parameters.some((parameter) => parameter.required) ? "" : "?"}: { ${group.parameters.map((parameter) => `${JSON.stringify(parameter.name)}${parameter.required ? "" : "?"}: ${parameter.schema?.type === "integer" || parameter.schema?.type === "number" ? "number" : parameter.schema?.type === "boolean" ? "boolean" : "string"}`).join("; ")} }`).join("; ");
+        const required = groups.some((group) => group.parameters.some((parameter) => parameter.required));
+        lines.push(`  async ${functionName}(init: RequestInit & { ${type} }${required ? "" : " = {}"}): Promise<Response> {`, "    const headers = new Headers(init.headers);", `    let path = ${JSON.stringify(requestPath)};`, ...groups.flatMap((group) => group.parameters.filter((parameter) => parameter.required).map((parameter) => `    if (init.${group.field}?.[${JSON.stringify(parameter.name)}] === undefined) throw new TypeError(${JSON.stringify(`Required operation ${group.field === "operationHeaders" ? "header" : group.field === "operationPath" ? "path parameter" : "query parameter"}: ${parameter.name}`)});`)), ...headers.map((parameter) => `    if (init.operationHeaders?.[${JSON.stringify(parameter.name)}] !== undefined) headers.set(${JSON.stringify(parameter.name)}, String(init.operationHeaders[${JSON.stringify(parameter.name)}]));`), ...pathParameters.map((parameter) => `    if (init.operationPath?.[${JSON.stringify(parameter.name)}] !== undefined) path = path.replaceAll(${JSON.stringify(`{${parameter.name}}`)}, encodeURIComponent(String(init.operationPath[${JSON.stringify(parameter.name)}])));`), ...queryParameters.length ? [
+          "    const query = new URLSearchParams();",
+          ...queryParameters.map((parameter) => `    if (init.operationQuery?.[${JSON.stringify(parameter.name)}] !== undefined) query.set(${JSON.stringify(parameter.name)}, String(init.operationQuery[${JSON.stringify(parameter.name)}]));`),
+          "    if (query.size) path += '?' + query.toString();"
+        ] : [], `    const { ${groups.map((group) => `${group.field}: _${group.field}`).join(", ")}, ...requestInit } = init;`, `    return await this.request(path, { ...requestInit, headers, method: ${JSON.stringify(method.toUpperCase())} });`, "  }", "");
+        continue;
+      }
       lines.push(`  async ${functionName}(init: RequestInit = {}): Promise<Response> {`, `    return await this.request("${requestPath}", { ...init, method: "${method.toUpperCase()}" });`, "  }", "");
     }
   }

package/dist/entries/openapi/validate.js

@@ -13,6 +13,16 @@ function validateOpenApiSpec(spec) {
       errors.push(`Path must start with '/': ${path}`);
     }
     for (const [method, operation] of Object.entries(methods)) {
+      const details = operation;
+      const seen = new Set;
+      for (const parameter of details.parameters ?? []) {
+        const identity = `${parameter.in}:${parameter.in === "header" ? parameter.name.toLowerCase() : parameter.name}`;
+        if (seen.has(identity))
+          errors.push(`Duplicate parameter ${parameter.name} on ${method.toUpperCase()} ${path}.`);
+        seen.add(identity);
+        if (parameter.in === "path" && (!parameter.required || !path.includes(`{${parameter.name}}`)))
+          errors.push(`Path parameter ${parameter.name} must be required and match ${path}.`);
+      }
       if (!("responses" in operation)) {
         errors.push(`Operation ${method.toUpperCase()} ${path} is missing responses.`);
       }

package/dist/entries/tenant/databaseTenantContext.js

@@ -58,6 +58,24 @@ var init_tenantContext = __esm(() => {
 // ../../src/core/events/eventBus.ts
 class EventBus {
   constructor() {}
+  transactionalListeners = new Map;
+  listenTransactional(event, listener) {
+    const handlers = this.transactionalListeners.get(event) ?? new Set;
+    handlers.add(listener);
+    this.transactionalListeners.set(event, handlers);
+    return () => {
+      handlers.delete(listener);
+      if (!handlers.size)
+        this.transactionalListeners.delete(event);
+    };
+  }
+  hasTransactionalListeners(event) {
+    return (this.transactionalListeners.get(event)?.size ?? 0) > 0;
+  }
+  async dispatchTransactional(event, payload) {
+    for (const listener of this.transactionalListeners.get(event) ?? [])
+      await listener(payload);
+  }
   listeners = new Map;
   on(event, listener) {
     return this.listen(event, listener);

package/dist/entries/tenant/tenantDatabaseScope.js

@@ -133,6 +133,24 @@ var init_tenantContext = __esm(() => {
 // ../../src/core/events/eventBus.ts
 class EventBus {
   constructor() {}
+  transactionalListeners = new Map;
+  listenTransactional(event, listener) {
+    const handlers = this.transactionalListeners.get(event) ?? new Set;
+    handlers.add(listener);
+    this.transactionalListeners.set(event, handlers);
+    return () => {
+      handlers.delete(listener);
+      if (!handlers.size)
+        this.transactionalListeners.delete(event);
+    };
+  }
+  hasTransactionalListeners(event) {
+    return (this.transactionalListeners.get(event)?.size ?? 0) > 0;
+  }
+  async dispatchTransactional(event, payload) {
+    for (const listener of this.transactionalListeners.get(event) ?? [])
+      await listener(payload);
+  }
   listeners = new Map;
   on(event, listener) {
     return this.listen(event, listener);

package/dist/index.js

@@ -535,6 +535,24 @@ var init_transactionControl = __esm(() => {
 // ../../src/core/events/eventBus.ts
 class EventBus {
   constructor() {}
+  transactionalListeners = new Map;
+  listenTransactional(event, listener) {
+    const handlers = this.transactionalListeners.get(event) ?? new Set;
+    handlers.add(listener);
+    this.transactionalListeners.set(event, handlers);
+    return () => {
+      handlers.delete(listener);
+      if (!handlers.size)
+        this.transactionalListeners.delete(event);
+    };
+  }
+  hasTransactionalListeners(event) {
+    return (this.transactionalListeners.get(event)?.size ?? 0) > 0;
+  }
+  async dispatchTransactional(event, payload) {
+    for (const listener of this.transactionalListeners.get(event) ?? [])
+      await listener(payload);
+  }
   listeners = new Map;
   on(event, listener) {
     return this.listen(event, listener);
@@ -621,6 +639,7 @@ async function dispatchQueuedModelEvents(queued) {
   }
 }
 async function dispatchModelEvent(event, payload) {
+  await eventBus.dispatchTransactional(event, payload);
   const state = deferredModelEvents.getStore();
   const frame = state?.frames[state.frames.length - 1];
   if (frame) {
@@ -3810,6 +3829,9 @@ class ConfigStore {
     return this.values.has(key);
   }
 }
+// ../../src/core/database/baseRepository.ts
+init_eventBus();
+
 // ../../src/core/events/index.ts
 init_deferredModelEvents();
 init_eventBus();
@@ -3828,6 +3850,9 @@ function buildPaginationMeta(input) {
   };
 }
 
+// ../../src/core/database/baseRepository.ts
+init_connectionContext();
+
 // ../../src/core/database/query.ts
 init_dialect();
 function quoteIdentifier(identifier) {
@@ -4952,6 +4977,9 @@ class RepositoryQuery {
 }
 
 // ../../src/core/database/baseRepository.ts
+init_transaction();
+init_transactionControl();
+
 class BaseRepository {
   table;
   connection;
@@ -4959,6 +4987,17 @@ class BaseRepository {
     this.table = table;
     this.connection = connection;
   }
+  assertTransactionalEvent(action) {
+    if (!eventBus.hasTransactionalListeners(modelEventName(this.table.name, action)))
+      return;
+    if (!hasActiveTransaction() || this.connection !== repositoryConnection && this.connection !== getActiveDatabaseConnection(repositoryConnection))
+      throw new Error("Transactional model listeners require runInTransaction and the framework-bound repository connection before writing.");
+  }
+  async runModelMutation(action, operation) {
+    if (!eventBus.hasTransactionalListeners(modelEventName(this.table.name, action)))
+      return operation();
+    return runInTransaction(operation);
+  }
   async count(options = {}) {
     const { whereNodes, where, ...rest } = options;
     return await this.countWhere(where ?? {}, rest, whereNodes ?? []);
@@ -5116,7 +5155,8 @@ class BaseRepository {
     return await this.incrementById(id, column, -amount, extra);
   }
   async create(values) {
-    return await withDatabaseErrorHandling(async () => {
+    this.assertTransactionalEvent("created");
+    return await this.runModelMutation("created", () => withDatabaseErrorHandling(async () => {
       const { text, params } = buildInsertQuery(this.table, values);
       const [record] = await this.connection.unsafe(text, params);
       if (!record) {
@@ -5125,10 +5165,11 @@ class BaseRepository {
       const entity = record;
       await dispatchModelEvent(modelEventName(this.table.name, "created"), entity);
       return entity;
-    });
+    }));
   }
   async updateById(id, changes) {
-    return await withDatabaseErrorHandling(async () => {
+    this.assertTransactionalEvent("updated");
+    return await this.runModelMutation("updated", () => withDatabaseErrorHandling(async () => {
       const { text, params } = buildUpdateQuery(this.table, id, changes);
       const [record] = await this.connection.unsafe(text, params);
       const entity = record ?? null;
@@ -5136,7 +5177,7 @@ class BaseRepository {
         await dispatchModelEvent(modelEventName(this.table.name, "updated"), entity);
       }
       return entity;
-    });
+    }));
   }
   async updateByIdOrThrow(id, changes, errorFactory) {
     const record = await this.updateById(id, changes);
@@ -5152,7 +5193,8 @@ class BaseRepository {
     return await this.forceDeleteById(id);
   }
   async softDeleteById(id) {
-    return await withDatabaseErrorHandling(async () => {
+    this.assertTransactionalEvent("deleted");
+    return await this.runModelMutation("deleted", () => withDatabaseErrorHandling(async () => {
       const { text, params } = buildSoftDeleteByIdQuery(this.table, id, new Date);
       const [record] = await this.connection.unsafe(text, params);
       if (!record) {
@@ -5160,10 +5202,11 @@ class BaseRepository {
       }
       await dispatchModelEvent(modelEventName(this.table.name, "deleted"), record);
       return true;
-    });
+    }));
   }
   async forceDeleteById(id) {
-    return await withDatabaseErrorHandling(async () => {
+    this.assertTransactionalEvent("force-deleted");
+    return await this.runModelMutation("force-deleted", () => withDatabaseErrorHandling(async () => {
       const { text, params } = buildDeleteByIdQuery(this.table, id);
       const [row] = await this.connection.unsafe(text, params);
       if (!row) {
@@ -5173,10 +5216,11 @@ class BaseRepository {
         id
       });
       return true;
-    });
+    }));
   }
   async restoreById(id) {
-    return await withDatabaseErrorHandling(async () => {
+    this.assertTransactionalEvent("restored");
+    return await this.runModelMutation("restored", () => withDatabaseErrorHandling(async () => {
       const { text, params } = buildRestoreByIdQuery(this.table, id);
       const [record] = await this.connection.unsafe(text, params);
       if (!record) {
@@ -5185,7 +5229,7 @@ class BaseRepository {
       const entity = record;
       await dispatchModelEvent(modelEventName(this.table.name, "restored"), entity);
       return entity;
-    });
+    }));
   }
   withConnection(connection) {
     const clone = Object.create(Object.getPrototypeOf(this));
@@ -8417,6 +8461,10 @@ class SqlOutbox {
       this.listeners.set(listener.name, listener);
     }
   }
+  hasListener(name, event) {
+    const listener = this.listeners.get(name);
+    return listener !== undefined && (event === undefined || listener.event === event);
+  }
   async publish(name, payload, options = {}) {
     if (!hasActiveTransaction())
       throw new Error("Durable publication requires an active business transaction.");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getstrata/core",
-  "version": "2.0.3",
+  "version": "2.0.4",
   "description": "Strata Bun framework public API",
   "type": "module",
   "license": "MIT",