@classytic/arc 2.23.0 → 2.28.0

package/dist/utils/index.d.mts

@@ -1,40 +1,11 @@
-import { $ as OpenApiSchemas, $t as UserLike, Jt as AnyRecord, S as QueryParserInterface, U as ResourceConfig, b as ParsedQuery } from "../index-BBsvQt7U.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 {
@@ -437,34 +459,6 @@ declare const NEUTRAL_DIALECT: FilterDialect;
  */
 declare function handleRaw<T>(handler: (request: FastifyRequest, reply: FastifyReply) => Promise<T>, statusCode?: number): (request: FastifyRequest, reply: FastifyReply) => Promise<void>;
 //#endregion
-//#region src/utils/headers.d.ts
-/**
- * Canonical header typing + accessor.
- *
- * Node/Fastify header values are `string | string[] | undefined` — repeated
- * headers arrive as arrays. `IRequestContext.headers` is DECLARED as
- * `Record<string, string | undefined>` for ergonomic host code, but the HTTP
- * adapter passes Fastify's headers object through unchanged, so `string[]`
- * CAN appear at runtime behind the narrower type (the declared type is
- * scheduled to widen to {@link ArcHeaders} in v3). Until then, read headers
- * through {@link getHeader} instead of indexing — it's honest about arrays
- * and deterministic about duplicates.
- */
-/** What a headers bag actually contains at runtime — HTTP or synthetic MCP. */
-type ArcHeaders = Readonly<Record<string, string | readonly string[] | undefined>>;
-/**
- * Read a single header value. Lowercases the name (Node normalizes incoming
- * header names to lowercase) and returns the FIRST value when the header
- * was repeated.
- *
- * Duplicate policy: first-value is deterministic, but for security-sensitive
- * headers (authorization material, forwarded-for chains, content-length) a
- * duplicate usually signals smuggling or a broken proxy — consumers that
- * care should check `Array.isArray(headers[name])` and REJECT instead of
- * picking a winner.
- */
-declare function getHeader(headers: ArcHeaders | Record<string, string | undefined> | undefined, name: string): string | undefined;
-//#endregion
 //#region src/utils/queryParser.d.ts
 interface ArcQueryParserOptions {
   /** Maximum allowed limit value (default: 1000) */
@@ -1110,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()`.
@@ -1521,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, type ArcHeaders, 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 SseStream, type SseStreamOptions, 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, getHeader, getListQueryParams, getUserId, handleRaw, hasEvents, isArcError, isJsonSchema, isReadableStream, isZodSchema, keysetListResponse, listResponse, offsetListResponse, openSseStream, 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,8 +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 { 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 CircuitState, C as defineGuard, D as CircuitBreaker, E as withCompensation, F as validateResourceConfig, M as createCircuitBreakerRegistry, N as assertValidConfig, O as CircuitBreakerError, P as formatValidationErrors, S as NEUTRAL_DIALECT, T as defineCompensation, _ as ArcQueryParser, a as bareListResponse, b as handleRaw, c as errorDetailSchema, d as keysetListResponse, f as listResponse, g as responses, h as queryParams, i as aggregateListResponse, j as createCircuitBreaker, k as CircuitBreakerRegistry, 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 defineErrorMapper, x as MONGO_DIALECT, y as getHeader } from "../utils-CZyeRXTh.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, getHeader, getListQueryParams, getUserId, handleRaw, hasEvents, isArcError, isJsonSchema, isReadableStream, isZodSchema, keysetListResponse, listResponse, offsetListResponse, openSseStream, 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 };