@classytic/arc 2.22.0 → 2.25.0

package/dist/userHelpers-Cg_y3fBz.mjs

@@ -0,0 +1,29 @@
+//#region src/utils/userHelpers.ts
+/**
+* Extract a user ID from a user object. Accepts `id` or `_id` — returns
+* `undefined` when neither is present. Used by arc's controllers to
+* populate `createdBy` / `updatedBy` fields and for cache scoping.
+*
+* @example
+* ```ts
+* import { getUserId } from '@classytic/arc/utils';
+* const uid = getUserId(request.user);
+* ```
+*/
+function getUserId(user) {
+	if (!user) return void 0;
+	const id = user.id ?? user._id;
+	return id ? String(id) : void 0;
+}
+/** Normalize a raw role value from Better Auth, JWT, or a custom identity provider. */
+function normalizeRoles(value) {
+	if (Array.isArray(value)) return value.map((role) => String(role).trim()).filter(Boolean);
+	if (typeof value === "string" && value.length > 0) return value.split(",").map((role) => role.trim()).filter(Boolean);
+	return [];
+}
+/** Extract normalized roles from a user-like object. */
+function getUserRoles(user) {
+	return user ? normalizeRoles(user.role ?? user.roles) : [];
+}
+//#endregion
+export { getUserRoles as n, normalizeRoles as r, getUserId as t };

package/dist/utils/index.d.mts

@@ -1,40 +1,11 @@
-import { $ as OpenApiSchemas, Qt as UserLike, S as QueryParserInterface, U as ResourceConfig, b as ParsedQuery, qt as AnyRecord } from "../index-DbtgCOCj.mjs";
+import { $ as OpenApiSchemas, S as QueryParserInterface, b as ParsedQuery } from "../index-DPRH0Cme.mjs";
+import { F as getHeader, I as requireSingleHeaderValue, P as ArcHeaders } from "../types-DjC-KUCz.mjs";
+import { a as getUserId, c as AnyRecord, o as getUserRoles, s as normalizeRoles } from "../types-Dmw-6Qeo.mjs";
 import { n as ErrorMapper } from "../errorHandler-C6yv4ZTW.mjs";
 import { a as NotFoundError, c as RateLimitError, d as ValidationError, f as createDomainError, i as ForbiddenError, l as ServiceUnavailableError, m as isArcError, n as ConflictError, o as OrgAccessDeniedError, p as createError, r as ErrorOptions, s as OrgRequiredError, t as ArcError, u as UnauthorizedError } from "../errors-DHcHVAgk.mjs";
 import { errorContractSchema, errorDetailSchema } from "@classytic/repo-core/errors";
+import { scheduleBackground } from "@classytic/repo-core/cache";
 import { FastifyInstance, FastifyReply, FastifyRequest, RouteHandlerMethod } from "fastify";
-//#region src/core/validateResourceConfig.d.ts
-interface ConfigError {
-  field: string;
-  message: string;
-  suggestion?: string;
-}
-interface ValidationResult {
-  valid: boolean;
-  errors: ConfigError[];
-  warnings: ConfigError[];
-}
-interface ValidateOptions {
-  /** Skip controller method validation (for testing) */
-  skipControllerCheck?: boolean;
-  /** Allow unknown preset names */
-  allowUnknownPresets?: boolean;
-  /** Custom valid permission keys beyond CRUD */
-  additionalPermissionKeys?: string[];
-}
-/**
- * Validate a resource configuration
- */
-declare function validateResourceConfig(config: ResourceConfig, options?: ValidateOptions): ValidationResult;
-/**
- * Format validation errors for display
- */
-declare function formatValidationErrors(resourceName: string, result: ValidationResult): string;
-/**
- * Validate and throw if invalid
- */
-declare function assertValidConfig(config: ResourceConfig, options?: ValidateOptions): void;
-//#endregion
 //#region src/utils/circuitBreaker.d.ts
 /**
  * Circuit Breaker Pattern
@@ -103,6 +74,31 @@ interface CircuitBreakerOptions {
    * @default 1
    */
   successThreshold?: number;
+  /**
+   * Maximum concurrent probe calls allowed while HALF_OPEN.
+   * After `resetTimeout`, only this many callers actually test the
+   * downstream — the rest fail fast (or hit the fallback) as if the
+   * circuit were still open. Without a cap, every queued caller floods
+   * a barely-recovered dependency the instant the circuit half-opens.
+   * @default 1
+   */
+  halfOpenMaxProbes?: number;
+  /**
+   * Abort the underlying operation when the breaker times out.
+   * When `true`, the wrapped function receives an `AbortSignal` as an
+   * EXTRA TRAILING argument, aborted on timeout — pass it to fetch/DB
+   * calls so timed-out work stops consuming sockets and pool slots
+   * instead of running to completion behind the rejected caller.
+   * Opt-in because it changes the wrapped function's call shape.
+   * @default false
+   *
+   * @example
+   * const breaker = new CircuitBreaker(
+   *   async (url: string, signal?: AbortSignal) => fetch(url, { signal }),
+   *   { timeout: 5000, propagateAbort: true },
+   * );
+   */
+  propagateAbort?: boolean;
   /**
    * Fallback function when circuit is open.
    * Receives the same arguments as the wrapped function.
@@ -142,10 +138,13 @@ declare class CircuitBreaker<T extends AnyAsyncFn> {
   private nextAttempt;
   private lastCallAt;
   private openedAt;
+  private halfOpenInFlight;
   private readonly failureThreshold;
   private readonly resetTimeout;
   private readonly timeout;
   private readonly successThreshold;
+  private readonly halfOpenMaxProbes;
+  private readonly propagateAbort;
   private readonly fallback?;
   private readonly onStateChange?;
   private readonly onError?;
@@ -157,7 +156,10 @@ declare class CircuitBreaker<T extends AnyAsyncFn> {
    */
   call(...args: Parameters<T>): Promise<ReturnType<T>>;
   /**
-   * Execute function with timeout
+   * Execute function with timeout. With `propagateAbort`, the wrapped fn
+   * receives a trailing AbortSignal that fires on timeout — the breaker's
+   * timeout otherwise only rejects the CALLER while the underlying work
+   * keeps consuming sockets/pool slots to completion.
    */
   private executeWithTimeout;
   /**
@@ -301,7 +303,20 @@ interface CompensationStep<TCtx = Record<string, unknown>, TResult = unknown> {
   readonly execute: (ctx: TCtx) => Promise<TResult>;
   /** Rollback on failure — receives context and this step's own result */
   readonly compensate?: (ctx: TCtx, stepResult: TResult) => Promise<void>;
-  /** Fire-and-forget — don't await, don't block, swallow errors, skip in rollback */
+  /**
+   * Fire-and-forget — don't await, don't block, skip in rollback.
+   *
+   * OUTSIDE the transactional result by design: the step is NOT listed in
+   * `completedSteps` (it hasn't completed when the result is returned — a
+   * step that later fails must never have been reported as completed), its
+   * value never appears in `results`, and it is not compensatable. Its
+   * rejection is reported through `hooks.onStepFailed` (observability
+   * only — the transaction outcome is unaffected).
+   *
+   * This is best-effort by construction — a crash loses it. Side effects
+   * that must survive failure belong in the outbox or a job queue, not in
+   * a fire-and-forget step.
+   */
   readonly fireAndForget?: boolean;
 }
 /** Lifecycle hooks for observability — wire to Arc events, metrics, or logging */
@@ -309,6 +324,13 @@ interface CompensationHooks {
   readonly onStepComplete?: (stepName: string, result: unknown) => void;
   readonly onStepFailed?: (stepName: string, error: Error) => void;
   readonly onCompensate?: (stepName: string) => void;
+  /**
+   * Reports a hook that THREW. Hook failures never alter the transaction
+   * (contained by design), but silent containment makes a broken
+   * metrics/audit sink invisible — wire this to a logger. Must not throw;
+   * if it does, that too is contained.
+   */
+  readonly onHookError?: (hookName: string, error: Error) => void;
 }
 /** Error from a compensation action that failed during rollback */
 interface CompensationError {
@@ -1082,13 +1104,6 @@ declare function getListQueryParams(): AnyRecord;
  */
 declare function getDefaultCrudSchemas(): Record<string, Record<string, unknown>>;
 //#endregion
-//#region src/utils/runtime.d.ts
-/**
- * Portable "run on next tick" scheduler. `setImmediate` is Node-only — not
- * available in Bun workers, Deno, Cloudflare Workers, or edge runtimes.
- */
-declare const scheduleBackground: (cb: () => void) => void;
-//#endregion
 //#region src/utils/schemaConverter.d.ts
 /**
  * Supported JSON Schema output targets for Zod v4's `toJSONSchema()`.
@@ -1215,6 +1230,38 @@ declare function convertRouteSchema(schema: Record<string, unknown>, target?: Js
  */
 declare function simpleEqualityMatcher(item: unknown, filters: Record<string, unknown>): boolean;
 //#endregion
+//#region src/utils/sseStream.d.ts
+interface SseStreamOptions {
+  /** Heartbeat comment interval in ms (default: 30000). */
+  heartbeatMs?: number;
+  /**
+   * Reconnection-delay hint written once at connect as the standard SSE
+   * `retry:` field (WHATWG EventSource honors it natively). Omit to send
+   * no hint (browser default ~3s).
+   */
+  retryMs?: number;
+}
+interface SseStream {
+  /**
+   * Write one SSE frame. `id` (optional) becomes the standard SSE `id:`
+   * field — clients receive it as `lastEventId` (WHATWG), enabling
+   * client-side dedup/resume bookkeeping even when the server keeps no
+   * replay log. Returns `false` when the connection was destroyed
+   * (backpressure) — the stream is already cleaned up; stop writing.
+   */
+  write(eventName: string, data: string, id?: string): boolean;
+  /** Idempotent teardown: heartbeat cleared, cleanups run, socket ended. */
+  close(): void;
+  /** Register teardown work (unsubscribes etc.) — runs exactly once. */
+  onCleanup(fn: () => void): void;
+}
+/**
+ * Take over the reply socket and open an SSE stream. Call ONLY after every
+ * gate (auth, permissions, validation) has passed — after `hijack()` no
+ * JSON error can be sent.
+ */
+declare function openSseStream(request: FastifyRequest, reply: FastifyReply, options?: SseStreamOptions): SseStream;
+//#endregion
 //#region src/utils/stateMachine.d.ts
 /**
  * State Machine Utility
@@ -1461,18 +1508,4 @@ declare function hasEvents(instance: FastifyInstance): instance is FastifyInstan
   events: EventsDecorator;
 };
 //#endregion
-//#region src/utils/userHelpers.d.ts
-/**
- * Extract a user ID from a user object. Accepts `id` or `_id` — returns
- * `undefined` when neither is present. Used by arc's controllers to
- * populate `createdBy` / `updatedBy` fields and for cache scoping.
- *
- * @example
- * ```ts
- * import { getUserId } from '@classytic/arc/utils';
- * const uid = getUserId(request.user);
- * ```
- */
-declare function getUserId(user: UserLike | null | undefined): string | undefined;
-//#endregion
-export { ArcError, ArcQueryParser, type ArcQueryParserOptions, CircuitBreaker, CircuitBreakerError, type CircuitBreakerOptions, CircuitBreakerRegistry, type CircuitBreakerStats, CircuitState, type CompensationDefinition, type CompensationError, type CompensationHooks, type CompensationResult, type CompensationStep, type ConfigError, ConflictError, type ErrorOptions, type EventsDecorator, type FilterDialect, ForbiddenError, type Guard, type GuardConfig, type JsonSchema, type JsonSchemaTarget, MONGO_DIALECT, NEUTRAL_DIALECT, NotFoundError, OrgAccessDeniedError, OrgRequiredError, type PipeUIMessageStreamOptions, RateLimitError, ServiceUnavailableError, type StateMachine, type TransitionConfig, UI_MESSAGE_STREAM_HEADERS, UnauthorizedError, type ValidateOptions, ValidationError, type ValidationResult, aggregateListResponse, assertValidConfig, bareListResponse, convertOpenApiSchemas, convertRouteSchema, createCircuitBreaker, createCircuitBreakerRegistry, createDomainError, createError, createQueryParser, createStateMachine, defineCompensation, defineErrorMapper, defineGuard, deleteResponse, errorContractSchema, errorDetailSchema, formatValidationErrors, forwardedStreamHeaders, getDefaultCrudSchemas, getListQueryParams, getUserId, handleRaw, hasEvents, isArcError, isJsonSchema, isReadableStream, isZodSchema, keysetListResponse, listResponse, offsetListResponse, paginationSchema, pipeUIMessageStreamToReply, promoteStreamTokenToHeader, queryParams, responses, scheduleBackground, simpleEqualityMatcher, toJsonSchema, validateResourceConfig, withCompensation };
+export { ArcError, type ArcHeaders, ArcQueryParser, type ArcQueryParserOptions, CircuitBreaker, CircuitBreakerError, type CircuitBreakerOptions, CircuitBreakerRegistry, type CircuitBreakerStats, CircuitState, type CompensationDefinition, type CompensationError, type CompensationHooks, type CompensationResult, type CompensationStep, ConflictError, type ErrorOptions, type EventsDecorator, type FilterDialect, ForbiddenError, type Guard, type GuardConfig, type JsonSchema, type JsonSchemaTarget, MONGO_DIALECT, NEUTRAL_DIALECT, NotFoundError, OrgAccessDeniedError, OrgRequiredError, type PipeUIMessageStreamOptions, RateLimitError, ServiceUnavailableError, type SseStream, type SseStreamOptions, type StateMachine, type TransitionConfig, UI_MESSAGE_STREAM_HEADERS, UnauthorizedError, ValidationError, aggregateListResponse, bareListResponse, convertOpenApiSchemas, convertRouteSchema, createCircuitBreaker, createCircuitBreakerRegistry, createDomainError, createError, createQueryParser, createStateMachine, defineCompensation, defineErrorMapper, defineGuard, deleteResponse, errorContractSchema, errorDetailSchema, forwardedStreamHeaders, getDefaultCrudSchemas, getHeader, getListQueryParams, getUserId, getUserRoles, handleRaw, hasEvents, isArcError, isJsonSchema, isReadableStream, isZodSchema, keysetListResponse, listResponse, normalizeRoles, offsetListResponse, openSseStream, paginationSchema, pipeUIMessageStreamToReply, promoteStreamTokenToHeader, queryParams, requireSingleHeaderValue, responses, scheduleBackground, simpleEqualityMatcher, toJsonSchema, withCompensation };

package/dist/utils/index.mjs

@@ -1,6 +1,10 @@
 import { a as OrgAccessDeniedError, c as ServiceUnavailableError, d as createDomainError, f as createError, i as NotFoundError, l as UnauthorizedError, n as ConflictError, o as OrgRequiredError, p as isArcError, r as ForbiddenError, s as RateLimitError, t as ArcError, u as ValidationError } from "../errors-DkO8Nk6-.mjs";
-import { A as createCircuitBreaker, C as defineErrorMapper, D as CircuitBreakerError, E as CircuitBreaker, F as simpleEqualityMatcher, M as assertValidConfig, N as formatValidationErrors, O as CircuitBreakerRegistry, P as validateResourceConfig, S as defineGuard, T as withCompensation, _ as ArcQueryParser, a as bareListResponse, b as MONGO_DIALECT, c as errorDetailSchema, d as keysetListResponse, f as listResponse, g as responses, h as queryParams, i as aggregateListResponse, j as createCircuitBreakerRegistry, k as CircuitState, l as getDefaultCrudSchemas, m as paginationSchema, n as createStateMachine, o as deleteResponse, p as offsetListResponse, r as scheduleBackground, s as errorContractSchema, t as getUserId, u as getListQueryParams, v as createQueryParser, w as defineCompensation, x as NEUTRAL_DIALECT, y as handleRaw } from "../utils-FhJ88TJE.mjs";
-import { a as isZodSchema, i as isJsonSchema, n as convertRouteSchema, o as toJsonSchema, t as convertOpenApiSchemas } from "../schemaConverter-Ds5reSGs.mjs";
+import { n as requireSingleHeaderValue, t as getHeader } from "../headers-BvlQSDMB.mjs";
+import { n as getUserRoles, r as normalizeRoles, t as getUserId } from "../userHelpers-Cg_y3fBz.mjs";
+import { t as simpleEqualityMatcher } from "../simpleEqualityMatcher-Cg05HPsn.mjs";
+import { A as createCircuitBreakerRegistry, C as defineCompensation, D as CircuitBreakerRegistry, E as CircuitBreakerError, O as CircuitState, S as defineErrorMapper, T as CircuitBreaker, _ as createQueryParser, a as deleteResponse, b as NEUTRAL_DIALECT, c as getDefaultCrudSchemas, d as listResponse, f as offsetListResponse, g as ArcQueryParser, h as responses, i as bareListResponse, k as createCircuitBreaker, l as getListQueryParams, m as queryParams, n as scheduleBackground, o as errorContractSchema, p as paginationSchema, r as aggregateListResponse, s as errorDetailSchema, t as createStateMachine, u as keysetListResponse, v as handleRaw, w as withCompensation, x as defineGuard, y as MONGO_DIALECT } from "../utils-taUVD4p3.mjs";
+import { a as isZodSchema, i as isJsonSchema, n as convertRouteSchema, o as toJsonSchema, t as convertOpenApiSchemas } from "../schemaConverter-DJvodiHj.mjs";
 import { a as promoteStreamTokenToHeader, i as pipeUIMessageStreamToReply, n as forwardedStreamHeaders, r as isReadableStream, t as UI_MESSAGE_STREAM_HEADERS } from "../streaming-BQcW6_Kq.mjs";
+import { t as openSseStream } from "../sseStream-BQ7Qaynp.mjs";
 import { t as hasEvents } from "../typeGuards-C9KXUly6.mjs";
-export { ArcError, ArcQueryParser, CircuitBreaker, CircuitBreakerError, CircuitBreakerRegistry, CircuitState, ConflictError, ForbiddenError, MONGO_DIALECT, NEUTRAL_DIALECT, NotFoundError, OrgAccessDeniedError, OrgRequiredError, RateLimitError, ServiceUnavailableError, UI_MESSAGE_STREAM_HEADERS, UnauthorizedError, ValidationError, aggregateListResponse, assertValidConfig, bareListResponse, convertOpenApiSchemas, convertRouteSchema, createCircuitBreaker, createCircuitBreakerRegistry, createDomainError, createError, createQueryParser, createStateMachine, defineCompensation, defineErrorMapper, defineGuard, deleteResponse, errorContractSchema, errorDetailSchema, formatValidationErrors, forwardedStreamHeaders, getDefaultCrudSchemas, getListQueryParams, getUserId, handleRaw, hasEvents, isArcError, isJsonSchema, isReadableStream, isZodSchema, keysetListResponse, listResponse, offsetListResponse, paginationSchema, pipeUIMessageStreamToReply, promoteStreamTokenToHeader, queryParams, responses, scheduleBackground, simpleEqualityMatcher, toJsonSchema, validateResourceConfig, withCompensation };
+export { ArcError, ArcQueryParser, CircuitBreaker, CircuitBreakerError, CircuitBreakerRegistry, CircuitState, ConflictError, ForbiddenError, MONGO_DIALECT, NEUTRAL_DIALECT, NotFoundError, OrgAccessDeniedError, OrgRequiredError, RateLimitError, ServiceUnavailableError, UI_MESSAGE_STREAM_HEADERS, UnauthorizedError, ValidationError, aggregateListResponse, bareListResponse, convertOpenApiSchemas, convertRouteSchema, createCircuitBreaker, createCircuitBreakerRegistry, createDomainError, createError, createQueryParser, createStateMachine, defineCompensation, defineErrorMapper, defineGuard, deleteResponse, errorContractSchema, errorDetailSchema, forwardedStreamHeaders, getDefaultCrudSchemas, getHeader, getListQueryParams, getUserId, getUserRoles, handleRaw, hasEvents, isArcError, isJsonSchema, isReadableStream, isZodSchema, keysetListResponse, listResponse, normalizeRoles, offsetListResponse, openSseStream, paginationSchema, pipeUIMessageStreamToReply, promoteStreamTokenToHeader, queryParams, requireSingleHeaderValue, responses, scheduleBackground, simpleEqualityMatcher, toJsonSchema, withCompensation };