@classytic/arc 2.8.4 → 2.8.5

package/dist/utils/index.d.mts

@@ -1,6 +1,6 @@
-import { Y as OpenApiSchemas, Z as ParsedQuery, m as AnyRecord, nt as QueryParserInterface } from "../interface-BVuMfeVv.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 ErrorDetails, s as OrgRequiredError, t as ArcError, u as UnauthorizedError } from "../errors-Bmn3eZT6.mjs";
-import { a as CircuitBreakerStats, c as createCircuitBreakerRegistry, i as CircuitBreakerRegistry, n as CircuitBreakerError, o as CircuitState, r as CircuitBreakerOptions, s as createCircuitBreaker, t as CircuitBreaker } from "../circuitBreaker-CvXkjfrW.mjs";
+import { Y as OpenApiSchemas, Z as ParsedQuery, m as AnyRecord, nt as QueryParserInterface } from "../interface-CMRutPfe.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 ErrorDetails, s as OrgRequiredError, t as ArcError, u as UnauthorizedError } from "../errors-Ck2h67pm.mjs";
+import { a as CircuitBreakerStats, c as createCircuitBreakerRegistry, i as CircuitBreakerRegistry, n as CircuitBreakerError, o as CircuitState, r as CircuitBreakerOptions, s as createCircuitBreaker, t as CircuitBreaker } from "../circuitBreaker-dTtG-UyS.mjs";
 import { FastifyInstance, FastifyReply, FastifyRequest, RouteHandlerMethod } from "fastify";
 
 //#region src/utils/compensation.d.ts
@@ -506,6 +506,14 @@ declare function getListQueryParams(): AnyRecord;
 declare function getDefaultCrudSchemas(): Record<string, Record<string, unknown>>;
 //#endregion
 //#region src/utils/schemaConverter.d.ts
+/**
+ * Supported JSON Schema output targets for Zod v4's `toJSONSchema()`.
+ * - `draft-7`: Fastify/AJV validation (default)
+ * - `draft-2020-12`: AJV 2020 (opt-in, requires ajv/dist/2020)
+ * - `openapi-3.0`: OpenAPI 3.0 document generation
+ * - `openapi-3.1`: OpenAPI 3.1 document generation
+ */
+type JsonSchemaTarget = "draft-7" | "draft-2020-12" | "openapi-3.0" | "openapi-3.1";
 /**
  * Check if an object is already a plain JSON Schema.
  * Returns true if it has JSON Schema markers (`type`, `properties`, `$ref`,
@@ -522,15 +530,22 @@ declare function isZodSchema(input: unknown): boolean;
  * Detection order:
  * 1. `null`/`undefined` → `undefined`
  * 2. Already JSON Schema → pass through as-is (zero overhead)
- * 3. Zod v4 schema → `z.toJSONSchema(schema, { target: 'openapi-3.0' })`
+ * 3. Zod v4 schema → `z.toJSONSchema(schema, { target })`
  * 4. Unrecognized object → return as-is (treat as opaque schema)
+ *
+ * @param input Schema (Zod, plain JSON Schema, or opaque object)
+ * @param target Output target — defaults to `draft-7` for Fastify compatibility.
+ *               Pass `openapi-3.0`/`openapi-3.1` for OpenAPI document generation.
  */
-declare function toJsonSchema(input: unknown): Record<string, unknown> | undefined;
+declare function toJsonSchema(input: unknown, target?: JsonSchemaTarget): Record<string, unknown> | undefined;
 /**
  * Convert all schema fields in an OpenApiSchemas object.
  * JSON Schema values pass through unchanged. Only Zod schemas are converted.
+ *
+ * Defaults to the `openapi-3.0` target since this function feeds OpenAPI doc
+ * generation, not Fastify route validation.
  */
-declare function convertOpenApiSchemas(schemas: OpenApiSchemas): OpenApiSchemas;
+declare function convertOpenApiSchemas(schemas: OpenApiSchemas, target?: JsonSchemaTarget): OpenApiSchemas;
 /**
  * Convert schema values in a Fastify route schema record.
  *
@@ -540,8 +555,11 @@ declare function convertOpenApiSchemas(schemas: OpenApiSchemas): OpenApiSchemas;
  * JSON Schema values pass through unchanged. Only Zod schemas are converted.
  *
  * Used for both additionalRoutes and customSchemas (CRUD overrides).
+ *
+ * Defaults to `draft-7` so Fastify v5's bundled AJV 8 accepts the output.
+ * Pass `openapi-3.0` (or `openapi-3.1`) when generating OpenAPI documents.
  */
-declare function convertRouteSchema(schema: Record<string, unknown>): Record<string, unknown>;
+declare function convertRouteSchema(schema: Record<string, unknown>, target?: JsonSchemaTarget): Record<string, unknown>;
 //#endregion
 //#region src/utils/stateMachine.d.ts
 /**
@@ -673,4 +691,4 @@ declare function hasEvents(instance: FastifyInstance): instance is FastifyInstan
   events: EventsDecorator;
 };
 //#endregion
-export { ArcError, ArcQueryParser, type ArcQueryParserOptions, CircuitBreaker, CircuitBreakerError, type CircuitBreakerOptions, CircuitBreakerRegistry, type CircuitBreakerStats, CircuitState, type CompensationDefinition, type CompensationError, type CompensationHooks, type CompensationResult, type CompensationStep, ConflictError, type ErrorDetails, type EventsDecorator, ForbiddenError, type Guard, type GuardConfig, type JsonSchema, NotFoundError, OrgAccessDeniedError, OrgRequiredError, RateLimitError, ServiceUnavailableError, type StateMachine, type TransitionConfig, UnauthorizedError, ValidationError, convertOpenApiSchemas, convertRouteSchema, createCircuitBreaker, createCircuitBreakerRegistry, createDomainError, createError, createQueryParser, createStateMachine, defineCompensation, defineGuard, deleteResponse, errorResponseSchema, getDefaultCrudSchemas, getListQueryParams, handleRaw, hasEvents, isArcError, isJsonSchema, isZodSchema, itemResponse, listResponse, mutationResponse, paginationSchema, queryParams, responses, successResponseSchema, toJsonSchema, withCompensation, wrapResponse };
+export { ArcError, ArcQueryParser, type ArcQueryParserOptions, CircuitBreaker, CircuitBreakerError, type CircuitBreakerOptions, CircuitBreakerRegistry, type CircuitBreakerStats, CircuitState, type CompensationDefinition, type CompensationError, type CompensationHooks, type CompensationResult, type CompensationStep, ConflictError, type ErrorDetails, type EventsDecorator, ForbiddenError, type Guard, type GuardConfig, type JsonSchema, type JsonSchemaTarget, NotFoundError, OrgAccessDeniedError, OrgRequiredError, RateLimitError, ServiceUnavailableError, type StateMachine, type TransitionConfig, UnauthorizedError, ValidationError, convertOpenApiSchemas, convertRouteSchema, createCircuitBreaker, createCircuitBreakerRegistry, createDomainError, createError, createQueryParser, createStateMachine, defineCompensation, defineGuard, deleteResponse, errorResponseSchema, getDefaultCrudSchemas, getListQueryParams, handleRaw, hasEvents, isArcError, isJsonSchema, isZodSchema, itemResponse, listResponse, mutationResponse, paginationSchema, queryParams, responses, successResponseSchema, toJsonSchema, withCompensation, wrapResponse };

package/dist/utils/index.mjs

@@ -1,5 +1,5 @@
 import { n as createQueryParser, t as ArcQueryParser } from "../queryParser-CgCtsjti.mjs";
-import { a as toJsonSchema, i as isZodSchema, n as convertRouteSchema, r as isJsonSchema, t as convertOpenApiSchemas } from "../schemaConverter-OxfCshus.mjs";
+import { a as toJsonSchema, i as isZodSchema, n as convertRouteSchema, r as isJsonSchema, t as convertOpenApiSchemas } from "../schemaConverter-Y7nCYaLJ.mjs";
 import { a as createCircuitBreaker, i as CircuitState, n as CircuitBreakerError, o as createCircuitBreakerRegistry, r as CircuitBreakerRegistry, t as CircuitBreaker } from "../circuitBreaker-cmi5XDv5.mjs";
 import { _ as withCompensation, a as getListQueryParams, c as mutationResponse, d as responses, f as successResponseSchema, g as defineCompensation, h as defineGuard, i as getDefaultCrudSchemas, l as paginationSchema, m as handleRaw, n as deleteResponse, o as itemResponse, p as wrapResponse, r as errorResponseSchema, s as listResponse, t as createStateMachine, u as queryParams } from "../utils-yYT3HDXt.mjs";
 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-BF2bIOIS.mjs";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/arc",
-  "version": "2.8.4",
+  "version": "2.8.5",
   "description": "Resource-oriented backend framework for Fastify — clean, minimal, powerful, tree-shakable",
   "type": "module",
   "exports": {
@@ -20,6 +20,10 @@
       "types": "./dist/types/index.d.mts",
       "default": "./dist/types/index.mjs"
     },
+    "./types/storage": {
+      "types": "./dist/types/storage.d.mts",
+      "default": "./dist/types/storage.mjs"
+    },
     "./adapters": {
       "types": "./dist/adapters/index.d.mts",
       "default": "./dist/adapters/index.mjs"
@@ -36,6 +40,10 @@
       "types": "./dist/presets/multiTenant.d.mts",
       "default": "./dist/presets/multiTenant.mjs"
     },
+    "./presets/files-upload": {
+      "types": "./dist/presets/filesUpload.d.mts",
+      "default": "./dist/presets/filesUpload.mjs"
+    },
     "./auth": {
       "types": "./dist/auth/index.d.mts",
       "default": "./dist/auth/index.mjs"
@@ -116,6 +124,10 @@
       "types": "./dist/testing/index.d.mts",
       "default": "./dist/testing/index.mjs"
     },
+    "./testing/storage": {
+      "types": "./dist/testing/storageContract.d.mts",
+      "default": "./dist/testing/storageContract.mjs"
+    },
     "./policies": {
       "types": "./dist/policies/index.d.mts",
       "default": "./dist/policies/index.mjs"
@@ -364,7 +376,10 @@
     "@vitest/coverage-v8": "^3.2.4",
     "ajv": "^8.18.0",
     "better-auth": "^1.6.2",
+    "bullmq": "^5.73.5",
+    "dotenv": "^17.4.2",
     "fastify-raw-body": "^5.0.0",
+    "ioredis": "^5.10.1",
     "jsonwebtoken": "^9.0.0",
     "knip": "^6.4.1",
     "mongodb": "^7.1.0",

package/skills/arc/references/events.md

@@ -168,6 +168,35 @@ class KafkaTransport implements EventTransport {
 | Redis Pub/Sub | `@classytic/arc/events/redis` | Multi-instance, real-time |
 | Redis Streams | `@classytic/arc/events/redis-stream` | Ordered, persistent, consumer groups |
 
+### Streams vs Pub/Sub — pick the right one
+
+Choosing wrong loses messages silently. Default to **Streams** for anything business-critical.
+
+| Requirement | Use |
+|---|---|
+| Message MUST NOT be lost (billing, payments, audit) | **Streams** |
+| Real-time notifications, OK to miss when no subscriber is up | Pub/Sub |
+| Need to replay/reprocess past events | **Streams** |
+| Multiple workers processing the same queue | **Streams** (consumer groups) |
+| Simple broadcast to live WebSocket clients | Pub/Sub |
+| Event sourcing or audit trail | **Streams** |
+| Single-instance dev | Memory |
+| At-least-once delivery with durable WAL | **Streams** + outbox pattern |
+
+**Why it matters:** Pub/Sub is fire-and-forget. If no subscriber is connected when you publish, the message is gone. Streams persist until every consumer group acknowledges them — crashes, restarts, and network blips are survivable.
+
+**Defense-in-depth:** pair `eventPlugin` with the transactional outbox (`EventOutbox` + `MemoryOutboxStore` or your own persistent store) for guaranteed delivery even if Redis is unreachable at publish time.
+
+### Redis eviction policy — required for queues and idempotency
+
+When you back events (Streams), jobs (BullMQ), idempotency, or cache with Redis, your Redis instance **must** be configured with `maxmemory-policy: noeviction`. Any other policy can silently evict in-flight stream entries or pending jobs.
+
+- **Self-hosted Redis:** `redis-cli CONFIG SET maxmemory-policy noeviction` (or set in `redis.conf`).
+- **Upstash:** free/paid DBs default to `optimistic-volatile`. You'll see `IMPORTANT! Eviction policy is optimistic-volatile. It should be "noeviction"` in BullMQ logs. **Do one of:** open a support ticket to request `noeviction`, use a dedicated DB for queues, or accept that long-idle jobs may be evicted.
+- **ElastiCache / Redis Cloud:** set the parameter group's `maxmemory-policy` to `noeviction` before pointing arc at it.
+
+For a pure cache DB (no queues, no idempotency), `allkeys-lru` is correct and what you want.
+
 ## Injectable Logger
 
 All transports and retry accept a `logger` option — defaults to `console`, compatible with pino/fastify.log:

package/dist/redis-z3sFr1UP.d.mts

@@ -1,49 +0,0 @@
-import { n as IdempotencyResult, r as IdempotencyStore } from "./interface-B-pe8fhj.mjs";
-
-//#region src/idempotency/stores/redis.d.ts
-interface RedisClient {
-  get(key: string): Promise<string | null>;
-  set(key: string, value: string, options?: {
-    EX?: number;
-    NX?: boolean;
-  }): Promise<string | null>;
-  del(key: string | string[]): Promise<number>;
-  exists(key: string | string[]): Promise<number>;
-  /** SCAN command — compatible with node-redis and ioredis varargs signatures. */
-  scan?(cursor: string | number, ...args: (string | number)[]): Promise<[string | number, string[]]>;
-  quit?(): Promise<string>;
-  disconnect?(): Promise<void>;
-}
-interface RedisIdempotencyStoreOptions {
-  /** Redis client instance */
-  client: RedisClient;
-  /** Key prefix (default: 'idem:') */
-  prefix?: string;
-  /** Lock key prefix (default: 'idem:lock:') */
-  lockPrefix?: string;
-  /** Default TTL in ms (default: 86400000 = 24 hours) */
-  ttlMs?: number;
-}
-declare class RedisIdempotencyStore implements IdempotencyStore {
-  readonly name = "redis";
-  private client;
-  private prefix;
-  private lockPrefix;
-  private ttlMs;
-  constructor(options: RedisIdempotencyStoreOptions);
-  private resultKey;
-  private lockKey;
-  get(key: string): Promise<IdempotencyResult | undefined>;
-  set(key: string, result: Omit<IdempotencyResult, "key">): Promise<void>;
-  tryLock(key: string, requestId: string, ttlMs: number): Promise<boolean>;
-  unlock(key: string, requestId: string): Promise<void>;
-  isLocked(key: string): Promise<boolean>;
-  delete(key: string): Promise<void>;
-  deleteByPrefix(prefix: string): Promise<number>;
-  findByPrefix(prefix: string): Promise<IdempotencyResult | undefined>;
-  /** Scan Redis keys matching a prefix pattern. Falls back to empty if SCAN unavailable. */
-  private scanByPrefix;
-  close(): Promise<void>;
-}
-//#endregion
-export { RedisIdempotencyStore as n, RedisIdempotencyStoreOptions as r, RedisClient as t };