@classytic/arc 1.1.0 → 2.1.2

package/dist/betterAuthOpenApi-BrHKeSAx.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"betterAuthOpenApi-BrHKeSAx.mjs","names":[],"sources":["../src/auth/betterAuthOpenApi.ts"],"sourcesContent":["/**\n * Better Auth OpenAPI Extractor\n *\n * Introspects a Better Auth instance's `api` object and extracts\n * OpenAPI-compatible path definitions from endpoint metadata.\n *\n * Schema conversion uses Zod v4's native `z.toJSONSchema()` via\n * the shared `schemaConverter` utility.\n *\n * @example\n * ```typescript\n * import { extractBetterAuthOpenApi } from '@classytic/arc/auth';\n *\n * const auth = betterAuth({ ... });\n * const openapi = extractBetterAuthOpenApi(auth.api, { basePath: '/api/auth' });\n * // openapi.paths, openapi.securitySchemes, openapi.tags\n * ```\n */\n\nimport type { ExternalOpenApiPaths } from '../docs/externalPaths.js';\nimport { toJsonSchema } from '../utils/schemaConverter.js';\n\n// ============================================================================\n// Types\n// ============================================================================\n\nexport interface BetterAuthOpenApiOptions {\n  /** Base path prefix for auth routes (default: '/api/auth') */\n  basePath?: string;\n  /** Tag name for auth routes in OpenAPI (default: 'Authentication') */\n  tagName?: string;\n  /** Tag description */\n  tagDescription?: string;\n  /** Exclude specific paths from the spec (e.g. ['/ok', '/error']) */\n  excludePaths?: string[];\n  /** Exclude SERVER_ONLY endpoints (default: true) */\n  excludeServerOnly?: boolean;\n  /**\n   * Additional user fields from Better Auth config.\n   * These get merged into signUpEmail/updateUser request body schemas\n   * and the User component schema for $ref resolution.\n   *\n   * Fields with `input: false` are excluded from request bodies\n   * but still appear in the User component schema (output-only).\n   */\n  userFields?: Record<string, {\n    type: string;\n    description?: string;\n    /** Whether this field is required in sign-up (default: false) */\n    required?: boolean;\n    /** Whether this field is accepted in request body (default: true). Set false for output-only fields. */\n    input?: boolean;\n  }>;\n}\n\n// ============================================================================\n// Better Auth Endpoint Discovery\n// ============================================================================\n\n/** Shape of a Better Auth endpoint function with metadata */\ninterface BetterAuthEndpoint {\n  path: string;\n  options: {\n    method?: string | string[];\n    body?: unknown;\n    query?: unknown;\n    metadata?: {\n      openapi?: {\n        summary?: string;\n        description?: string;\n        operationId?: string;\n        responses?: Record<string, unknown>;\n        requestBody?: {\n          content: Record<string, { schema: Record<string, unknown> }>;\n          required?: boolean;\n        };\n        tags?: string[];\n      };\n      SERVER_ONLY?: boolean;\n      [key: string]: unknown;\n    };\n    [key: string]: unknown;\n  };\n}\n\n/**\n * Check if a value looks like a Better Auth endpoint (has .path and .options)\n */\nfunction isBetterAuthEndpoint(value: unknown): value is BetterAuthEndpoint {\n  if (typeof value !== 'function' && typeof value !== 'object') return false;\n  if (!value) return false;\n\n  const v = value as Record<string, unknown>;\n  return (\n    typeof v.path === 'string' &&\n    typeof v.options === 'object' &&\n    v.options !== null\n  );\n}\n\n/**\n * Convert Fastify-style path params (/:id) to OpenAPI-style (/{id})\n */\nfunction toOpenApiPath(path: string): string {\n  return path.replace(/:([^/]+)/g, '{$1}');\n}\n\n/**\n * Extract path parameters from a path string\n */\nfunction extractPathParams(path: string): Array<{ name: string; in: 'path'; required: true; schema: { type: string } }> {\n  const params: Array<{ name: string; in: 'path'; required: true; schema: { type: string } }> = [];\n  const matches = path.matchAll(/:(\\w+)/g);\n  for (const match of matches) {\n    params.push({\n      name: match[1]!,\n      in: 'path',\n      required: true,\n      schema: { type: 'string' },\n    });\n  }\n  return params;\n}\n\n/**\n * Extract OpenAPI paths from a Better Auth instance's API object.\n *\n * Walks `authApi` (the `auth.api` object from Better Auth), discovers\n * endpoints, converts their Zod schemas to JSON Schema via `z.toJSONSchema()`,\n * and returns a complete `ExternalOpenApiPaths` object ready for Arc's spec builder.\n */\nexport function extractBetterAuthOpenApi(\n  authApi: Record<string, unknown>,\n  options: BetterAuthOpenApiOptions = {},\n): ExternalOpenApiPaths {\n  const {\n    basePath = '/api/auth',\n    tagName = 'Authentication',\n    tagDescription = 'Better Auth authentication endpoints',\n    excludePaths = [],\n    excludeServerOnly = true,\n    userFields,\n  } = options;\n\n  const normalizedBase = basePath.replace(/\\/+$/, '');\n  const paths: Record<string, Record<string, unknown>> = {};\n\n  // Auto-detect active plugins by inspecting available endpoints.\n  // This avoids hardcoding plugin-specific schemes — the spec adapts to\n  // whatever plugins the app has registered with Better Auth.\n  const detectedPlugins = detectActivePlugins(authApi);\n\n  // Build security options dynamically: session + bearer are always available,\n  // others are added based on detected plugins.\n  const securityOptions: Array<Record<string, unknown[]>> = [\n    { cookieAuth: [] },\n    { bearerAuth: [] },\n  ];\n  if (detectedPlugins.apiKey) {\n    securityOptions.push({ apiKeyAuth: [] });\n  }\n\n  for (const [key, value] of Object.entries(authApi)) {\n    if (!isBetterAuthEndpoint(value)) continue;\n\n    const endpoint = value;\n    const { path: endpointPath, options: endpointOpts } = endpoint;\n\n    // Skip excluded paths\n    if (excludePaths.includes(endpointPath)) continue;\n\n    // Skip SERVER_ONLY endpoints\n    if (excludeServerOnly && endpointOpts.metadata?.SERVER_ONLY) continue;\n\n    // Build full path\n    const fullPath = toOpenApiPath(`${normalizedBase}${endpointPath}`);\n\n    // Determine HTTP method(s)\n    const methods: string[] = [];\n    if (endpointOpts.method) {\n      if (Array.isArray(endpointOpts.method)) {\n        methods.push(...endpointOpts.method.map(m => m.toLowerCase()));\n      } else {\n        methods.push(endpointOpts.method.toLowerCase());\n      }\n    } else {\n      // Default: GET if no body, POST if body exists\n      methods.push(endpointOpts.body ? 'post' : 'get');\n    }\n\n    // Extract OpenAPI metadata from endpoint\n    const openApiMeta = endpointOpts.metadata?.openapi;\n\n    // Build operation for each method\n    for (const method of methods) {\n      const operation: Record<string, unknown> = {\n        tags: openApiMeta?.tags ?? [tagName],\n        operationId: openApiMeta?.operationId ?? key,\n        summary: openApiMeta?.summary ?? formatOperationSummary(key),\n        security: securityOptions,\n      };\n\n      if (openApiMeta?.description) {\n        operation.description = openApiMeta.description;\n      }\n\n      // Path parameters\n      const pathParams = extractPathParams(endpointPath);\n      const parameters: unknown[] = [...pathParams];\n\n      // Query parameters (for GET/DELETE)\n      if ((method === 'get' || method === 'delete') && endpointOpts.query) {\n        const querySchema = toJsonSchema(endpointOpts.query);\n        if (querySchema && querySchema.type === 'object' && querySchema.properties) {\n          const props = querySchema.properties as Record<string, Record<string, unknown>>;\n          const required = (querySchema.required as string[]) ?? [];\n          for (const [name, prop] of Object.entries(props)) {\n            const paramEntry: Record<string, unknown> = {\n              name,\n              in: 'query',\n              required: required.includes(name),\n              schema: prop,\n            };\n            if (prop.description) {\n              paramEntry.description = prop.description;\n            }\n            parameters.push(paramEntry);\n          }\n        }\n      }\n\n      if (parameters.length > 0) {\n        operation.parameters = parameters;\n      }\n\n      // Request body (for POST/PUT/PATCH)\n      if (method === 'post' || method === 'put' || method === 'patch') {\n        if (openApiMeta?.requestBody) {\n          // Prefer metadata.openapi.requestBody (cleaner than Zod conversion)\n          operation.requestBody = structuredClone(openApiMeta.requestBody);\n        } else if (endpointOpts.body) {\n          // Fall back to Zod body conversion\n          const bodySchema = toJsonSchema(endpointOpts.body);\n          if (bodySchema) {\n            operation.requestBody = {\n              required: true,\n              content: {\n                'application/json': { schema: bodySchema },\n              },\n            };\n          }\n        }\n\n        // Merge userFields into sign-up and update-user request bodies\n        if (userFields && isUserFieldEndpoint(endpointPath) && operation.requestBody) {\n          mergeUserFieldsIntoRequestBody(\n            operation.requestBody as Record<string, unknown>,\n            userFields,\n            endpointPath,\n          );\n        }\n      }\n\n      // Responses\n      if (openApiMeta?.responses) {\n        operation.responses = openApiMeta.responses;\n      } else {\n        // Default responses\n        operation.responses = {\n          '200': { description: 'Success' },\n          '400': { description: 'Bad request' },\n          '401': { description: 'Unauthorized' },\n        };\n      }\n\n      // Add to paths\n      if (!paths[fullPath]) paths[fullPath] = {};\n      (paths[fullPath] as Record<string, unknown>)[method] = operation;\n    }\n  }\n\n  // Build component schemas for $ref resolution (e.g. $ref: \"#/components/schemas/User\")\n  const schemas: Record<string, Record<string, unknown>> = {\n    User: {\n      type: 'object',\n      properties: {\n        id: { type: 'string' },\n        name: { type: 'string' },\n        email: { type: 'string', format: 'email' },\n        emailVerified: { type: 'boolean' },\n        image: { type: 'string', nullable: true },\n        createdAt: { type: 'string', format: 'date-time' },\n        updatedAt: { type: 'string', format: 'date-time' },\n      },\n    },\n    Session: {\n      type: 'object',\n      properties: {\n        id: { type: 'string' },\n        userId: { type: 'string' },\n        token: { type: 'string' },\n        expiresAt: { type: 'string', format: 'date-time' },\n        ipAddress: { type: 'string', nullable: true },\n        userAgent: { type: 'string', nullable: true },\n        createdAt: { type: 'string', format: 'date-time' },\n        updatedAt: { type: 'string', format: 'date-time' },\n      },\n    },\n  };\n\n  // Merge userFields into User component schema (all fields, including input: false)\n  if (userFields) {\n    const userProps = schemas.User!.properties as Record<string, unknown>;\n    for (const [name, field] of Object.entries(userFields)) {\n      const prop: Record<string, unknown> = { type: field.type };\n      if (field.description) prop.description = field.description;\n      userProps[name] = prop;\n    }\n  }\n\n  // Build security schemes — always include cookieAuth, add plugin-specific schemes dynamically\n  const securitySchemes: Record<string, Record<string, unknown>> = {\n    cookieAuth: {\n      type: 'apiKey',\n      in: 'cookie',\n      name: 'better-auth.session_token',\n      description: 'Session cookie set by Better Auth after sign-in',\n    },\n  };\n\n  if (detectedPlugins.apiKey) {\n    securitySchemes.apiKeyAuth = {\n      type: 'apiKey',\n      in: 'header',\n      name: 'x-api-key',\n      description: 'API key for programmatic access. Pass org context via x-organization-id header.',\n    };\n  }\n\n  // Build resourceSecurity — additional auth alternatives for Arc resource paths.\n  // Each item is OR'd with bearerAuth; keys within the same object are AND'd.\n  const resourceSecurity: Array<Record<string, string[]>> = [];\n  if (detectedPlugins.apiKey) {\n    // API key requires org header for tenant context (AND = same object)\n    resourceSecurity.push({ apiKeyAuth: [], orgHeader: [] });\n  }\n\n  return {\n    paths,\n    schemas,\n    securitySchemes,\n    tags: [{ name: tagName, description: tagDescription }],\n    resourceSecurity: resourceSecurity.length > 0 ? resourceSecurity : undefined,\n  };\n}\n\n// ============================================================================\n// Plugin Detection\n// ============================================================================\n\ninterface DetectedPlugins {\n  apiKey: boolean;\n  organization: boolean;\n}\n\n/**\n * Auto-detect active Better Auth plugins by inspecting the API object.\n *\n * Rather than hardcoding plugin-specific behavior, we check for known\n * endpoint signatures that each plugin registers. This way the OpenAPI\n * spec adapts automatically to whatever plugins the app has enabled —\n * no Arc update needed when adding/removing plugins.\n */\nfunction detectActivePlugins(authApi: Record<string, unknown>): DetectedPlugins {\n  const endpointPaths = new Set<string>();\n\n  for (const value of Object.values(authApi)) {\n    if (isBetterAuthEndpoint(value)) {\n      endpointPaths.add(value.path);\n    }\n  }\n\n  return {\n    // apiKey plugin registers /api-key/create\n    apiKey: endpointPaths.has('/api-key/create'),\n    // organization plugin registers /organization/create\n    organization: endpointPaths.has('/organization/create'),\n  };\n}\n\n// ============================================================================\n// Helpers\n// ============================================================================\n\n/**\n * Convert a camelCase key like 'signInEmail' to a readable summary like 'Sign in email'\n */\nfunction formatOperationSummary(key: string): string {\n  return key\n    .replace(/([A-Z])/g, ' $1')\n    .replace(/^./, (s) => s.toUpperCase())\n    .trim();\n}\n\n/**\n * Check if an endpoint path should have userFields merged into its request body.\n */\nfunction isUserFieldEndpoint(path: string): boolean {\n  return path === '/sign-up/email' || path === '/update-user';\n}\n\n/**\n * Merge user-defined fields into an existing requestBody schema.\n * For updateUser, all fields are treated as optional regardless of their `required` setting.\n */\nfunction mergeUserFieldsIntoRequestBody(\n  requestBody: Record<string, unknown>,\n  userFields: NonNullable<BetterAuthOpenApiOptions['userFields']>,\n  endpointPath: string,\n): void {\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  const content = (requestBody as any)?.content?.['application/json'];\n  if (!content?.schema) return;\n\n  const schema = content.schema as Record<string, unknown>;\n\n  if (!schema.properties) schema.properties = {};\n  if (!schema.required) schema.required = [];\n\n  const props = schema.properties as Record<string, unknown>;\n  const required = schema.required as string[];\n\n  for (const [name, field] of Object.entries(userFields)) {\n    // Skip input: false fields (output-only, not accepted in request body)\n    if (field.input === false) continue;\n\n    // For updateUser, all fields are optional\n    const isRequired = endpointPath === '/update-user' ? false : (field.required ?? false);\n\n    const prop: Record<string, unknown> = { type: field.type };\n    if (field.description) prop.description = field.description;\n    props[name] = prop;\n\n    if (isRequired && !required.includes(name)) {\n      required.push(name);\n    }\n  }\n}\n"],"mappings":"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"}

package/dist/cache/index.d.mts

@@ -0,0 +1,146 @@
+import { i as CacheStore, n as CacheSetOptions, r as CacheStats, t as CacheLogger } from "../interface-CZe8IkMf.mjs";
+import { a as CacheEnvelope, c as QueryCache, i as queryCachePlugin, l as QueryCacheConfig, n as QueryCacheDefaults, o as CacheResult, r as QueryCachePluginOptions, s as CacheStatus, t as CrossResourceRule } from "../queryCachePlugin-7THaI5mt.mjs";
+
+//#region src/cache/memory.d.ts
+interface MemoryCacheStoreOptions {
+  /** Default TTL in milliseconds (default: 60_000) */
+  defaultTtlMs?: number;
+  /** Hard upper bound for entries (default: 1000) */
+  maxEntries?: number;
+  /** Background cleanup interval in milliseconds (default: 30_000) */
+  cleanupIntervalMs?: number;
+  /**
+   * Maximum serialized entry size in bytes (default: 256 KiB).
+   * Oversized entries are skipped to prevent memory pressure.
+   */
+  maxEntryBytes?: number;
+  /**
+   * Total memory budget in bytes (default: 50 MiB).
+   * When exceeded, LRU entries are evicted until usage drops below watermark.
+   * Set to 0 to disable (rely on maxEntries only).
+   */
+  maxMemoryBytes?: number;
+  /**
+   * Eviction watermark as fraction of maxMemoryBytes (default: 0.9).
+   * When memory exceeds budget, evict until usage drops to budget * watermark.
+   */
+  evictionWatermark?: number;
+  /** Logger for warnings/errors (default: console) */
+  logger?: CacheLogger;
+}
+/**
+ * In-memory LRU+TTL cache store with hard entry cap and memory budget.
+ * - LRU eviction when `maxEntries` or `maxMemoryBytes` is reached
+ * - TTL expiration on read + periodic cleanup
+ * - Entry size guard to avoid runaway memory usage
+ * - Stats tracking for observability
+ */
+declare class MemoryCacheStore<TValue = unknown> implements CacheStore<TValue> {
+  readonly name = "memory-cache";
+  private readonly cache;
+  private readonly defaultTtlMs;
+  private readonly maxEntries;
+  private readonly maxEntryBytes;
+  private readonly maxMemoryBytes;
+  private readonly evictionWatermark;
+  private readonly logger;
+  private readonly cleanupTimer;
+  private currentBytes;
+  private _hits;
+  private _misses;
+  private _evictions;
+  constructor(options?: MemoryCacheStoreOptions);
+  get(key: string): Promise<TValue | undefined>;
+  set(key: string, value: TValue, options?: CacheSetOptions): Promise<void>;
+  delete(key: string): Promise<void>;
+  clear(): Promise<void>;
+  close(): Promise<void>;
+  stats(): CacheStats;
+  private removeEntry;
+  private evictToLimit;
+  private evictToMemoryLimit;
+  private cleanupExpired;
+  private estimateSize;
+}
+//#endregion
+//#region src/cache/redis.d.ts
+interface RedisCacheClient {
+  get(key: string): Promise<string | null>;
+  set(key: string, value: string, options?: {
+    EX?: number;
+    PX?: number;
+    NX?: boolean;
+    XX?: boolean;
+  }): Promise<string | null | unknown>;
+  del(key: string | string[]): Promise<number>;
+  /**
+   * Optional: enables prefix-based `clear()` and `deleteByPrefix()` via SCAN.
+   * Compatible with both ioredis and node-redis.
+   * If not provided, `clear()` is a safe no-op.
+   */
+  scan?(cursor: string | number, ...args: (string | number)[]): Promise<[string | number, string[]]>;
+  /** Optional: pipeline for batched commands (ioredis compatible) */
+  pipeline?(): RedisPipeline;
+}
+interface RedisPipeline {
+  del(key: string): unknown;
+  exec(): Promise<unknown>;
+}
+interface RedisCacheStoreOptions {
+  /** Redis client instance */
+  client: RedisCacheClient;
+  /** Key prefix for namespacing (default: 'arc:cache:') */
+  prefix?: string;
+  /** Default TTL in milliseconds (default: 60_000) */
+  defaultTtlMs?: number;
+  /** Maximum serialized entry size in bytes. Oversized entries are skipped. */
+  maxEntryBytes?: number;
+}
+/**
+ * Redis-backed cache store.
+ * Suitable for multi-instance and horizontally scaled deployments.
+ * Uses pipeline batching when available for bulk operations.
+ */
+declare class RedisCacheStore<TValue = unknown> implements CacheStore<TValue> {
+  readonly name = "redis-cache";
+  private readonly client;
+  private readonly prefix;
+  private readonly defaultTtlMs;
+  private readonly maxEntryBytes;
+  private _hits;
+  private _misses;
+  constructor(options: RedisCacheStoreOptions);
+  get(key: string): Promise<TValue | undefined>;
+  set(key: string, value: TValue, options?: CacheSetOptions): Promise<void>;
+  delete(key: string): Promise<void>;
+  clear(): Promise<void>;
+  /** Delete all keys matching `this.prefix + prefix + *`. Returns count deleted. */
+  deleteByPrefix(prefix: string): Promise<number>;
+  stats(): CacheStats;
+  private scanAndDelete;
+  private withPrefix;
+}
+//#endregion
+//#region src/cache/keys.d.ts
+/**
+ * Cache Key Utilities
+ *
+ * Deterministic, scope-safe key generation for QueryCache.
+ * Keys include resource version, operation, params hash, and user/org scope
+ * to ensure multi-tenant isolation and O(1) version-based invalidation.
+ */
+/** Build a deterministic cache key for a query */
+declare function buildQueryKey(resource: string, operation: string, resourceVersion: number, params: Record<string, unknown>, userId?: string, orgId?: string): string;
+/** Resource version key — stored in CacheStore, bumped on mutations */
+declare function versionKey(resource: string): string;
+/** Tag version key — stored in CacheStore, bumped on cross-resource invalidation */
+declare function tagVersionKey(tag: string): string;
+/**
+ * Stable hash for query params.
+ * Sorts keys recursively, serializes to JSON, then applies djb2 hash.
+ * Returns hex string.
+ */
+declare function hashParams(params: Record<string, unknown>): string;
+//#endregion
+export { type CacheEnvelope, type CacheLogger, type CacheResult, type CacheSetOptions, type CacheStats, type CacheStatus, type CacheStore, type CrossResourceRule, MemoryCacheStore, type MemoryCacheStoreOptions, QueryCache, type QueryCacheConfig, type QueryCacheDefaults, type QueryCachePluginOptions, type RedisCacheClient, RedisCacheStore, type RedisCacheStoreOptions, type RedisPipeline, buildQueryKey, hashParams, queryCachePlugin, tagVersionKey, versionKey };
+//# sourceMappingURL=index.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../../src/cache/memory.ts","../../src/cache/redis.ts","../../src/cache/keys.ts"],"mappings":";;;;UAQiB,uBAAA;;EAEf,YAAA;EAFe;EAIf,UAAA;;EAEA,iBAAA;EAJA;;;;EASA,aAAA;EAWA;;;;;EALA,cAAA;EAiB2B;;;;EAZ3B,iBAAA;EA0CwB;EAxCxB,MAAA,GAAS,WAAA;AAAA;;;;;;;;cAUE,gBAAA,8BAA8C,UAAA,CAAW,MAAA;EAAA,SAC3D,IAAA;EAAA,iBAEQ,KAAA;EAAA,iBACA,YAAA;EAAA,iBACA,UAAA;EAAA,iBACA,aAAA;EAAA,iBACA,cAAA;EAAA,iBACA,iBAAA;EAAA,iBACA,MAAA;EAAA,iBACA,YAAA;EAAA,QAET,YAAA;EAAA,QACA,KAAA;EAAA,QACA,OAAA;EAAA,QACA,UAAA;cAEI,OAAA,GAAS,uBAAA;EAaf,GAAA,CAAI,GAAA,WAAc,OAAA,CAAQ,MAAA;EAoB1B,GAAA,CAAI,GAAA,UAAa,KAAA,EAAO,MAAA,EAAQ,OAAA,GAAS,eAAA,GAAuB,OAAA;EA0BhE,MAAA,CAAO,GAAA,WAAc,OAAA;EAKrB,KAAA,CAAA,GAAS,OAAA;EAKT,KAAA,CAAA,GAAS,OAAA;EAMf,KAAA,CAAA,GAAS,UAAA;EAAA,QAUD,WAAA;EAAA,QAKA,YAAA;EAAA,QAUA,kBAAA;EAAA,QAYA,cAAA;EAAA,QASA,YAAA;AAAA;;;UClLO,gBAAA;EACf,GAAA,CAAI,GAAA,WAAc,OAAA;EAClB,GAAA,CACE,GAAA,UACA,KAAA,UACA,OAAA;IACE,EAAA;IACA,EAAA;IACA,EAAA;IACA,EAAA;EAAA,IAED,OAAA;EACH,GAAA,CAAI,GAAA,sBAAyB,OAAA;EDA7B;;;;;ECMA,IAAA,EACE,MAAA,sBACG,IAAA,wBACF,OAAA;EDSiB;ECPpB,QAAA,KAAa,aAAA;AAAA;AAAA,UAGE,aAAA;EACf,GAAA,CAAI,GAAA;EACJ,IAAA,IAAQ,OAAA;AAAA;AAAA,UAGO,sBAAA;EDuCS;ECrCxB,MAAA,EAAQ,gBAAA;EDyDuC;ECvD/C,MAAA;EDiF2B;EC/E3B,YAAA;EDyFe;ECvFf,aAAA;AAAA;;;;;;cAQW,eAAA,8BAA6C,UAAA,CAAW,MAAA;EAAA,SAC1D,IAAA;EAAA,iBAEQ,MAAA;EAAA,iBACA,MAAA;EAAA,iBACA,YAAA;EAAA,iBACA,aAAA;EAAA,QAET,KAAA;EAAA,QACA,OAAA;cAEI,OAAA,EAAS,sBAAA;EAOf,GAAA,CAAI,GAAA,WAAc,OAAA,CAAQ,MAAA;EAiB1B,GAAA,CAAI,GAAA,UAAa,KAAA,EAAO,MAAA,EAAQ,OAAA,GAAS,eAAA,GAAuB,OAAA;EAahE,MAAA,CAAO,GAAA,WAAc,OAAA;EAIrB,KAAA,CAAA,GAAS,OAAA;;EAKT,cAAA,CAAe,MAAA,WAAiB,OAAA;EAItC,KAAA,CAAA,GAAS,UAAA;EAAA,QAUK,aAAA;EAAA,QA2BN,UAAA;AAAA;;;;;;;AD3IV;;;;iBECgB,aAAA,CACd,QAAA,UACA,SAAA,UACA,eAAA,UACA,MAAA,EAAQ,MAAA,mBACR,MAAA,WACA,KAAA;;iBASc,UAAA,CAAW,QAAA;;iBAKX,aAAA,CAAc,GAAA;;;;;;iBASd,UAAA,CAAW,MAAA,EAAQ,MAAA"}

package/dist/cache/index.mjs

@@ -0,0 +1,92 @@
+import { i as versionKey, n as hashParams, r as tagVersionKey, t as buildQueryKey } from "../keys-BqNejWup.mjs";
+import { t as MemoryCacheStore } from "../memory-cQgelFOj.mjs";
+import { r as QueryCache, t as queryCachePlugin } from "../queryCachePlugin-DMBnp2Q0.mjs";
+
+//#region src/cache/redis.ts
+/**
+* Redis-backed cache store.
+* Suitable for multi-instance and horizontally scaled deployments.
+* Uses pipeline batching when available for bulk operations.
+*/
+var RedisCacheStore = class {
+	name = "redis-cache";
+	client;
+	prefix;
+	defaultTtlMs;
+	maxEntryBytes;
+	_hits = 0;
+	_misses = 0;
+	constructor(options) {
+		this.client = options.client;
+		this.prefix = options.prefix ?? "arc:cache:";
+		this.defaultTtlMs = options.defaultTtlMs ?? 6e4;
+		this.maxEntryBytes = options.maxEntryBytes ?? 0;
+	}
+	async get(key) {
+		const data = await this.client.get(this.withPrefix(key));
+		if (!data) {
+			this._misses++;
+			return;
+		}
+		try {
+			this._hits++;
+			return JSON.parse(data);
+		} catch {
+			this._misses++;
+			this._hits--;
+			return;
+		}
+	}
+	async set(key, value, options = {}) {
+		const ttlMs = options.ttlMs ?? this.defaultTtlMs;
+		if (!Number.isFinite(ttlMs) || ttlMs <= 0) return;
+		const payload = JSON.stringify(value);
+		if (this.maxEntryBytes > 0 && Buffer.byteLength(payload, "utf8") > this.maxEntryBytes) return;
+		await this.client.set(this.withPrefix(key), payload, { PX: Math.ceil(ttlMs) });
+	}
+	async delete(key) {
+		await this.client.del(this.withPrefix(key));
+	}
+	async clear() {
+		await this.scanAndDelete(`${this.prefix}*`);
+	}
+	/** Delete all keys matching `this.prefix + prefix + *`. Returns count deleted. */
+	async deleteByPrefix(prefix) {
+		return this.scanAndDelete(`${this.prefix}${prefix}*`);
+	}
+	stats() {
+		return {
+			entries: -1,
+			memoryBytes: -1,
+			hits: this._hits,
+			misses: this._misses,
+			evictions: -1
+		};
+	}
+	async scanAndDelete(pattern) {
+		if (!this.client.scan) return 0;
+		const BATCH_SIZE = 200;
+		let cursor = "0";
+		let deleted = 0;
+		do {
+			const [nextCursor, keys] = await this.client.scan(cursor, "MATCH", pattern, "COUNT", BATCH_SIZE);
+			cursor = nextCursor;
+			if (keys.length > 0) {
+				if (this.client.pipeline) {
+					const pipe = this.client.pipeline();
+					for (const key of keys) pipe.del(key);
+					await pipe.exec();
+				} else await this.client.del(keys);
+				deleted += keys.length;
+			}
+		} while (String(cursor) !== "0");
+		return deleted;
+	}
+	withPrefix(key) {
+		return `${this.prefix}${key}`;
+	}
+};
+
+//#endregion
+export { MemoryCacheStore, QueryCache, RedisCacheStore, buildQueryKey, hashParams, queryCachePlugin, tagVersionKey, versionKey };
+//# sourceMappingURL=index.mjs.map

package/dist/cache/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../../src/cache/redis.ts"],"sourcesContent":["import type { CacheSetOptions, CacheStats, CacheStore } from './interface.js';\n\nexport interface RedisCacheClient {\n  get(key: string): Promise<string | null>;\n  set(\n    key: string,\n    value: string,\n    options?: {\n      EX?: number;\n      PX?: number;\n      NX?: boolean;\n      XX?: boolean;\n    }\n  ): Promise<string | null | unknown>;\n  del(key: string | string[]): Promise<number>;\n  /**\n   * Optional: enables prefix-based `clear()` and `deleteByPrefix()` via SCAN.\n   * Compatible with both ioredis and node-redis.\n   * If not provided, `clear()` is a safe no-op.\n   */\n  scan?(\n    cursor: string | number,\n    ...args: (string | number)[]\n  ): Promise<[string | number, string[]]>;\n  /** Optional: pipeline for batched commands (ioredis compatible) */\n  pipeline?(): RedisPipeline;\n}\n\nexport interface RedisPipeline {\n  del(key: string): unknown;\n  exec(): Promise<unknown>;\n}\n\nexport interface RedisCacheStoreOptions {\n  /** Redis client instance */\n  client: RedisCacheClient;\n  /** Key prefix for namespacing (default: 'arc:cache:') */\n  prefix?: string;\n  /** Default TTL in milliseconds (default: 60_000) */\n  defaultTtlMs?: number;\n  /** Maximum serialized entry size in bytes. Oversized entries are skipped. */\n  maxEntryBytes?: number;\n}\n\n/**\n * Redis-backed cache store.\n * Suitable for multi-instance and horizontally scaled deployments.\n * Uses pipeline batching when available for bulk operations.\n */\nexport class RedisCacheStore<TValue = unknown> implements CacheStore<TValue> {\n  readonly name = 'redis-cache';\n\n  private readonly client: RedisCacheClient;\n  private readonly prefix: string;\n  private readonly defaultTtlMs: number;\n  private readonly maxEntryBytes: number;\n\n  private _hits = 0;\n  private _misses = 0;\n\n  constructor(options: RedisCacheStoreOptions) {\n    this.client = options.client;\n    this.prefix = options.prefix ?? 'arc:cache:';\n    this.defaultTtlMs = options.defaultTtlMs ?? 60_000;\n    this.maxEntryBytes = options.maxEntryBytes ?? 0; // 0 = no limit\n  }\n\n  async get(key: string): Promise<TValue | undefined> {\n    const data = await this.client.get(this.withPrefix(key));\n    if (!data) {\n      this._misses++;\n      return undefined;\n    }\n\n    try {\n      this._hits++;\n      return JSON.parse(data) as TValue;\n    } catch {\n      this._misses++;\n      this._hits--; // undo the hit — it's a corrupt entry\n      return undefined;\n    }\n  }\n\n  async set(key: string, value: TValue, options: CacheSetOptions = {}): Promise<void> {\n    const ttlMs = options.ttlMs ?? this.defaultTtlMs;\n    if (!Number.isFinite(ttlMs) || ttlMs <= 0) return;\n\n    const payload = JSON.stringify(value);\n\n    if (this.maxEntryBytes > 0 && Buffer.byteLength(payload, 'utf8') > this.maxEntryBytes) {\n      return; // skip oversized entry\n    }\n\n    await this.client.set(this.withPrefix(key), payload, { PX: Math.ceil(ttlMs) });\n  }\n\n  async delete(key: string): Promise<void> {\n    await this.client.del(this.withPrefix(key));\n  }\n\n  async clear(): Promise<void> {\n    await this.scanAndDelete(`${this.prefix}*`);\n  }\n\n  /** Delete all keys matching `this.prefix + prefix + *`. Returns count deleted. */\n  async deleteByPrefix(prefix: string): Promise<number> {\n    return this.scanAndDelete(`${this.prefix}${prefix}*`);\n  }\n\n  stats(): CacheStats {\n    return {\n      entries: -1, // not cheaply available in Redis\n      memoryBytes: -1,\n      hits: this._hits,\n      misses: this._misses,\n      evictions: -1, // Redis handles eviction internally\n    };\n  }\n\n  private async scanAndDelete(pattern: string): Promise<number> {\n    if (!this.client.scan) return 0;\n\n    const BATCH_SIZE = 200;\n    let cursor: string | number = '0';\n    let deleted = 0;\n\n    do {\n      const [nextCursor, keys] = await this.client.scan(\n        cursor, 'MATCH', pattern, 'COUNT', BATCH_SIZE,\n      );\n      cursor = nextCursor;\n      if (keys.length > 0) {\n        if (this.client.pipeline) {\n          const pipe = this.client.pipeline();\n          for (const key of keys) pipe.del(key);\n          await pipe.exec();\n        } else {\n          await this.client.del(keys);\n        }\n        deleted += keys.length;\n      }\n    } while (String(cursor) !== '0');\n\n    return deleted;\n  }\n\n  private withPrefix(key: string): string {\n    return `${this.prefix}${key}`;\n  }\n}\n\nexport default RedisCacheStore;\n"],"mappings":";;;;;;;;;;AAiDA,IAAa,kBAAb,MAA6E;CAC3E,AAAS,OAAO;CAEhB,AAAiB;CACjB,AAAiB;CACjB,AAAiB;CACjB,AAAiB;CAEjB,AAAQ,QAAQ;CAChB,AAAQ,UAAU;CAElB,YAAY,SAAiC;AAC3C,OAAK,SAAS,QAAQ;AACtB,OAAK,SAAS,QAAQ,UAAU;AAChC,OAAK,eAAe,QAAQ,gBAAgB;AAC5C,OAAK,gBAAgB,QAAQ,iBAAiB;;CAGhD,MAAM,IAAI,KAA0C;EAClD,MAAM,OAAO,MAAM,KAAK,OAAO,IAAI,KAAK,WAAW,IAAI,CAAC;AACxD,MAAI,CAAC,MAAM;AACT,QAAK;AACL;;AAGF,MAAI;AACF,QAAK;AACL,UAAO,KAAK,MAAM,KAAK;UACjB;AACN,QAAK;AACL,QAAK;AACL;;;CAIJ,MAAM,IAAI,KAAa,OAAe,UAA2B,EAAE,EAAiB;EAClF,MAAM,QAAQ,QAAQ,SAAS,KAAK;AACpC,MAAI,CAAC,OAAO,SAAS,MAAM,IAAI,SAAS,EAAG;EAE3C,MAAM,UAAU,KAAK,UAAU,MAAM;AAErC,MAAI,KAAK,gBAAgB,KAAK,OAAO,WAAW,SAAS,OAAO,GAAG,KAAK,cACtE;AAGF,QAAM,KAAK,OAAO,IAAI,KAAK,WAAW,IAAI,EAAE,SAAS,EAAE,IAAI,KAAK,KAAK,MAAM,EAAE,CAAC;;CAGhF,MAAM,OAAO,KAA4B;AACvC,QAAM,KAAK,OAAO,IAAI,KAAK,WAAW,IAAI,CAAC;;CAG7C,MAAM,QAAuB;AAC3B,QAAM,KAAK,cAAc,GAAG,KAAK,OAAO,GAAG;;;CAI7C,MAAM,eAAe,QAAiC;AACpD,SAAO,KAAK,cAAc,GAAG,KAAK,SAAS,OAAO,GAAG;;CAGvD,QAAoB;AAClB,SAAO;GACL,SAAS;GACT,aAAa;GACb,MAAM,KAAK;GACX,QAAQ,KAAK;GACb,WAAW;GACZ;;CAGH,MAAc,cAAc,SAAkC;AAC5D,MAAI,CAAC,KAAK,OAAO,KAAM,QAAO;EAE9B,MAAM,aAAa;EACnB,IAAI,SAA0B;EAC9B,IAAI,UAAU;AAEd,KAAG;GACD,MAAM,CAAC,YAAY,QAAQ,MAAM,KAAK,OAAO,KAC3C,QAAQ,SAAS,SAAS,SAAS,WACpC;AACD,YAAS;AACT,OAAI,KAAK,SAAS,GAAG;AACnB,QAAI,KAAK,OAAO,UAAU;KACxB,MAAM,OAAO,KAAK,OAAO,UAAU;AACnC,UAAK,MAAM,OAAO,KAAM,MAAK,IAAI,IAAI;AACrC,WAAM,KAAK,MAAM;UAEjB,OAAM,KAAK,OAAO,IAAI,KAAK;AAE7B,eAAW,KAAK;;WAEX,OAAO,OAAO,KAAK;AAE5B,SAAO;;CAGT,AAAQ,WAAW,KAAqB;AACtC,SAAO,GAAG,KAAK,SAAS"}

package/dist/caching-Bl28lYsR.mjs

@@ -0,0 +1,94 @@
+import { t as __exportAll } from "./chunk-C7Uep-_p.mjs";
+import fp from "fastify-plugin";
+
+//#region src/plugins/caching.ts
+/**
+* Caching Plugin
+*
+* Adds ETag and Cache-Control headers to GET/HEAD responses.
+* Supports conditional requests (304 Not Modified) for bandwidth savings.
+*
+* @example
+* import { cachingPlugin } from '@classytic/arc/plugins';
+*
+* // Basic — ETag + conditional requests, no browser caching
+* await fastify.register(cachingPlugin);
+*
+* // With cache rules per path
+* await fastify.register(cachingPlugin, {
+*   rules: [
+*     { match: '/api/products', maxAge: 60 },
+*     { match: '/api/categories', maxAge: 300, staleWhileRevalidate: 60 },
+*   ],
+* });
+*/
+var caching_exports = /* @__PURE__ */ __exportAll({
+	cachingPlugin: () => cachingPlugin,
+	default: () => caching_default
+});
+const FNV_OFFSET = 2166136261;
+const FNV_PRIME = 16777619;
+/** Fast non-cryptographic hash for ETag generation */
+function fnv1a(data) {
+	let hash = FNV_OFFSET;
+	for (let i = 0; i < data.length; i++) {
+		hash ^= data.charCodeAt(i);
+		hash = hash * FNV_PRIME >>> 0;
+	}
+	return hash.toString(36);
+}
+const cachingPlugin = async (fastify, opts = {}) => {
+	const { maxAge = 0, etag = true, conditional = true, methods = ["GET", "HEAD"], exclude = [], rules = [] } = opts;
+	const methodSet = new Set(methods.map((m) => m.toUpperCase()));
+	/** Find the first matching rule for a URL path */
+	function findRule(url) {
+		const path = url.split("?")[0];
+		return rules.find((r) => path.startsWith(r.match));
+	}
+	/** Build Cache-Control header value */
+	function buildCacheControl(rule) {
+		const age = rule?.maxAge ?? maxAge;
+		if (age <= 0) return "no-cache";
+		const parts = [];
+		parts.push(rule?.private ? "private" : "public");
+		parts.push(`max-age=${age}`);
+		if (rule?.staleWhileRevalidate) parts.push(`stale-while-revalidate=${rule.staleWhileRevalidate}`);
+		return parts.join(", ");
+	}
+	fastify.addHook("onSend", async (request, reply, payload) => {
+		const url = request.url;
+		if (exclude.some((p) => url.startsWith(p))) return payload;
+		const method = request.method.toUpperCase();
+		if (!methodSet.has(method)) {
+			if (!reply.hasHeader("cache-control")) reply.header("cache-control", "no-store");
+			return payload;
+		}
+		const statusCode = reply.statusCode;
+		if (statusCode < 200 || statusCode >= 300) return payload;
+		if (!reply.hasHeader("cache-control")) {
+			const rule = findRule(url);
+			reply.header("cache-control", buildCacheControl(rule));
+		}
+		if (etag && payload) {
+			const tag = `"${fnv1a(typeof payload === "string" ? payload : String(payload))}"`;
+			reply.header("etag", tag);
+			if (conditional) {
+				const ifNoneMatch = request.headers["if-none-match"];
+				if (ifNoneMatch && ifNoneMatch === tag) {
+					reply.code(304);
+					return "";
+				}
+			}
+		}
+		return payload;
+	});
+	fastify.log?.debug?.("Caching plugin registered");
+};
+var caching_default = fp(cachingPlugin, {
+	name: "arc-caching",
+	fastify: "5.x"
+});
+
+//#endregion
+export { caching_default as n, caching_exports as r, cachingPlugin as t };
+//# sourceMappingURL=caching-Bl28lYsR.mjs.map

package/dist/caching-Bl28lYsR.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"caching-Bl28lYsR.mjs","names":[],"sources":["../src/plugins/caching.ts"],"sourcesContent":["/**\n * Caching Plugin\n *\n * Adds ETag and Cache-Control headers to GET/HEAD responses.\n * Supports conditional requests (304 Not Modified) for bandwidth savings.\n *\n * @example\n * import { cachingPlugin } from '@classytic/arc/plugins';\n *\n * // Basic — ETag + conditional requests, no browser caching\n * await fastify.register(cachingPlugin);\n *\n * // With cache rules per path\n * await fastify.register(cachingPlugin, {\n *   rules: [\n *     { match: '/api/products', maxAge: 60 },\n *     { match: '/api/categories', maxAge: 300, staleWhileRevalidate: 60 },\n *   ],\n * });\n */\n\nimport fp from 'fastify-plugin';\nimport type { FastifyInstance, FastifyPluginAsync } from 'fastify';\n\nexport interface CachingRule {\n  /** Path prefix to match (e.g., '/api/products') */\n  match: string;\n  /** Cache-Control max-age in seconds */\n  maxAge: number;\n  /** Cache-Control: private vs public (default: public) */\n  private?: boolean;\n  /** stale-while-revalidate directive in seconds */\n  staleWhileRevalidate?: number;\n}\n\nexport interface CachingOptions {\n  /** Default max-age in seconds for Cache-Control (default: 0 = no-cache) */\n  maxAge?: number;\n  /** Enable ETag generation (default: true) */\n  etag?: boolean;\n  /** Enable conditional requests — 304 Not Modified (default: true) */\n  conditional?: boolean;\n  /** HTTP methods to cache (default: ['GET', 'HEAD']) */\n  methods?: string[];\n  /** Paths to exclude from caching (prefix match) */\n  exclude?: string[];\n  /** Custom cache rules per path prefix */\n  rules?: CachingRule[];\n}\n\n// ============================================================================\n// FNV-1a Hash (fast, non-cryptographic)\n// ============================================================================\n\nconst FNV_OFFSET = 2166136261;\nconst FNV_PRIME = 16777619;\n\n/** Fast non-cryptographic hash for ETag generation */\nfunction fnv1a(data: string): string {\n  let hash = FNV_OFFSET;\n  for (let i = 0; i < data.length; i++) {\n    hash ^= data.charCodeAt(i);\n    hash = (hash * FNV_PRIME) >>> 0;\n  }\n  return hash.toString(36);\n}\n\n// ============================================================================\n// Plugin\n// ============================================================================\n\nconst cachingPlugin: FastifyPluginAsync<CachingOptions> = async (\n  fastify: FastifyInstance,\n  opts: CachingOptions = {},\n) => {\n  const {\n    maxAge = 0,\n    etag = true,\n    conditional = true,\n    methods = ['GET', 'HEAD'],\n    exclude = [],\n    rules = [],\n  } = opts;\n\n  const methodSet = new Set(methods.map((m) => m.toUpperCase()));\n\n  /** Find the first matching rule for a URL path */\n  function findRule(url: string): CachingRule | undefined {\n    // Strip query string\n    const path = url.split('?')[0]!;\n    return rules.find((r) => path.startsWith(r.match));\n  }\n\n  /** Build Cache-Control header value */\n  function buildCacheControl(rule?: CachingRule): string {\n    const age = rule?.maxAge ?? maxAge;\n    if (age <= 0) return 'no-cache';\n\n    const parts: string[] = [];\n    parts.push(rule?.private ? 'private' : 'public');\n    parts.push(`max-age=${age}`);\n    if (rule?.staleWhileRevalidate) {\n      parts.push(`stale-while-revalidate=${rule.staleWhileRevalidate}`);\n    }\n    return parts.join(', ');\n  }\n\n  // onSend hook — runs just before the response is sent\n  fastify.addHook('onSend', async (request, reply, payload) => {\n    const url = request.url;\n\n    // Skip excluded paths\n    if (exclude.some((p) => url.startsWith(p))) {\n      return payload;\n    }\n\n    const method = request.method.toUpperCase();\n\n    // Mutation methods always get no-store\n    if (!methodSet.has(method)) {\n      if (!reply.hasHeader('cache-control')) {\n        reply.header('cache-control', 'no-store');\n      }\n      return payload;\n    }\n\n    // Only cache 2xx responses\n    const statusCode = reply.statusCode;\n    if (statusCode < 200 || statusCode >= 300) {\n      return payload;\n    }\n\n    // Don't override user-set Cache-Control\n    if (!reply.hasHeader('cache-control')) {\n      const rule = findRule(url);\n      reply.header('cache-control', buildCacheControl(rule));\n    }\n\n    // ETag generation\n    if (etag && payload) {\n      const body = typeof payload === 'string' ? payload : String(payload);\n      const tag = `\"${fnv1a(body)}\"`;\n      reply.header('etag', tag);\n\n      // Conditional request: check If-None-Match\n      if (conditional) {\n        const ifNoneMatch = request.headers['if-none-match'];\n        if (ifNoneMatch && ifNoneMatch === tag) {\n          reply.code(304);\n          return '';\n        }\n      }\n    }\n\n    return payload;\n  });\n\n  fastify.log?.debug?.('Caching plugin registered');\n};\n\nexport default fp(cachingPlugin, {\n  name: 'arc-caching',\n  fastify: '5.x',\n});\n\nexport { cachingPlugin };\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;AAsDA,MAAM,aAAa;AACnB,MAAM,YAAY;;AAGlB,SAAS,MAAM,MAAsB;CACnC,IAAI,OAAO;AACX,MAAK,IAAI,IAAI,GAAG,IAAI,KAAK,QAAQ,KAAK;AACpC,UAAQ,KAAK,WAAW,EAAE;AAC1B,SAAQ,OAAO,cAAe;;AAEhC,QAAO,KAAK,SAAS,GAAG;;AAO1B,MAAM,gBAAoD,OACxD,SACA,OAAuB,EAAE,KACtB;CACH,MAAM,EACJ,SAAS,GACT,OAAO,MACP,cAAc,MACd,UAAU,CAAC,OAAO,OAAO,EACzB,UAAU,EAAE,EACZ,QAAQ,EAAE,KACR;CAEJ,MAAM,YAAY,IAAI,IAAI,QAAQ,KAAK,MAAM,EAAE,aAAa,CAAC,CAAC;;CAG9D,SAAS,SAAS,KAAsC;EAEtD,MAAM,OAAO,IAAI,MAAM,IAAI,CAAC;AAC5B,SAAO,MAAM,MAAM,MAAM,KAAK,WAAW,EAAE,MAAM,CAAC;;;CAIpD,SAAS,kBAAkB,MAA4B;EACrD,MAAM,MAAM,MAAM,UAAU;AAC5B,MAAI,OAAO,EAAG,QAAO;EAErB,MAAM,QAAkB,EAAE;AAC1B,QAAM,KAAK,MAAM,UAAU,YAAY,SAAS;AAChD,QAAM,KAAK,WAAW,MAAM;AAC5B,MAAI,MAAM,qBACR,OAAM,KAAK,0BAA0B,KAAK,uBAAuB;AAEnE,SAAO,MAAM,KAAK,KAAK;;AAIzB,SAAQ,QAAQ,UAAU,OAAO,SAAS,OAAO,YAAY;EAC3D,MAAM,MAAM,QAAQ;AAGpB,MAAI,QAAQ,MAAM,MAAM,IAAI,WAAW,EAAE,CAAC,CACxC,QAAO;EAGT,MAAM,SAAS,QAAQ,OAAO,aAAa;AAG3C,MAAI,CAAC,UAAU,IAAI,OAAO,EAAE;AAC1B,OAAI,CAAC,MAAM,UAAU,gBAAgB,CACnC,OAAM,OAAO,iBAAiB,WAAW;AAE3C,UAAO;;EAIT,MAAM,aAAa,MAAM;AACzB,MAAI,aAAa,OAAO,cAAc,IACpC,QAAO;AAIT,MAAI,CAAC,MAAM,UAAU,gBAAgB,EAAE;GACrC,MAAM,OAAO,SAAS,IAAI;AAC1B,SAAM,OAAO,iBAAiB,kBAAkB,KAAK,CAAC;;AAIxD,MAAI,QAAQ,SAAS;GAEnB,MAAM,MAAM,IAAI,MADH,OAAO,YAAY,WAAW,UAAU,OAAO,QAAQ,CACzC,CAAC;AAC5B,SAAM,OAAO,QAAQ,IAAI;AAGzB,OAAI,aAAa;IACf,MAAM,cAAc,QAAQ,QAAQ;AACpC,QAAI,eAAe,gBAAgB,KAAK;AACtC,WAAM,KAAK,IAAI;AACf,YAAO;;;;AAKb,SAAO;GACP;AAEF,SAAQ,KAAK,QAAQ,4BAA4B;;AAGnD,sBAAe,GAAG,eAAe;CAC/B,MAAM;CACN,SAAS;CACV,CAAC"}

package/dist/chunk-C7Uep-_p.mjs

@@ -0,0 +1,20 @@
+import { createRequire } from "node:module";
+
+//#region \0rolldown/runtime.js
+var __defProp = Object.defineProperty;
+var __exportAll = (all, no_symbols) => {
+	let target = {};
+	for (var name in all) {
+		__defProp(target, name, {
+			get: all[name],
+			enumerable: true
+		});
+	}
+	if (!no_symbols) {
+		__defProp(target, Symbol.toStringTag, { value: "Module" });
+	}
+	return target;
+};
+
+//#endregion
+export { __exportAll as t };