@classytic/arc 1.1.0 → 2.1.2

package/dist/events/transports/redis.d.mts

@@ -0,0 +1,77 @@
+import { i as EventTransport, n as EventHandler, r as EventLogger, t as DomainEvent } from "../../EventTransport-BD2U0BTc.mjs";
+
+//#region src/events/transports/redis.d.ts
+interface RedisLike {
+  publish(channel: string, message: string): Promise<number>;
+  subscribe(...channels: string[]): Promise<unknown>;
+  psubscribe(...patterns: string[]): Promise<unknown>;
+  on(event: string, handler: (...args: unknown[]) => void): unknown;
+  duplicate(): RedisLike;
+  quit(): Promise<unknown>;
+}
+interface RedisEventTransportOptions {
+  /**
+   * Redis channel prefix for all events.
+   * Events are published to `<channel>:<event.type>`.
+   * @default 'arc-events'
+   */
+  channel?: string;
+  /**
+   * If `true`, the transport will NOT call `quit()` on the Redis clients when
+   * `close()` is called. Useful when you manage the Redis lifecycle externally.
+   * @default false
+   */
+  externalLifecycle?: boolean;
+  /**
+   * Logger for error messages (default: console).
+   * Pass `fastify.log` to integrate with your application logger.
+   */
+  logger?: EventLogger;
+}
+declare class RedisEventTransport implements EventTransport {
+  readonly name = "redis";
+  /** Publish-side client (the original client or a duplicate). */
+  private pub;
+  /** Subscribe-side client (always a duplicate — ioredis requires a dedicated connection for subscriptions). */
+  private sub;
+  /** Channel prefix. */
+  private channel;
+  /** Whether we own the Redis client lifecycle. */
+  private externalLifecycle;
+  /** Logger for error messages. */
+  private logger;
+  /** Registered handlers keyed by their *Redis* pattern (with channel prefix). */
+  private handlers;
+  /** Tracks whether the pmessage listener has been attached. */
+  private listenerAttached;
+  constructor(redis: RedisLike, options?: RedisEventTransportOptions);
+  publish(event: DomainEvent): Promise<void>;
+  subscribe(pattern: string, handler: EventHandler): Promise<() => void>;
+  close(): Promise<void>;
+  /**
+   * Attach the Redis message listeners exactly once.
+   */
+  private ensureListener;
+  /**
+   * Dispatch an incoming Redis message to all registered handlers.
+   */
+  private dispatch;
+  /**
+   * Convert an Arc event pattern to a Redis channel/pattern string.
+   *
+   * Arc patterns use `*` as a single-segment wildcard (e.g., `product.*`).
+   * Redis PSUBSCRIBE uses the same glob syntax, so we just prepend the
+   * channel prefix.
+   *
+   * Special case: bare `*` means "all events", which maps to
+   * `<channel>:*` in Redis.
+   */
+  private toRedisPattern;
+  /**
+   * Returns true if the pattern contains glob characters.
+   */
+  private isGlob;
+}
+//#endregion
+export { RedisEventTransport, RedisEventTransport as default, RedisEventTransportOptions, RedisLike };
+//# sourceMappingURL=redis.d.mts.map

package/dist/events/transports/redis.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redis.d.mts","names":[],"sources":["../../../src/events/transports/redis.ts"],"mappings":";;;UAwBiB,SAAA;EACf,OAAA,CAAQ,OAAA,UAAiB,OAAA,WAAkB,OAAA;EAC3C,SAAA,IAAa,QAAA,aAAqB,OAAA;EAClC,UAAA,IAAc,QAAA,aAAqB,OAAA;EACnC,EAAA,CAAG,KAAA,UAAe,OAAA,MAAa,IAAA;EAC/B,SAAA,IAAa,SAAA;EACb,IAAA,IAAQ,OAAA;AAAA;AAAA,UAOO,0BAAA;EATgB;;;;;EAe/B,OAAA;EAbe;;AAOjB;;;EAaE,iBAAA;EAPA;;;;EAaA,MAAA,GAAS,WAAA;AAAA;AAAA,cA8BE,mBAAA,YAA+B,cAAA;EAAA,SACjC,IAAA;;UAGD,GAAA;EAoB+B;EAAA,QAjB/B,GAAA;EAmC2B;EAAA,QAhC3B,OAAA;EAyCiD;EAAA,QAtCjD,iBAAA;EAbkC;EAAA,QAgBlC,MAAA;EAhBgD;EAAA,QAmBhD,QAAA;EAlBC;EAAA,QAqBD,gBAAA;cAEI,KAAA,EAAO,SAAA,EAAW,OAAA,GAAS,0BAAA;EAkBjC,OAAA,CAAQ,KAAA,EAAO,WAAA,GAAc,OAAA;EAS7B,SAAA,CAAU,OAAA,UAAiB,OAAA,EAAS,YAAA,GAAe,OAAA;EAmCnD,KAAA,CAAA,GAAS,OAAA;EAnEP;;;EAAA,QAyFA,cAAA;EApFI;;;EAAA,QAwGJ,QAAA;EAtFa;;;;;;;;;;EAAA,QA6Hb,cAAA;EAvCA;;;EAAA,QA8CA,MAAA;AAAA"}

package/dist/events/transports/redis.mjs

@@ -0,0 +1,125 @@
+//#region src/events/transports/redis.ts
+/**
+* DomainEvent contains a `Date` in `meta.timestamp`.  We serialize it as an
+* ISO string and revive it on the other end so subscribers always receive a
+* proper Date object.
+*/
+function serialize(event) {
+	return JSON.stringify(event, (_key, value) => {
+		if (value instanceof Date) return value.toISOString();
+		return value;
+	});
+}
+function deserialize(raw) {
+	return JSON.parse(raw, (key, value) => {
+		if (key === "timestamp" && typeof value === "string") return new Date(value);
+		return value;
+	});
+}
+var RedisEventTransport = class {
+	name = "redis";
+	/** Publish-side client (the original client or a duplicate). */
+	pub;
+	/** Subscribe-side client (always a duplicate — ioredis requires a dedicated connection for subscriptions). */
+	sub;
+	/** Channel prefix. */
+	channel;
+	/** Whether we own the Redis client lifecycle. */
+	externalLifecycle;
+	/** Logger for error messages. */
+	logger;
+	/** Registered handlers keyed by their *Redis* pattern (with channel prefix). */
+	handlers = /* @__PURE__ */ new Map();
+	/** Tracks whether the pmessage listener has been attached. */
+	listenerAttached = false;
+	constructor(redis, options = {}) {
+		const { channel = "arc-events", externalLifecycle = false, logger = console } = options;
+		this.channel = channel;
+		this.externalLifecycle = externalLifecycle;
+		this.logger = logger;
+		this.pub = redis;
+		this.sub = redis.duplicate();
+	}
+	async publish(event) {
+		const redisChannel = `${this.channel}:${event.type}`;
+		await this.pub.publish(redisChannel, serialize(event));
+	}
+	async subscribe(pattern, handler) {
+		this.ensureListener();
+		const redisPattern = this.toRedisPattern(pattern);
+		if (!this.handlers.has(redisPattern)) {
+			this.handlers.set(redisPattern, /* @__PURE__ */ new Set());
+			if (this.isGlob(redisPattern)) await this.sub.psubscribe(redisPattern);
+			else await this.sub.subscribe(redisPattern);
+		}
+		this.handlers.get(redisPattern).add(handler);
+		return () => {
+			const set = this.handlers.get(redisPattern);
+			if (set) set.delete(handler);
+		};
+	}
+	async close() {
+		this.handlers.clear();
+		if (!this.externalLifecycle) await Promise.all([this.sub.quit(), this.pub.quit()]);
+		else await this.sub.quit();
+	}
+	/**
+	* Attach the Redis message listeners exactly once.
+	*/
+	ensureListener() {
+		if (this.listenerAttached) return;
+		this.listenerAttached = true;
+		this.sub.on("pmessage", (...args) => {
+			const [redisPattern, , message] = args;
+			this.dispatch(redisPattern, message);
+		});
+		this.sub.on("message", (...args) => {
+			const [channel, message] = args;
+			this.dispatch(channel, message);
+		});
+	}
+	/**
+	* Dispatch an incoming Redis message to all registered handlers.
+	*/
+	dispatch(redisPatternOrChannel, raw) {
+		const handlers = this.handlers.get(redisPatternOrChannel);
+		if (!handlers || handlers.size === 0) return;
+		let event;
+		try {
+			event = deserialize(raw);
+		} catch {
+			return;
+		}
+		for (const handler of handlers) try {
+			const result = handler(event);
+			if (result && typeof result.catch === "function") result.catch((err) => {
+				this.logger.error(`[RedisEventTransport] Handler error for ${event.type}:`, err);
+			});
+		} catch (err) {
+			this.logger.error(`[RedisEventTransport] Handler error for ${event.type}:`, err);
+		}
+	}
+	/**
+	* Convert an Arc event pattern to a Redis channel/pattern string.
+	*
+	* Arc patterns use `*` as a single-segment wildcard (e.g., `product.*`).
+	* Redis PSUBSCRIBE uses the same glob syntax, so we just prepend the
+	* channel prefix.
+	*
+	* Special case: bare `*` means "all events", which maps to
+	* `<channel>:*` in Redis.
+	*/
+	toRedisPattern(pattern) {
+		return `${this.channel}:${pattern}`;
+	}
+	/**
+	* Returns true if the pattern contains glob characters.
+	*/
+	isGlob(pattern) {
+		return pattern.includes("*") || pattern.includes("?") || pattern.includes("[");
+	}
+};
+
+//#endregion
+export { RedisEventTransport, RedisEventTransport as default };
+//# sourceMappingURL=redis.mjs.map

package/dist/events/transports/redis.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"redis.mjs","names":[],"sources":["../../../src/events/transports/redis.ts"],"sourcesContent":["/**\n * Redis Event Transport\n *\n * Uses Redis Pub/Sub for cross-process event delivery.\n * Optional dependency — only imported when explicitly used.\n *\n * @example\n * import { RedisEventTransport } from '@classytic/arc/events/redis';\n * import Redis from 'ioredis';\n *\n * const redis = new Redis();\n * const transport = new RedisEventTransport(redis, { channel: 'arc-events' });\n *\n * await app.register(eventPlugin, { transport });\n */\n\nimport type { EventTransport, DomainEvent, EventHandler, EventLogger } from '../EventTransport.js';\n\n// ---------------------------------------------------------------------------\n// Minimal Redis-like interface so consumers don't need ioredis at type level.\n// Any Redis client implementing these methods (ioredis, node-redis wrapper,\n// etc.) will work.\n// ---------------------------------------------------------------------------\n\nexport interface RedisLike {\n  publish(channel: string, message: string): Promise<number>;\n  subscribe(...channels: string[]): Promise<unknown>;\n  psubscribe(...patterns: string[]): Promise<unknown>;\n  on(event: string, handler: (...args: unknown[]) => void): unknown;\n  duplicate(): RedisLike;\n  quit(): Promise<unknown>;\n}\n\n// ---------------------------------------------------------------------------\n// Options\n// ---------------------------------------------------------------------------\n\nexport interface RedisEventTransportOptions {\n  /**\n   * Redis channel prefix for all events.\n   * Events are published to `<channel>:<event.type>`.\n   * @default 'arc-events'\n   */\n  channel?: string;\n\n  /**\n   * If `true`, the transport will NOT call `quit()` on the Redis clients when\n   * `close()` is called. Useful when you manage the Redis lifecycle externally.\n   * @default false\n   */\n  externalLifecycle?: boolean;\n\n  /**\n   * Logger for error messages (default: console).\n   * Pass `fastify.log` to integrate with your application logger.\n   */\n  logger?: EventLogger;\n}\n\n// ---------------------------------------------------------------------------\n// Serialization helpers\n// ---------------------------------------------------------------------------\n\n/**\n * DomainEvent contains a `Date` in `meta.timestamp`.  We serialize it as an\n * ISO string and revive it on the other end so subscribers always receive a\n * proper Date object.\n */\nfunction serialize(event: DomainEvent): string {\n  return JSON.stringify(event, (_key, value) => {\n    if (value instanceof Date) return value.toISOString();\n    return value;\n  });\n}\n\nfunction deserialize(raw: string): DomainEvent {\n  return JSON.parse(raw, (key, value) => {\n    if (key === 'timestamp' && typeof value === 'string') return new Date(value);\n    return value;\n  }) as DomainEvent;\n}\n\n// ---------------------------------------------------------------------------\n// Transport\n// ---------------------------------------------------------------------------\n\nexport class RedisEventTransport implements EventTransport {\n  readonly name = 'redis';\n\n  /** Publish-side client (the original client or a duplicate). */\n  private pub: RedisLike;\n\n  /** Subscribe-side client (always a duplicate — ioredis requires a dedicated connection for subscriptions). */\n  private sub: RedisLike;\n\n  /** Channel prefix. */\n  private channel: string;\n\n  /** Whether we own the Redis client lifecycle. */\n  private externalLifecycle: boolean;\n\n  /** Logger for error messages. */\n  private logger: EventLogger;\n\n  /** Registered handlers keyed by their *Redis* pattern (with channel prefix). */\n  private handlers = new Map<string, Set<EventHandler>>();\n\n  /** Tracks whether the pmessage listener has been attached. */\n  private listenerAttached = false;\n\n  constructor(redis: RedisLike, options: RedisEventTransportOptions = {}) {\n    const { channel = 'arc-events', externalLifecycle = false, logger = console } = options;\n\n    this.channel = channel;\n    this.externalLifecycle = externalLifecycle;\n    this.logger = logger;\n\n    // Use the provided client for publishing, create a dedicated duplicate for subscribing.\n    // ioredis requires separate connections for pub and sub because a client in\n    // subscriber mode cannot issue regular commands.\n    this.pub = redis;\n    this.sub = redis.duplicate();\n  }\n\n  // -----------------------------------------------------------------------\n  // EventTransport.publish\n  // -----------------------------------------------------------------------\n\n  async publish(event: DomainEvent): Promise<void> {\n    const redisChannel = `${this.channel}:${event.type}`;\n    await this.pub.publish(redisChannel, serialize(event));\n  }\n\n  // -----------------------------------------------------------------------\n  // EventTransport.subscribe\n  // -----------------------------------------------------------------------\n\n  async subscribe(pattern: string, handler: EventHandler): Promise<() => void> {\n    this.ensureListener();\n\n    const redisPattern = this.toRedisPattern(pattern);\n\n    if (!this.handlers.has(redisPattern)) {\n      this.handlers.set(redisPattern, new Set());\n\n      // Decide between exact SUBSCRIBE or pattern PSUBSCRIBE.\n      if (this.isGlob(redisPattern)) {\n        await this.sub.psubscribe(redisPattern);\n      } else {\n        await this.sub.subscribe(redisPattern);\n      }\n    }\n\n    this.handlers.get(redisPattern)!.add(handler);\n\n    // Return unsubscribe function.\n    return () => {\n      const set = this.handlers.get(redisPattern);\n      if (set) {\n        set.delete(handler);\n        // Note: we intentionally do NOT punsubscribe/unsubscribe from Redis\n        // when the last handler for a pattern is removed. This keeps the\n        // implementation simple and avoids race conditions. The pattern stays\n        // active until close() is called.\n      }\n    };\n  }\n\n  // -----------------------------------------------------------------------\n  // EventTransport.close\n  // -----------------------------------------------------------------------\n\n  async close(): Promise<void> {\n    this.handlers.clear();\n\n    if (!this.externalLifecycle) {\n      // The subscriber connection is always a duplicate we created, so we\n      // always quit it. The publisher is the client the user passed in, so\n      // we only quit it when externalLifecycle is false.\n      await Promise.all([this.sub.quit(), this.pub.quit()]);\n    } else {\n      // Even with external lifecycle we quit the subscriber duplicate since we\n      // created it ourselves.\n      await this.sub.quit();\n    }\n  }\n\n  // -----------------------------------------------------------------------\n  // Internal helpers\n  // -----------------------------------------------------------------------\n\n  /**\n   * Attach the Redis message listeners exactly once.\n   */\n  private ensureListener(): void {\n    if (this.listenerAttached) return;\n    this.listenerAttached = true;\n\n    // Pattern-matched messages (from psubscribe)\n    this.sub.on('pmessage', (...args: unknown[]) => {\n      const [redisPattern, , message] = args as [string, string, string];\n      this.dispatch(redisPattern, message);\n    });\n\n    // Exact-matched messages (from subscribe)\n    this.sub.on('message', (...args: unknown[]) => {\n      const [channel, message] = args as [string, string];\n      this.dispatch(channel, message);\n    });\n  }\n\n  /**\n   * Dispatch an incoming Redis message to all registered handlers.\n   */\n  private dispatch(redisPatternOrChannel: string, raw: string): void {\n    const handlers = this.handlers.get(redisPatternOrChannel);\n    if (!handlers || handlers.size === 0) return;\n\n    let event: DomainEvent;\n    try {\n      event = deserialize(raw);\n    } catch {\n      // Ignore malformed messages — they may come from non-Arc publishers\n      // sharing the same Redis instance.\n      return;\n    }\n\n    for (const handler of handlers) {\n      try {\n        const result = handler(event);\n        // If the handler returns a promise, catch rejections so one failing\n        // handler doesn't prevent the rest from executing.\n        if (result && typeof (result as Promise<void>).catch === 'function') {\n          (result as Promise<void>).catch((err) => {\n            this.logger.error(`[RedisEventTransport] Handler error for ${event.type}:`, err);\n          });\n        }\n      } catch (err) {\n        this.logger.error(`[RedisEventTransport] Handler error for ${event.type}:`, err);\n      }\n    }\n  }\n\n  /**\n   * Convert an Arc event pattern to a Redis channel/pattern string.\n   *\n   * Arc patterns use `*` as a single-segment wildcard (e.g., `product.*`).\n   * Redis PSUBSCRIBE uses the same glob syntax, so we just prepend the\n   * channel prefix.\n   *\n   * Special case: bare `*` means \"all events\", which maps to\n   * `<channel>:*` in Redis.\n   */\n  private toRedisPattern(pattern: string): string {\n    return `${this.channel}:${pattern}`;\n  }\n\n  /**\n   * Returns true if the pattern contains glob characters.\n   */\n  private isGlob(pattern: string): boolean {\n    return pattern.includes('*') || pattern.includes('?') || pattern.includes('[');\n  }\n}\n\nexport default RedisEventTransport;\n"],"mappings":";;;;;;AAoEA,SAAS,UAAU,OAA4B;AAC7C,QAAO,KAAK,UAAU,QAAQ,MAAM,UAAU;AAC5C,MAAI,iBAAiB,KAAM,QAAO,MAAM,aAAa;AACrD,SAAO;GACP;;AAGJ,SAAS,YAAY,KAA0B;AAC7C,QAAO,KAAK,MAAM,MAAM,KAAK,UAAU;AACrC,MAAI,QAAQ,eAAe,OAAO,UAAU,SAAU,QAAO,IAAI,KAAK,MAAM;AAC5E,SAAO;GACP;;AAOJ,IAAa,sBAAb,MAA2D;CACzD,AAAS,OAAO;;CAGhB,AAAQ;;CAGR,AAAQ;;CAGR,AAAQ;;CAGR,AAAQ;;CAGR,AAAQ;;CAGR,AAAQ,2BAAW,IAAI,KAAgC;;CAGvD,AAAQ,mBAAmB;CAE3B,YAAY,OAAkB,UAAsC,EAAE,EAAE;EACtE,MAAM,EAAE,UAAU,cAAc,oBAAoB,OAAO,SAAS,YAAY;AAEhF,OAAK,UAAU;AACf,OAAK,oBAAoB;AACzB,OAAK,SAAS;AAKd,OAAK,MAAM;AACX,OAAK,MAAM,MAAM,WAAW;;CAO9B,MAAM,QAAQ,OAAmC;EAC/C,MAAM,eAAe,GAAG,KAAK,QAAQ,GAAG,MAAM;AAC9C,QAAM,KAAK,IAAI,QAAQ,cAAc,UAAU,MAAM,CAAC;;CAOxD,MAAM,UAAU,SAAiB,SAA4C;AAC3E,OAAK,gBAAgB;EAErB,MAAM,eAAe,KAAK,eAAe,QAAQ;AAEjD,MAAI,CAAC,KAAK,SAAS,IAAI,aAAa,EAAE;AACpC,QAAK,SAAS,IAAI,8BAAc,IAAI,KAAK,CAAC;AAG1C,OAAI,KAAK,OAAO,aAAa,CAC3B,OAAM,KAAK,IAAI,WAAW,aAAa;OAEvC,OAAM,KAAK,IAAI,UAAU,aAAa;;AAI1C,OAAK,SAAS,IAAI,aAAa,CAAE,IAAI,QAAQ;AAG7C,eAAa;GACX,MAAM,MAAM,KAAK,SAAS,IAAI,aAAa;AAC3C,OAAI,IACF,KAAI,OAAO,QAAQ;;;CAazB,MAAM,QAAuB;AAC3B,OAAK,SAAS,OAAO;AAErB,MAAI,CAAC,KAAK,kBAIR,OAAM,QAAQ,IAAI,CAAC,KAAK,IAAI,MAAM,EAAE,KAAK,IAAI,MAAM,CAAC,CAAC;MAIrD,OAAM,KAAK,IAAI,MAAM;;;;;CAWzB,AAAQ,iBAAuB;AAC7B,MAAI,KAAK,iBAAkB;AAC3B,OAAK,mBAAmB;AAGxB,OAAK,IAAI,GAAG,aAAa,GAAG,SAAoB;GAC9C,MAAM,CAAC,gBAAgB,WAAW;AAClC,QAAK,SAAS,cAAc,QAAQ;IACpC;AAGF,OAAK,IAAI,GAAG,YAAY,GAAG,SAAoB;GAC7C,MAAM,CAAC,SAAS,WAAW;AAC3B,QAAK,SAAS,SAAS,QAAQ;IAC/B;;;;;CAMJ,AAAQ,SAAS,uBAA+B,KAAmB;EACjE,MAAM,WAAW,KAAK,SAAS,IAAI,sBAAsB;AACzD,MAAI,CAAC,YAAY,SAAS,SAAS,EAAG;EAEtC,IAAI;AACJ,MAAI;AACF,WAAQ,YAAY,IAAI;UAClB;AAGN;;AAGF,OAAK,MAAM,WAAW,SACpB,KAAI;GACF,MAAM,SAAS,QAAQ,MAAM;AAG7B,OAAI,UAAU,OAAQ,OAAyB,UAAU,WACvD,CAAC,OAAyB,OAAO,QAAQ;AACvC,SAAK,OAAO,MAAM,2CAA2C,MAAM,KAAK,IAAI,IAAI;KAChF;WAEG,KAAK;AACZ,QAAK,OAAO,MAAM,2CAA2C,MAAM,KAAK,IAAI,IAAI;;;;;;;;;;;;;CAetF,AAAQ,eAAe,SAAyB;AAC9C,SAAO,GAAG,KAAK,QAAQ,GAAG;;;;;CAM5B,AAAQ,OAAO,SAA0B;AACvC,SAAO,QAAQ,SAAS,IAAI,IAAI,QAAQ,SAAS,IAAI,IAAI,QAAQ,SAAS,IAAI"}

package/dist/externalPaths-DlINfKbP.d.mts

@@ -0,0 +1,51 @@
+//#region src/docs/externalPaths.d.ts
+/**
+ * External OpenAPI Path Provider
+ *
+ * Generic interface for injecting non-resource paths into the OpenAPI spec.
+ * Used by auth adapters (Better Auth, custom auth), third-party integrations,
+ * or any system that registers routes outside Arc's resource registry.
+ *
+ * @example
+ * ```typescript
+ * import type { ExternalOpenApiPaths } from '@classytic/arc/docs';
+ *
+ * const authPaths: ExternalOpenApiPaths = {
+ *   paths: {
+ *     '/api/auth/sign-in': {
+ *       post: { summary: 'Sign in', requestBody: { ... } },
+ *     },
+ *   },
+ *   securitySchemes: {
+ *     cookieAuth: { type: 'apiKey', in: 'cookie', name: 'session_token' },
+ *   },
+ *   tags: [{ name: 'Authentication' }],
+ * };
+ * ```
+ */
+/** Pre-built OpenAPI path fragments ready to merge into a spec */
+interface ExternalOpenApiPaths {
+  /** OpenAPI path items keyed by path (e.g. '/api/auth/sign-in') */
+  paths: Record<string, Record<string, unknown>>;
+  /** Additional component schemas to merge into components.schemas */
+  schemas?: Record<string, Record<string, unknown>>;
+  /** Additional security scheme definitions to merge into components.securitySchemes */
+  securitySchemes?: Record<string, Record<string, unknown>>;
+  /** Additional tags for grouping operations */
+  tags?: Array<{
+    name: string;
+    description?: string;
+  }>;
+  /**
+   * Additional security alternatives for Arc resource paths.
+   * Each item is OR'd with bearerAuth. Keys within the same object are AND'd.
+   *
+   * @example
+   * // "bearer OR (api-key AND org-header)"
+   * resourceSecurity: [{ apiKeyAuth: [], orgHeader: [] }]
+   */
+  resourceSecurity?: Array<Record<string, string[]>>;
+}
+//#endregion
+export { ExternalOpenApiPaths as t };
+//# sourceMappingURL=externalPaths-DlINfKbP.d.mts.map

package/dist/externalPaths-DlINfKbP.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"externalPaths-DlINfKbP.d.mts","names":[],"sources":["../src/docs/externalPaths.ts"],"mappings":";;AA0BA;;;;;;;;;;;;;;;;;;;;;;;;UAAiB,oBAAA;EAQA;EANf,KAAA,EAAO,MAAA,SAAe,MAAA;EAetB;EAbA,OAAA,GAAU,MAAA,SAAe,MAAA;EAaA;EAXzB,eAAA,GAAkB,MAAA,SAAe,MAAA;EAWF;EAT/B,IAAA,GAAO,KAAA;IAAQ,IAAA;IAAc,WAAA;EAAA;;;;;;;;;EAS7B,gBAAA,GAAmB,KAAA,CAAM,MAAA;AAAA"}

package/dist/factory/index.d.mts

@@ -0,0 +1,64 @@
+import "../elevation-B_2dRLVP.mjs";
+import "../interface-Ch8HU9uM.mjs";
+import "../types-aYB4V7uN.mjs";
+import "../queryCachePlugin-7THaI5mt.mjs";
+import "../eventPlugin-CTrLH3mt.mjs";
+import "../errorHandler-BbcgBmIH.mjs";
+import { a as CustomPluginAuthOption, c as RawBodyOptions, i as CustomAuthenticatorOption, l as UnderPressureOptions, n as BetterAuthOption, o as JwtAuthOption, r as CreateAppOptions, s as MultipartOptions, t as AuthOption } from "../types-CIgB7UUl.mjs";
+import { FastifyInstance } from "fastify";
+
+//#region src/factory/createApp.d.ts
+/**
+ * Create a production-ready Fastify application with Arc framework
+ *
+ * Security plugins are enabled by default (opt-out):
+ * - helmet (security headers)
+ * - cors (cross-origin requests)
+ * - rateLimit (DDoS protection)
+ * - underPressure (health monitoring)
+ *
+ * Note: Compression is not included due to known Fastify 5 issues.
+ * Use a reverse proxy (Nginx, Caddy) or CDN for compression.
+ *
+ * @param options - Application configuration
+ * @returns Configured Fastify instance
+ */
+declare function createApp(options: CreateAppOptions): Promise<FastifyInstance>;
+/**
+ * Quick factory for common scenarios
+ */
+declare const ArcFactory: {
+  /**
+   * Create production app with strict security
+   */
+  production(options: Omit<CreateAppOptions, "preset">): Promise<FastifyInstance>;
+  /**
+   * Create development app with relaxed security
+   */
+  development(options: Omit<CreateAppOptions, "preset">): Promise<FastifyInstance>;
+  /**
+   * Create testing app with minimal setup
+   */
+  testing(options: Omit<CreateAppOptions, "preset">): Promise<FastifyInstance>;
+};
+//#endregion
+//#region src/factory/presets.d.ts
+/**
+ * Production preset - strict security, performance optimized
+ */
+declare const productionPreset: Partial<CreateAppOptions>;
+/**
+ * Development preset - relaxed security, verbose logging
+ */
+declare const developmentPreset: Partial<CreateAppOptions>;
+/**
+ * Testing preset - minimal setup, fast startup
+ */
+declare const testingPreset: Partial<CreateAppOptions>;
+/**
+ * Get preset by name
+ */
+declare function getPreset(name: 'production' | 'development' | 'testing' | 'edge'): Partial<CreateAppOptions>;
+//#endregion
+export { ArcFactory, type AuthOption, type BetterAuthOption, type CreateAppOptions, type CustomAuthenticatorOption, type CustomPluginAuthOption, type JwtAuthOption, type MultipartOptions, type RawBodyOptions, type UnderPressureOptions, createApp, developmentPreset, getPreset, productionPreset, testingPreset };
+//# sourceMappingURL=index.d.mts.map

package/dist/factory/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../../src/factory/createApp.ts","../../src/factory/presets.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;iBAkHsB,SAAA,CAAU,OAAA,EAAS,gBAAA,GAAmB,OAAA,CAAQ,eAAA;;;;cAievD,UAAA;EAkBsE;;;sBAdvD,IAAA,CAAK,gBAAA,cAA8B,OAAA,CAAQ,eAAA;ECzkB1D;;;uBDglBgB,IAAA,CAAK,gBAAA,cAA8B,OAAA,CAAQ,eAAA;EChlBjB;AA8DvD;;mBDyhByB,IAAA,CAAK,gBAAA,cAA8B,OAAA,CAAQ,eAAA;AAAA;;;;AAnfpE;;cCpGa,gBAAA,EAAkB,OAAA,CAAQ,gBAAA;;;;cA8D1B,iBAAA,EAAmB,OAAA,CAAQ,gBAAA;;;;cA6C3B,aAAA,EAAe,OAAA,CAAQ,gBAAA;;;;iBAiEpB,SAAA,CAAU,IAAA,sDAA0D,OAAA,CAAQ,gBAAA"}

package/dist/factory/index.mjs

@@ -0,0 +1,3 @@
+import { a as getPreset, i as developmentPreset, n as createApp, o as productionPreset, s as testingPreset, t as ArcFactory } from "../createApp-CUgNqegw.mjs";
+
+export { ArcFactory, createApp, developmentPreset, getPreset, productionPreset, testingPreset };

package/dist/fastifyAdapter-BkrGrlFi.d.mts

@@ -0,0 +1,217 @@
+import { s as RequestScope } from "./elevation-B_2dRLVP.mjs";
+import { b as IControllerResponse, x as IRequestContext, y as IController } from "./interface-Ch8HU9uM.mjs";
+import { t as PermissionCheck } from "./types-aYB4V7uN.mjs";
+import { CrudController, CrudRouterOptions, FastifyWithDecorators, RequestContext, RequestWithExtras } from "./types/index.mjs";
+import { FastifyInstance, FastifyReply, FastifyRequest, RouteHandlerMethod } from "fastify";
+
+//#region src/core/createCrudRouter.d.ts
+/**
+ * Create CRUD routes for a controller
+ *
+ * @param fastify - Fastify instance with Arc decorators
+ * @param controller - CRUD controller with handler methods
+ * @param options - Router configuration
+ */
+declare function createCrudRouter<TDoc = unknown>(fastify: FastifyWithDecorators, controller: CrudController<TDoc> | undefined, options?: CrudRouterOptions): void;
+/**
+ * Create permission middleware from PermissionCheck
+ * Useful for custom route registration
+ */
+declare function createPermissionMiddleware(permission: PermissionCheck, resourceName: string, action: string): RouteHandlerMethod | null;
+//#endregion
+//#region src/core/createActionRouter.d.ts
+/**
+ * Action handler function
+ * @param id - Resource ID
+ * @param data - Action-specific data from request body
+ * @param req - Full Fastify request object
+ * @returns Action result (will be wrapped in success response)
+ */
+type ActionHandler<TData = any, TResult = any> = (id: string, data: TData, req: RequestWithExtras) => Promise<TResult>;
+/**
+ * Action router configuration
+ */
+interface ActionRouterConfig {
+  /**
+   * OpenAPI tag for grouping routes
+   */
+  tag?: string;
+  /**
+   * Action handlers map
+   * @example { approve: (id, data, req) => service.approve(id), ... }
+   */
+  actions: Record<string, ActionHandler>;
+  /**
+   * Per-action permission checks (PermissionCheck functions)
+   * @example { approve: requireRoles(['admin', 'manager']), cancel: requireRoles(['admin']) }
+   */
+  actionPermissions?: Record<string, PermissionCheck>;
+  /**
+   * Per-action JSON schema for body validation
+   * @example { dispatch: { transport: { type: 'object' } } }
+   */
+  actionSchemas?: Record<string, Record<string, any>>;
+  /**
+   * Global permission check applied to all actions (if action-specific not defined)
+   */
+  globalAuth?: PermissionCheck;
+  /**
+   * Optional idempotency service
+   * If provided, will handle idempotency-key header
+   */
+  idempotencyService?: IdempotencyService;
+  /**
+   * Custom error handler for action execution failures
+   * @param error - The error thrown by action handler
+   * @param action - The action that failed
+   * @param id - The resource ID
+   * @returns Status code and error response
+   */
+  onError?: (error: Error, action: string, id: string) => {
+    statusCode: number;
+    error: string;
+    code?: string;
+  };
+}
+/**
+ * Idempotency service interface
+ * Apps can provide their own implementation
+ */
+interface IdempotencyService {
+  check(key: string, payload: any): Promise<{
+    isNew: boolean;
+    existingResult?: any;
+  }>;
+  complete(key: string | undefined, result: any): Promise<void>;
+  fail(key: string | undefined, error: Error): Promise<void>;
+}
+/**
+ * Create action-based state transition endpoint
+ *
+ * Registers: POST /:id/action
+ * Body: { action: string, ...actionData }
+ *
+ * @param fastify - Fastify instance
+ * @param config - Action router configuration
+ */
+declare function createActionRouter(fastify: FastifyInstance, config: ActionRouterConfig): void;
+//#endregion
+//#region src/constants.d.ts
+/**
+ * Arc Framework Constants — Single Source of Truth
+ *
+ * Every default value, magic string, and framework constant lives here.
+ * Import from this module instead of hard-coding values inline.
+ *
+ * All exported values are deeply frozen (Object.freeze) to prevent
+ * accidental mutation at runtime — inspired by Go's const blocks
+ * and Rust's immutable-by-default philosophy.
+ */
+/** Standard CRUD operation names */
+declare const CRUD_OPERATIONS: readonly ["list", "get", "create", "update", "delete"];
+type CrudOperation = (typeof CRUD_OPERATIONS)[number];
+/** Mutation operations that emit events */
+declare const MUTATION_OPERATIONS: readonly ["create", "update", "delete"];
+type MutationOperation = (typeof MUTATION_OPERATIONS)[number];
+/** Lifecycle hook phases */
+declare const HOOK_PHASES: readonly ["before", "around", "after"];
+type HookPhase = (typeof HOOK_PHASES)[number];
+/** Hook operations (superset of CRUD — includes 'read' alias for 'get') */
+declare const HOOK_OPERATIONS: readonly ["create", "update", "delete", "read", "list"];
+type HookOperation = (typeof HOOK_OPERATIONS)[number];
+/** Default items per page */
+declare const DEFAULT_LIMIT: 20;
+/** Maximum items per page (framework-wide ceiling) */
+declare const DEFAULT_MAX_LIMIT: 1000;
+/** Default sort field (descending creation date) */
+declare const DEFAULT_SORT: "-createdAt";
+/** Default primary key field name */
+declare const DEFAULT_ID_FIELD: "_id";
+/** Default multi-tenant scoping field */
+declare const DEFAULT_TENANT_FIELD: "organizationId";
+/** Default HTTP method for update routes */
+declare const DEFAULT_UPDATE_METHOD: "PATCH";
+/** System-managed fields that cannot be set via request body */
+declare const SYSTEM_FIELDS: readonly ["_id", "__v", "createdAt", "updatedAt", "deletedAt"];
+/** Maximum regex pattern length (ReDoS mitigation) */
+declare const MAX_REGEX_LENGTH: 200;
+/** Maximum search query length */
+declare const MAX_SEARCH_LENGTH: 200;
+/** Maximum filter nesting depth (prevents filter bombs) */
+declare const MAX_FILTER_DEPTH: 10;
+/**
+ * Query parameters consumed by the framework — never treated as filters.
+ * Shared by all query parsers (Arc built-in, Prisma, custom).
+ */
+declare const RESERVED_QUERY_PARAMS: Readonly<Set<string>>;
+//#endregion
+//#region src/core/fastifyAdapter.d.ts
+/**
+ * Create IRequestContext from Fastify request
+ *
+ * Extracts framework-agnostic context from Fastify-specific request object
+ */
+declare function createRequestContext(req: FastifyRequest): IRequestContext;
+/**
+ * Get typed auth context from an IRequestContext.
+ * Use this in controller overrides to access request context.
+ *
+ * For org scope, use `getControllerScope(req)` instead.
+ */
+declare function getControllerContext(req: IRequestContext): RequestContext;
+/**
+ * Get request scope from an IRequestContext.
+ * Returns the RequestScope set by auth adapters.
+ */
+declare function getControllerScope(req: IRequestContext): RequestScope;
+/**
+ * Send IControllerResponse via Fastify reply
+ *
+ * Converts framework-agnostic response to Fastify response
+ * Applies field masking if specified in request
+ */
+declare function sendControllerResponse<T>(reply: FastifyReply, response: IControllerResponse<T>, request?: FastifyRequest): void;
+/**
+ * Create Fastify route handler from IController method
+ *
+ * Wraps framework-agnostic controller method in Fastify-specific handler
+ *
+ * @example
+ * ```typescript
+ * const controller = new BaseController(repository);
+ *
+ * // Create Fastify handler
+ * const listHandler = createFastifyHandler(controller.list.bind(controller));
+ *
+ * // Register route
+ * fastify.get('/products', listHandler);
+ * ```
+ */
+declare function createFastifyHandler<T>(controllerMethod: (req: IRequestContext) => Promise<IControllerResponse<T>>): (req: FastifyRequest, reply: FastifyReply) => Promise<void>;
+/**
+ * Create Fastify adapters for all CRUD methods of an IController
+ *
+ * Returns Fastify-compatible handlers for each CRUD operation
+ *
+ * @example
+ * ```typescript
+ * const controller = new BaseController(repository);
+ * const handlers = createCrudHandlers(controller);
+ *
+ * fastify.get('/', handlers.list);
+ * fastify.get('/:id', handlers.get);
+ * fastify.post('/', handlers.create);
+ * fastify.patch('/:id', handlers.update);
+ * fastify.delete('/:id', handlers.delete);
+ * ```
+ */
+declare function createCrudHandlers<TDoc>(controller: IController<TDoc>): {
+  list: (req: FastifyRequest, reply: FastifyReply) => Promise<void>;
+  get: (req: FastifyRequest, reply: FastifyReply) => Promise<void>;
+  create: (req: FastifyRequest, reply: FastifyReply) => Promise<void>;
+  update: (req: FastifyRequest, reply: FastifyReply) => Promise<void>;
+  delete: (req: FastifyRequest, reply: FastifyReply) => Promise<void>;
+};
+//#endregion
+export { createCrudRouter as A, MutationOperation as C, ActionRouterConfig as D, ActionHandler as E, IdempotencyService as O, MUTATION_OPERATIONS as S, SYSTEM_FIELDS as T, HookOperation as _, getControllerScope as a, MAX_REGEX_LENGTH as b, CrudOperation as c, DEFAULT_MAX_LIMIT as d, DEFAULT_SORT as f, HOOK_PHASES as g, HOOK_OPERATIONS as h, getControllerContext as i, createPermissionMiddleware as j, createActionRouter as k, DEFAULT_ID_FIELD as l, DEFAULT_UPDATE_METHOD as m, createFastifyHandler as n, sendControllerResponse as o, DEFAULT_TENANT_FIELD as p, createRequestContext as r, CRUD_OPERATIONS as s, createCrudHandlers as t, DEFAULT_LIMIT as u, HookPhase as v, RESERVED_QUERY_PARAMS as w, MAX_SEARCH_LENGTH as x, MAX_FILTER_DEPTH as y };
+//# sourceMappingURL=fastifyAdapter-BkrGrlFi.d.mts.map

package/dist/fastifyAdapter-BkrGrlFi.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fastifyAdapter-BkrGrlFi.d.mts","names":[],"sources":["../src/core/createCrudRouter.ts","../src/core/createActionRouter.ts","../src/constants.ts","../src/core/fastifyAdapter.ts"],"mappings":";;;;;;;;;;;;;;iBA4WgB,gBAAA,gBAAA,CACd,OAAA,EAAS,qBAAA,EACT,UAAA,EAAY,cAAA,CAAe,IAAA,eAC3B,OAAA,GAAS,iBAAA;;;;AAmOX;iBAAgB,0BAAA,CACd,UAAA,EAAY,eAAA,EACZ,YAAA,UACA,MAAA,WACC,kBAAA;;;;;;;;;;KCjiBS,aAAA,gCACV,EAAA,UACA,IAAA,EAAM,KAAA,EACN,GAAA,EAAK,iBAAA,KACF,OAAA,CAAQ,OAAA;;;;UAKI,kBAAA;EALZ;;;EASH,GAAA;EAJe;;;;EAUf,OAAA,EAAS,MAAA,SAAe,aAAA;EAMW;;;;EAAnC,iBAAA,GAAoB,MAAA,SAAe,eAAA;EAiBd;;;;EAXrB,aAAA,GAAgB,MAAA,SAAe,MAAA;EAZ/B;;;EAiBA,UAAA,GAAa,eAAA;EAXO;;;;EAiBpB,kBAAA,GAAqB,kBAAA;EANrB;;;;;;;EAeA,OAAA,IACE,KAAA,EAAO,KAAA,EACP,MAAA,UACA,EAAA;IACK,UAAA;IAAoB,KAAA;IAAe,IAAA;EAAA;AAAA;;AAO5C;;;UAAiB,kBAAA;EACf,KAAA,CAAM,GAAA,UAAa,OAAA,QAAe,OAAA;IAAU,KAAA;IAAgB,cAAA;EAAA;EAC5D,QAAA,CAAS,GAAA,sBAAyB,MAAA,QAAc,OAAA;EAChD,IAAA,CAAK,GAAA,sBAAyB,KAAA,EAAO,KAAA,GAAQ,OAAA;AAAA;;;;;;;;;;iBAY/B,kBAAA,CAAmB,OAAA,EAAS,eAAA,EAAiB,MAAA,EAAQ,kBAAA;;;;;;;;;;AD0OrE;;;;cE5Va,eAAA;AAAA,KAGD,aAAA,WAAwB,eAAA;;cAGvB,mBAAA;AAAA,KAGD,iBAAA,WAA4B,mBAAA;;cAO3B,WAAA;AAAA,KAGD,SAAA,WAAoB,WAAA;;cAGnB,eAAA;AAAA,KAGD,aAAA,WAAwB,eAAA;;cAOvB,aAAA;;cAGA,iBAAA;AF+hBb;AAAA,cE5hBa,YAAA;;cAOA,gBAAA;;cAGA,oBAAA;;cAGA,qBAAA;;cAGA,aAAA;;cASA,gBAAA;;cAGA,iBAAA;AD7Bb;AAAA,cCgCa,gBAAA;;;;;cAUA,qBAAA,EAAqB,QAAA,CAAA,GAAA;;;;;;;;iBCAlB,oBAAA,CAAqB,GAAA,EAAK,cAAA,GAAiB,eAAA;;;;;;;iBA8D3C,oBAAA,CAAqB,GAAA,EAAK,eAAA,GAAkB,cAAA;;;;;iBAQ5C,kBAAA,CAAmB,GAAA,EAAK,eAAA,GAAkB,YAAA;;;;;;;iBAyC1C,sBAAA,GAAA,CACd,KAAA,EAAO,YAAA,EACP,QAAA,EAAU,mBAAA,CAAoB,CAAA,GAC9B,OAAA,GAAU,cAAA;;;;;;;AF5JZ;;;;;;;;;;iBEoQgB,oBAAA,GAAA,CACd,gBAAA,GAAmB,GAAA,EAAK,eAAA,KAAoB,OAAA,CAAQ,mBAAA,CAAoB,CAAA,MAE1D,GAAA,EAAK,cAAA,EAAgB,KAAA,EAAO,YAAA,KAAe,OAAA;;;;;;;;;;AF9P3D;;;;;;;;iBEsRgB,kBAAA,MAAA,CAAyB,UAAA,EAAY,WAAA,CAAY,IAAA;cAxB5C,cAAA,EAAc,KAAA,EAAS,YAAA,KAAe,OAAA;aAAtC,cAAA,EAAc,KAAA,EAAS,YAAA,KAAe,OAAA;gBAAtC,cAAA,EAAc,KAAA,EAAS,YAAA,KAAe,OAAA;gBAAtC,cAAA,EAAc,KAAA,EAAS,YAAA,KAAe,OAAA;gBAAtC,cAAA,EAAc,KAAA,EAAS,YAAA,KAAe,OAAA;AAAA"}