@classytic/arc 1.1.0 → 2.1.2

package/dist/interface-Ch8HU9uM.d.mts

@@ -0,0 +1,1098 @@
+import { n as FieldPermissionMap } from "./fields-DyaDVX4J.mjs";
+import { i as UserBase } from "./types-aYB4V7uN.mjs";
+import { AdditionalRoute, AnyRecord, ArcInternalMetadata, ControllerQueryOptions, CrudRouteKey, CrudSchemas, EventDefinition, IntrospectionData, MiddlewareConfig, OpenApiSchemas, QueryParserInterface, RateLimitConfig, RegistryEntry, RegistryStats, RequestContext, ResourceCacheConfig, ResourceConfig, ResourceMetadata, ResourcePermissions, RouteSchemaOptions } from "./types/index.mjs";
+import { FastifyPluginAsync, FastifyReply, FastifyRequest } from "fastify";
+
+//#region src/hooks/HookSystem.d.ts
+type HookPhase = 'before' | 'around' | 'after';
+type HookOperation = 'create' | 'update' | 'delete' | 'read' | 'list';
+interface HookContext<T = AnyRecord> {
+  resource: string;
+  operation: HookOperation;
+  phase: HookPhase;
+  data?: T;
+  result?: T | T[];
+  user?: UserBase;
+  context?: RequestContext;
+  meta?: AnyRecord;
+}
+type HookHandler<T = AnyRecord> = (ctx: HookContext<T>) => void | Promise<void> | T | Promise<T>;
+/**
+ * Around hook handler — wraps the core operation.
+ * Call `next()` to proceed to the next around hook or the actual operation.
+ */
+type AroundHookHandler<T = AnyRecord> = (ctx: HookContext<T>, next: () => Promise<T | undefined>) => T | undefined | Promise<T | undefined>;
+interface HookRegistration {
+  /** Hook name for dependency resolution and debugging */
+  name?: string;
+  resource: string;
+  operation: HookOperation;
+  phase: HookPhase;
+  handler: HookHandler;
+  priority: number;
+  /** Names of hooks that must execute before this one */
+  dependsOn?: string[];
+}
+interface HookSystemOptions {
+  /** Custom logger for error/warning reporting. Defaults to console */
+  logger?: {
+    error: (message: string, ...args: unknown[]) => void;
+    warn?: (message: string, ...args: unknown[]) => void;
+  };
+}
+declare class HookSystem {
+  private hooks;
+  private logger;
+  private warn;
+  constructor(options?: HookSystemOptions);
+  /**
+   * Generate hook key
+   */
+  private getKey;
+  /**
+   * Register a hook
+   * Supports both object parameter and positional arguments
+   */
+  register<T = AnyRecord>(resourceOrOptions: string | {
+    name?: string;
+    resource: string;
+    operation: HookOperation;
+    phase: HookPhase;
+    handler: HookHandler<T>;
+    priority?: number;
+    dependsOn?: string[];
+  }, operation?: HookOperation, phase?: HookPhase, handler?: HookHandler<T>, priority?: number): () => void;
+  /**
+   * Register before hook
+   */
+  before<T = AnyRecord>(resource: string, operation: HookOperation, handler: HookHandler<T>, priority?: number): () => void;
+  /**
+   * Register after hook
+   */
+  after<T = AnyRecord>(resource: string, operation: HookOperation, handler: HookHandler<T>, priority?: number): () => void;
+  /**
+   * Register around hook — wraps the core operation.
+   * Call `next()` inside the handler to proceed.
+   */
+  around<T = AnyRecord>(resource: string, operation: HookOperation, handler: AroundHookHandler<T>, priority?: number): () => void;
+  /**
+   * Execute around hooks as a nested middleware chain.
+   * Each around hook receives `next()` to call the next hook or the core operation.
+   */
+  executeAround<T = AnyRecord>(resource: string, operation: HookOperation, data: T, execute: () => Promise<T | undefined>, options?: {
+    user?: UserBase;
+    context?: RequestContext;
+    meta?: AnyRecord;
+  }): Promise<T | undefined>;
+  /**
+   * Execute hooks for a given context
+   */
+  execute<T = AnyRecord>(ctx: HookContext<T>): Promise<T | undefined>;
+  /**
+   * Execute before hooks
+   */
+  executeBefore<T = AnyRecord>(resource: string, operation: HookOperation, data: T, options?: {
+    user?: UserBase;
+    context?: RequestContext;
+    meta?: AnyRecord;
+  }): Promise<T>;
+  /**
+   * Execute after hooks
+   * Errors in after hooks are logged but don't fail the request
+   */
+  executeAfter<T = AnyRecord>(resource: string, operation: HookOperation, result: T | T[], options?: {
+    user?: UserBase;
+    context?: RequestContext;
+    meta?: AnyRecord;
+  }): Promise<void>;
+  /**
+   * Topological sort with Kahn's algorithm.
+   * Hooks with `dependsOn` are ordered after their dependencies.
+   * Within the same dependency level, priority ordering is preserved.
+   * Hooks without names or dependencies pass through in their original order.
+   */
+  private topologicalSort;
+  /**
+   * Get all registered hooks
+   */
+  getAll(): HookRegistration[];
+  /**
+   * Get hooks for a specific resource
+   */
+  getForResource(resource: string): HookRegistration[];
+  /**
+   * Get hooks matching filter criteria.
+   * Useful for debugging and testing specific hook combinations.
+   *
+   * @example
+   * ```typescript
+   * // Find all before-create hooks for products (including wildcards)
+   * const hooks = hookSystem.getRegistered({
+   *   resource: 'product',
+   *   operation: 'create',
+   *   phase: 'before',
+   * });
+   * ```
+   */
+  getRegistered(filter?: {
+    resource?: string;
+    operation?: HookOperation;
+    phase?: HookPhase;
+  }): HookRegistration[];
+  /**
+   * Get a structured summary of all registered hooks for debugging.
+   *
+   * @example
+   * ```typescript
+   * const info = hookSystem.inspect();
+   * // { total: 12, resources: { product: [...], '*': [...] }, summary: [...] }
+   * ```
+   */
+  inspect(): {
+    total: number;
+    resources: Record<string, HookRegistration[]>;
+    summary: Array<{
+      name?: string;
+      key: string;
+      priority: number;
+      dependsOn?: string[];
+    }>;
+  };
+  /**
+   * Check if any hooks exist for a specific resource/operation/phase combination.
+   */
+  has(resource: string, operation: HookOperation, phase: HookPhase): boolean;
+  /**
+   * Clear all hooks
+   */
+  clear(): void;
+  /**
+   * Clear hooks for a specific resource
+   */
+  clearResource(resource: string): void;
+}
+/**
+ * Create a new isolated HookSystem instance
+ *
+ * Use this for:
+ * - Test isolation (parallel test suites)
+ * - Multiple app instances with independent hooks
+ *
+ * @example
+ * const hooks = createHookSystem();
+ * await app.register(arcCorePlugin, { hookSystem: hooks });
+ *
+ * @example With custom logger
+ * const hooks = createHookSystem({ logger: fastify.log });
+ */
+declare function createHookSystem(options?: HookSystemOptions): HookSystem;
+interface DefineHookOptions<T = AnyRecord> {
+  /** Unique hook name (required for dependency resolution) */
+  name: string;
+  /** Target resource */
+  resource: string;
+  /** CRUD operation */
+  operation: HookOperation;
+  /** before or after */
+  phase: HookPhase;
+  /** Hook handler */
+  handler: HookHandler<T>;
+  /** Priority (lower = earlier, default: 10) */
+  priority?: number;
+  /** Names of hooks that must execute before this one */
+  dependsOn?: string[];
+}
+/**
+ * Define a named hook with optional dependencies.
+ * Returns a registration object — call `register(hookSystem)` to activate.
+ *
+ * @example
+ * ```typescript
+ * const generateSlug = defineHook({
+ *   name: 'generateSlug',
+ *   resource: 'product', operation: 'create', phase: 'before',
+ *   handler: (ctx) => ({ ...ctx.data, slug: slugify(ctx.data.name) }),
+ * });
+ *
+ * const validateUniqueSlug = defineHook({
+ *   name: 'validateUniqueSlug',
+ *   resource: 'product', operation: 'create', phase: 'before',
+ *   dependsOn: ['generateSlug'],
+ *   handler: async (ctx) => { // check uniqueness },
+ * });
+ *
+ * // Register on a hook system
+ * generateSlug.register(hooks);
+ * validateUniqueSlug.register(hooks);
+ * ```
+ */
+declare function defineHook<T = AnyRecord>(options: DefineHookOptions<T>): DefineHookOptions<T> & {
+  register: (hooks: HookSystem) => () => void;
+};
+/**
+ * Create a before-create hook registration for a given hook system
+ */
+declare function beforeCreate<T = AnyRecord>(hooks: HookSystem, resource: string, handler: HookHandler<T>, priority?: number): () => void;
+/**
+ * Create an after-create hook registration for a given hook system
+ */
+declare function afterCreate<T = AnyRecord>(hooks: HookSystem, resource: string, handler: HookHandler<T>, priority?: number): () => void;
+/**
+ * Create a before-update hook registration for a given hook system
+ */
+declare function beforeUpdate<T = AnyRecord>(hooks: HookSystem, resource: string, handler: HookHandler<T>, priority?: number): () => void;
+/**
+ * Create an after-update hook registration for a given hook system
+ */
+declare function afterUpdate<T = AnyRecord>(hooks: HookSystem, resource: string, handler: HookHandler<T>, priority?: number): () => void;
+/**
+ * Create a before-delete hook registration for a given hook system
+ */
+declare function beforeDelete<T = AnyRecord>(hooks: HookSystem, resource: string, handler: HookHandler<T>, priority?: number): () => void;
+/**
+ * Create an after-delete hook registration for a given hook system
+ */
+declare function afterDelete<T = AnyRecord>(hooks: HookSystem, resource: string, handler: HookHandler<T>, priority?: number): () => void;
+//#endregion
+//#region src/pipeline/types.d.ts
+/**
+ * Pipeline context passed to guards, transforms, and interceptors.
+ * Extends IRequestContext with pipeline-specific metadata.
+ */
+interface PipelineContext extends IRequestContext {
+  /** Resource name being accessed */
+  resource: string;
+  /** CRUD operation being performed */
+  operation: 'list' | 'get' | 'create' | 'update' | 'delete' | string;
+}
+/**
+ * Which operations a pipeline step applies to.
+ * If omitted, applies to ALL operations.
+ */
+type OperationFilter = Array<'list' | 'get' | 'create' | 'update' | 'delete' | string>;
+/**
+ * Guard — boolean check that short-circuits on failure.
+ * Return true to proceed, throw to deny.
+ */
+interface Guard {
+  readonly _type: 'guard';
+  readonly name: string;
+  readonly operations?: OperationFilter;
+  handler(ctx: PipelineContext): boolean | Promise<boolean>;
+}
+/**
+ * Transform — modifies request data before the handler.
+ * Returns modified context (or mutates in place).
+ */
+interface Transform {
+  readonly _type: 'transform';
+  readonly name: string;
+  readonly operations?: OperationFilter;
+  handler(ctx: PipelineContext): PipelineContext | void | Promise<PipelineContext | void>;
+}
+/**
+ * Next function passed to interceptors — calls the handler (or next interceptor).
+ */
+type NextFunction = () => Promise<IControllerResponse<unknown>>;
+/**
+ * Intercept — wraps handler execution (before + after pattern).
+ */
+interface Interceptor {
+  readonly _type: 'interceptor';
+  readonly name: string;
+  readonly operations?: OperationFilter;
+  handler(ctx: PipelineContext, next: NextFunction): Promise<IControllerResponse<unknown>>;
+}
+type PipelineStep = Guard | Transform | Interceptor;
+/**
+ * Pipeline configuration — can be a flat array or per-operation map.
+ */
+type PipelineConfig = PipelineStep[] | {
+  list?: PipelineStep[];
+  get?: PipelineStep[];
+  create?: PipelineStep[];
+  update?: PipelineStep[];
+  delete?: PipelineStep[];
+  [operation: string]: PipelineStep[] | undefined;
+};
+//#endregion
+//#region src/types/repository.d.ts
+/**
+ * Repository Interface - Database-Agnostic CRUD Operations
+ *
+ * This is the standard interface that all repositories must implement.
+ * MongoKit Repository already implements this interface.
+ *
+ * @example
+ * ```typescript
+ * import type { CrudRepository } from '@classytic/arc';
+ *
+ * // Your repository automatically satisfies this interface
+ * const userRepo: CrudRepository<UserDocument> = new Repository(UserModel);
+ * ```
+ */
+/**
+ * Query options for read operations
+ */
+interface QueryOptions {
+  /** Transaction session — adapters handle the actual type (e.g., Mongoose ClientSession) */
+  session?: unknown;
+  /** Field selection - include or exclude fields */
+  select?: string | string[] | Record<string, 0 | 1>;
+  /** Relations to populate - string, array, or Mongoose populate options */
+  populate?: string | string[] | Record<string, unknown>;
+  /** Return plain JS objects instead of Mongoose documents */
+  lean?: boolean;
+  /** Allow additional adapter-specific options */
+  [key: string]: unknown;
+}
+/**
+ * Pagination parameters for list operations
+ */
+interface PaginationParams<TDoc = unknown> {
+  /** Filter criteria */
+  filters?: Partial<TDoc> & Record<string, unknown>;
+  /** Sort specification - string ("-createdAt") or object ({ createdAt: -1 }) */
+  sort?: string | Record<string, 1 | -1>;
+  /** Page number (1-indexed) */
+  page?: number;
+  /** Items per page */
+  limit?: number;
+  /** Allow additional options (select, populate, etc.) */
+  [key: string]: unknown;
+}
+/**
+ * Paginated result from list operations
+ */
+interface PaginatedResult<TDoc> {
+  /** Documents for current page */
+  docs: TDoc[];
+  /** Current page number */
+  page: number;
+  /** Items per page */
+  limit: number;
+  /** Total document count */
+  total: number;
+  /** Total page count */
+  pages: number;
+  /** Has next page */
+  hasNext: boolean;
+  /** Has previous page */
+  hasPrev: boolean;
+}
+/**
+ * Standard CRUD Repository Interface
+ *
+ * Defines the contract for data access operations.
+ * All database adapters (MongoKit, Prisma, etc.) implement this interface.
+ *
+ * @typeParam TDoc - The document/entity type
+ */
+interface CrudRepository<TDoc> {
+  /**
+   * Get paginated list of documents
+   */
+  getAll(params?: PaginationParams<TDoc>, options?: QueryOptions): Promise<PaginatedResult<TDoc>>;
+  /**
+   * Get single document by ID
+   */
+  getById(id: string, options?: QueryOptions): Promise<TDoc | null>;
+  /**
+   * Create new document
+   */
+  create(data: Partial<TDoc>, options?: {
+    session?: unknown;
+    [key: string]: unknown;
+  }): Promise<TDoc>;
+  /**
+   * Update document by ID
+   */
+  update(id: string, data: Partial<TDoc>, options?: QueryOptions): Promise<TDoc | null>;
+  /**
+   * Delete document by ID
+   */
+  delete(id: string, options?: {
+    session?: unknown;
+    [key: string]: unknown;
+  }): Promise<{
+    success: boolean;
+    message: string;
+  }>;
+  /** Allow custom methods (getBySlug, getTree, restore, etc.) */
+  [key: string]: unknown;
+}
+/**
+ * Extract document type from a repository
+ *
+ * @example
+ * ```typescript
+ * type UserDoc = InferDoc<typeof userRepository>;
+ * // UserDoc is now the document type of userRepository
+ * ```
+ */
+type InferDoc<R> = R extends CrudRepository<infer T> ? T : never;
+//#endregion
+//#region src/core/defineResource.d.ts
+/**
+ * Define a resource with database adapter
+ *
+ * This is the MAIN entry point for creating Arc resources.
+ * The adapter provides both repository and schema metadata.
+ */
+declare function defineResource<TDoc = AnyRecord>(config: ResourceConfig<TDoc>): ResourceDefinition<TDoc>;
+interface ResolvedResourceConfig<TDoc = AnyRecord> extends ResourceConfig<TDoc> {
+  _appliedPresets?: string[];
+  _controllerOptions?: {
+    slugField?: string;
+    parentField?: string;
+    [key: string]: unknown;
+  };
+  _pendingHooks?: Array<{
+    operation: "create" | "update" | "delete" | "read" | "list";
+    phase: "before" | "after";
+    handler: (ctx: AnyRecord) => unknown;
+    priority: number;
+  }>;
+}
+declare class ResourceDefinition<TDoc = AnyRecord> {
+  readonly name: string;
+  readonly displayName: string;
+  readonly tag: string;
+  readonly prefix: string;
+  readonly adapter?: DataAdapter<TDoc>;
+  readonly controller?: IController<TDoc>;
+  readonly schemaOptions: RouteSchemaOptions;
+  readonly customSchemas: CrudSchemas;
+  readonly permissions: ResourcePermissions;
+  readonly additionalRoutes: AdditionalRoute[];
+  readonly middlewares: MiddlewareConfig;
+  readonly disableDefaultRoutes: boolean;
+  readonly disabledRoutes: CrudRouteKey[];
+  readonly events: Record<string, EventDefinition>;
+  readonly rateLimit?: RateLimitConfig | false;
+  readonly updateMethod?: "PUT" | "PATCH" | "both";
+  readonly pipe?: PipelineConfig;
+  readonly fields?: FieldPermissionMap;
+  readonly cache?: ResourceCacheConfig;
+  readonly _appliedPresets: string[];
+  _pendingHooks: Array<{
+    operation: "create" | "update" | "delete" | "read" | "list";
+    phase: "before" | "after";
+    handler: (ctx: AnyRecord) => unknown;
+    priority: number;
+  }>;
+  _registryMeta?: RegisterOptions;
+  constructor(config: ResolvedResourceConfig<TDoc>);
+  /** Get repository from adapter (if available) */
+  get repository(): RepositoryLike | CrudRepository<TDoc> | undefined;
+  _validateControllerMethods(): void;
+  toPlugin(): FastifyPluginAsync;
+  /**
+   * Get event definitions for registry
+   */
+  getEvents(): Array<{
+    name: string;
+    module: string;
+    schema?: AnyRecord;
+    description?: string;
+  }>;
+  /**
+   * Get resource metadata
+   */
+  getMetadata(): ResourceMetadata;
+}
+//#endregion
+//#region src/registry/ResourceRegistry.d.ts
+interface RegisterOptions {
+  module?: string;
+  /** Pre-generated OpenAPI schemas */
+  openApiSchemas?: OpenApiSchemas;
+}
+declare class ResourceRegistry {
+  private _resources;
+  private _frozen;
+  constructor();
+  /**
+   * Register a resource
+   */
+  register(resource: ResourceDefinition<unknown>, options?: RegisterOptions): this;
+  /**
+   * Get resource by name
+   */
+  get(name: string): RegistryEntry | undefined;
+  /**
+   * Get all resources
+   */
+  getAll(): RegistryEntry[];
+  /**
+   * Get resources by module
+   */
+  getByModule(moduleName: string): RegistryEntry[];
+  /**
+   * Get resources by preset
+   */
+  getByPreset(presetName: string): RegistryEntry[];
+  /**
+   * Check if resource exists
+   */
+  has(name: string): boolean;
+  /**
+   * Get registry statistics
+   */
+  getStats(): RegistryStats;
+  /**
+   * Get full introspection data
+   */
+  getIntrospection(): IntrospectionData;
+  /**
+   * Freeze registry (prevent further registrations)
+   */
+  freeze(): void;
+  /**
+   * Check if frozen
+   */
+  isFrozen(): boolean;
+  /**
+   * Unfreeze registry (allow new registrations)
+   */
+  unfreeze(): void;
+  /**
+   * Reset registry — clear all resources and unfreeze
+   */
+  reset(): void;
+  /** @internal Alias for unfreeze() */
+  _unfreeze(): void;
+  /** @internal Alias for reset() */
+  _clear(): void;
+  /**
+   * Group by key
+   */
+  private _groupBy;
+}
+//#endregion
+//#region src/types/handlers.d.ts
+/**
+ * Minimal server accessor — exposes safe, read-only server decorators.
+ * Allows controller handlers to publish events, log, and audit
+ * without switching to `wrapHandler: false`.
+ */
+interface ServerAccessor {
+  /** Event bus — publish domain events from any handler */
+  events?: {
+    publish: <T>(type: string, payload: T, meta?: Partial<Record<string, unknown>>) => Promise<void>;
+  };
+  /** Audit logger — log custom audit entries */
+  audit?: {
+    create: (resource: string, documentId: string, data: Record<string, unknown>, context?: Record<string, unknown>) => Promise<void>;
+    update: (resource: string, documentId: string, before: Record<string, unknown>, after: Record<string, unknown>, context?: Record<string, unknown>) => Promise<void>;
+    delete: (resource: string, documentId: string, data: Record<string, unknown>, context?: Record<string, unknown>) => Promise<void>;
+    custom: (resource: string, documentId: string, action: string, data?: Record<string, unknown>, context?: Record<string, unknown>) => Promise<void>;
+  };
+  /** Logger — structured logging */
+  log?: {
+    info: (...args: unknown[]) => void;
+    warn: (...args: unknown[]) => void;
+    error: (...args: unknown[]) => void;
+    debug: (...args: unknown[]) => void;
+  };
+  /** QueryCache — stale-while-revalidate data cache */
+  queryCache?: {
+    get: <T>(key: string) => Promise<{
+      data: T;
+      status: 'fresh' | 'stale' | 'miss';
+    }>;
+    set: <T>(key: string, data: T, config: {
+      staleTime?: number;
+      gcTime?: number;
+      tags?: string[];
+    }) => Promise<void>;
+    getResourceVersion: (resource: string) => Promise<number>;
+    bumpResourceVersion: (resource: string) => Promise<void>;
+  };
+}
+/**
+ * Request context passed to controller handlers
+ */
+interface IRequestContext {
+  /** Route parameters (e.g., { id: '123' }) */
+  params: Record<string, string>;
+  /** Query string parameters */
+  query: Record<string, unknown>;
+  /** Request body */
+  body: unknown;
+  /** Authenticated user or null */
+  user: UserBase | null;
+  /** Request headers */
+  headers: Record<string, string | undefined>;
+  /** Organization ID (for multi-tenant apps) */
+  organizationId?: string;
+  /** Team ID (for team-scoped resources) */
+  teamId?: string;
+  /**
+   * Organization/auth context from middleware.
+   * Contains orgRoles, orgScope, organizationId, and any custom fields
+   * set by the auth adapter or org-scope plugin.
+   *
+   * @example
+   * ```typescript
+   * async create(req: IRequestContext) {
+   *   const roles = req.context?.orgRoles ?? [];
+   *   if (roles.includes('manager')) { ... }
+   * }
+   * ```
+   */
+  context?: RequestContext;
+  /** Internal metadata (includes context + Arc internals like _policyFilters, log) */
+  metadata?: Record<string, unknown>;
+  /**
+   * Fastify server accessor — publish events, log, and audit
+   * from any handler without switching to `wrapHandler: false`.
+   *
+   * @example
+   * ```typescript
+   * async reschedule(req: IRequestContext) {
+   *   const result = await repo.reschedule(req.params.id, req.body);
+   *   await req.server?.events?.publish('interview.rescheduled', { data: result });
+   *   return { success: true, data: result };
+   * }
+   * ```
+   */
+  server?: ServerAccessor;
+}
+/**
+ * Standard response from controller handlers
+ */
+interface IControllerResponse<T = unknown> {
+  /** Operation success status */
+  success: boolean;
+  /** Response data */
+  data?: T;
+  /** Error message (when success is false) */
+  error?: string;
+  /** HTTP status code (default: 200 for success, 400 for error) */
+  status?: number;
+  /** Additional metadata */
+  meta?: Record<string, unknown>;
+  /** Error details (for debugging) */
+  details?: Record<string, unknown>;
+  /** Custom response headers (e.g., X-Total-Count, Link, ETag) */
+  headers?: Record<string, string>;
+}
+/**
+ * Controller handler - Arc's standard pattern
+ *
+ * Receives a request context object, returns IControllerResponse.
+ * Use with `wrapHandler: true` in additionalRoutes.
+ *
+ * @example
+ * ```typescript
+ * const createProduct: ControllerHandler<Product> = async (req) => {
+ *   const product = await productRepo.create(req.body);
+ *   return { success: true, data: product, status: 201 };
+ * };
+ *
+ * additionalRoutes: [{
+ *   method: 'POST',
+ *   path: '/products',
+ *   handler: createProduct,
+ *   permissions: requireAuth(),
+ *   wrapHandler: true,  // Arc wraps this into Fastify handler
+ * }]
+ * ```
+ */
+type ControllerHandler<T = unknown> = (req: IRequestContext) => Promise<IControllerResponse<T>>;
+/**
+ * Fastify native handler
+ *
+ * Standard Fastify request/reply pattern.
+ * Use with `wrapHandler: false` in additionalRoutes.
+ *
+ * @example
+ * ```typescript
+ * const downloadFile: FastifyHandler = async (request, reply) => {
+ *   const file = await getFile(request.params.id);
+ *   reply.header('Content-Type', file.mimeType);
+ *   return reply.send(file.buffer);
+ * };
+ *
+ * additionalRoutes: [{
+ *   method: 'GET',
+ *   path: '/files/:id/download',
+ *   handler: downloadFile,
+ *   permissions: requireAuth(),
+ *   wrapHandler: false,  // Use as-is, no wrapping
+ * }]
+ * ```
+ */
+type FastifyHandler = (request: FastifyRequest, reply: FastifyReply) => Promise<void> | void;
+/**
+ * Union type for route handlers
+ */
+type RouteHandler = ControllerHandler | FastifyHandler;
+/**
+ * Controller interface for CRUD operations (strict)
+ */
+interface IController<TDoc = unknown> {
+  list(req: IRequestContext): Promise<IControllerResponse<{
+    docs: TDoc[];
+    total: number;
+  }>>;
+  get(req: IRequestContext): Promise<IControllerResponse<TDoc>>;
+  create(req: IRequestContext): Promise<IControllerResponse<TDoc>>;
+  update(req: IRequestContext): Promise<IControllerResponse<TDoc>>;
+  delete(req: IRequestContext): Promise<IControllerResponse<{
+    message: string;
+  }>>;
+}
+/**
+ * Flexible controller interface - accepts controllers with any handler style
+ * Use this when your controller uses Fastify native handlers
+ */
+interface ControllerLike {
+  list?: unknown;
+  get?: unknown;
+  create?: unknown;
+  update?: unknown;
+  delete?: unknown;
+  [key: string]: unknown;
+}
+//#endregion
+//#region src/core/AccessControl.d.ts
+interface AccessControlConfig {
+  /** Field name used for multi-tenant scoping (default: 'organizationId') */
+  tenantField: string;
+  /** Primary key field name (default: '_id') */
+  idField: string;
+  /**
+   * Custom filter matching for policy enforcement.
+   * Provided by the DataAdapter for non-MongoDB databases (SQL, etc.).
+   * Falls back to built-in MongoDB-style matching if not provided.
+   */
+  matchesFilter?: (item: unknown, filters: Record<string, unknown>) => boolean;
+}
+/** Minimal repository interface for access-controlled fetch operations */
+interface AccessControlRepository {
+  getById(id: string, options?: unknown): Promise<unknown>;
+  getOne?: (filter: AnyRecord, options?: unknown) => Promise<unknown>;
+}
+declare class AccessControl {
+  private readonly tenantField;
+  private readonly idField;
+  private readonly _adapterMatchesFilter?;
+  /** Patterns that indicate dangerous regex (nested quantifiers, excessive backtracking).
+   *  Uses [^...] character classes instead of .+ to avoid backtracking in the detector itself. */
+  private static readonly DANGEROUS_REGEX;
+  /** Forbidden paths that could lead to prototype pollution */
+  private static readonly FORBIDDEN_PATHS;
+  constructor(config: AccessControlConfig);
+  /**
+   * Build filter for single-item operations (get/update/delete)
+   * Combines ID filter with policy/org filters for proper security enforcement
+   */
+  buildIdFilter(id: string, req: IRequestContext): AnyRecord;
+  /**
+   * Check if item matches policy filters (for get/update/delete operations)
+   * Validates that fetched item satisfies all policy constraints
+   *
+   * Delegates to adapter-provided matchesFilter if available (for SQL, etc.),
+   * otherwise falls back to built-in MongoDB-style matching.
+   */
+  checkPolicyFilters(item: AnyRecord, req: IRequestContext): boolean;
+  /**
+   * Check org/tenant scope for a document — uses configurable tenantField.
+   *
+   * SECURITY: When org scope is active (orgId present), documents that are
+   * missing the tenant field are DENIED by default. This prevents legacy or
+   * unscoped records from leaking across tenants.
+   */
+  checkOrgScope(item: AnyRecord | null, arcContext: ArcInternalMetadata | RequestContext | undefined): boolean;
+  /** Check ownership for update/delete (ownedByUser preset) */
+  checkOwnership(item: AnyRecord | null, req: IRequestContext): boolean;
+  /**
+   * Fetch a single document with full access control enforcement.
+   * Combines compound DB filter (ID + org + policy) with post-hoc fallback.
+   *
+   * Takes repository as a parameter to avoid coupling.
+   *
+   * Replaces the duplicated pattern in get/update/delete:
+   *   buildIdFilter -> getOne (or getById + checkOrgScope + checkPolicyFilters)
+   */
+  fetchWithAccessControl<TDoc>(id: string, req: IRequestContext, repository: AccessControlRepository, queryOptions?: unknown): Promise<TDoc | null>;
+  /** Extract typed Arc internal metadata from request */
+  private _meta;
+  /**
+   * Check if a value matches a MongoDB query operator
+   */
+  private matchesOperator;
+  /**
+   * Check if item matches a single filter condition
+   * Supports nested paths (e.g., "owner.id", "metadata.status")
+   */
+  private matchesFilter;
+  /**
+   * Built-in MongoDB-style policy filter matching.
+   * Supports: $eq, $ne, $gt, $gte, $lt, $lte, $in, $nin, $exists, $regex, $and, $or
+   */
+  private defaultMatchesPolicyFilters;
+  /**
+   * Get nested value from object using dot notation (e.g., "owner.id")
+   * Security: Validates path against forbidden patterns to prevent prototype pollution
+   */
+  private getNestedValue;
+  /**
+   * Create a safe RegExp from a string, guarding against ReDoS.
+   * Returns null if the pattern is invalid or dangerous.
+   */
+  private static safeRegex;
+}
+//#endregion
+//#region src/core/BodySanitizer.d.ts
+interface BodySanitizerConfig {
+  /** Schema options for field sanitization */
+  schemaOptions: RouteSchemaOptions;
+}
+declare class BodySanitizer {
+  private schemaOptions;
+  constructor(config: BodySanitizerConfig);
+  /**
+   * Strip readonly and system-managed fields from request body.
+   * Prevents clients from overwriting _id, timestamps, __v, etc.
+   *
+   * Also applies field-level write permissions when the request has
+   * field permission metadata.
+   */
+  sanitize(body: AnyRecord, _operation: 'create' | 'update', req?: IRequestContext, meta?: ArcInternalMetadata): AnyRecord;
+}
+//#endregion
+//#region src/core/QueryResolver.d.ts
+interface QueryResolverConfig {
+  /** Query parser instance (default: Arc built-in parser) */
+  queryParser?: QueryParserInterface;
+  /** Maximum limit for pagination (default: 100) */
+  maxLimit?: number;
+  /** Default limit for pagination (default: 20) */
+  defaultLimit?: number;
+  /** Default sort field (default: '-createdAt') */
+  defaultSort?: string;
+  /** Schema options for field sanitization */
+  schemaOptions?: RouteSchemaOptions;
+  /** Field name used for multi-tenant scoping (default: 'organizationId') */
+  tenantField?: string;
+}
+declare class QueryResolver {
+  private queryParser;
+  private maxLimit;
+  private defaultLimit;
+  private defaultSort;
+  private schemaOptions;
+  private tenantField;
+  constructor(config?: QueryResolverConfig);
+  /**
+   * Resolve a request into parsed query options -- ONE parse per request.
+   * Combines what was previously _buildContext + _parseQueryOptions + _applyFilters.
+   */
+  resolve(req: IRequestContext, meta?: ArcInternalMetadata): ControllerQueryOptions;
+  /**
+   * Convert parsed select object to string format
+   * Converts { name: 1, email: 1, password: 0 } -> 'name email -password'
+   */
+  private selectToString;
+  /** Sanitize select fields */
+  private sanitizeSelect;
+  /** Sanitize populate fields */
+  private sanitizePopulate;
+  /** Get blocked fields from schema options */
+  private getBlockedFields;
+}
+//#endregion
+//#region src/core/BaseController.d.ts
+interface BaseControllerOptions {
+  /** Schema options for field sanitization */
+  schemaOptions?: RouteSchemaOptions;
+  /**
+   * Query parser instance.
+   * Default: Arc built-in query parser (adapter-agnostic).
+   * Swap in MongoKit QueryParser, pgkit parser, etc.
+   */
+  queryParser?: QueryParserInterface;
+  /** Maximum limit for pagination (default: 100) */
+  maxLimit?: number;
+  /** Default limit for pagination (default: 20) */
+  defaultLimit?: number;
+  /** Default sort field (default: '-createdAt') */
+  defaultSort?: string;
+  /** Resource name for hook execution (e.g., 'product' -> 'product.created') */
+  resourceName?: string;
+  /**
+   * Field name used for multi-tenant scoping (default: 'organizationId').
+   * Override to match your schema: 'workspaceId', 'tenantId', 'teamId', etc.
+   */
+  tenantField?: string;
+  /**
+   * Primary key field name (default: '_id').
+   * Override for non-MongoDB adapters (e.g., 'id' for SQL databases).
+   */
+  idField?: string;
+  /**
+   * Custom filter matching for policy enforcement.
+   * Provided by the DataAdapter for non-MongoDB databases (SQL, etc.).
+   * Falls back to built-in MongoDB-style matching if not provided.
+   */
+  matchesFilter?: (item: unknown, filters: Record<string, unknown>) => boolean;
+  /** Cache configuration for the resource */
+  cache?: ResourceCacheConfig;
+  /** Internal preset fields map (slug, tree, etc.) */
+  presetFields?: {
+    slugField?: string;
+    parentField?: string;
+  };
+}
+/**
+ * Framework-agnostic base controller implementing IController.
+ *
+ * Composes AccessControl, BodySanitizer, and QueryResolver for clean
+ * separation of concerns. CRUD methods delegate directly to these
+ * composed classes — no intermediate wrapper methods.
+ *
+ * @template TDoc - The document type
+ * @template TRepository - The repository type (defaults to RepositoryLike)
+ */
+declare class BaseController<TDoc = AnyRecord, TRepository extends RepositoryLike = RepositoryLike> implements IController<TDoc> {
+  protected repository: TRepository;
+  protected schemaOptions: RouteSchemaOptions;
+  protected queryParser: QueryParserInterface;
+  protected maxLimit: number;
+  protected defaultLimit: number;
+  protected defaultSort: string;
+  protected resourceName?: string;
+  protected tenantField: string;
+  protected idField: string;
+  /** Composable access control (ID filtering, policy checks, org scope, ownership) */
+  readonly accessControl: AccessControl;
+  /** Composable body sanitization (field permissions, system fields) */
+  readonly bodySanitizer: BodySanitizer;
+  /** Composable query resolution (parsing, pagination, sort, select/populate) */
+  readonly queryResolver: QueryResolver;
+  private _matchesFilter?;
+  private _presetFields;
+  private _cacheConfig?;
+  constructor(repository: TRepository, options?: BaseControllerOptions);
+  /** Extract typed Arc internal metadata from request */
+  private meta;
+  /** Get hook system from request context (instance-scoped) */
+  private getHooks;
+  /** Resolve cache config for a specific operation, merging per-op overrides */
+  private resolveCacheConfig;
+  /** Extract user/org IDs from request for cache key scoping */
+  private cacheScope;
+  list(req: IRequestContext): Promise<IControllerResponse<PaginatedResult<TDoc>>>;
+  /** Execute list query through hooks (extracted for cache revalidation) */
+  private executeListQuery;
+  get(req: IRequestContext): Promise<IControllerResponse<TDoc>>;
+  /** Execute get query through hooks (extracted for cache revalidation) */
+  private executeGetQuery;
+  create(req: IRequestContext): Promise<IControllerResponse<TDoc>>;
+  update(req: IRequestContext): Promise<IControllerResponse<TDoc>>;
+  delete(req: IRequestContext): Promise<IControllerResponse<{
+    message: string;
+  }>>;
+  getBySlug(req: IRequestContext): Promise<IControllerResponse<TDoc>>;
+  getDeleted(req: IRequestContext): Promise<IControllerResponse<PaginatedResult<TDoc>>>;
+  restore(req: IRequestContext): Promise<IControllerResponse<TDoc>>;
+  getTree(req: IRequestContext): Promise<IControllerResponse<TDoc[]>>;
+  getChildren(req: IRequestContext): Promise<IControllerResponse<TDoc[]>>;
+}
+//#endregion
+//#region src/adapters/interface.d.ts
+/**
+ * Minimal repository interface for flexible adapter compatibility.
+ * Any repository with these method signatures is accepted — no `as any` needed.
+ *
+ * CrudRepository<TDoc> and MongoKit Repository both satisfy this interface.
+ */
+interface RepositoryLike {
+  getAll(params?: unknown): Promise<unknown>;
+  getById(id: string, options?: unknown): Promise<unknown>;
+  create(data: unknown, options?: unknown): Promise<unknown>;
+  update(id: string, data: unknown, options?: unknown): Promise<unknown>;
+  delete(id: string, options?: unknown): Promise<unknown>;
+  [key: string]: unknown;
+}
+interface DataAdapter<TDoc = unknown> {
+  /**
+   * Repository implementing CRUD operations
+   * Accepts CrudRepository, MongoKit Repository, or any compatible object
+   */
+  repository: CrudRepository<TDoc> | RepositoryLike;
+  /** Adapter identifier for introspection */
+  readonly type: 'mongoose' | 'prisma' | 'drizzle' | 'typeorm' | 'custom';
+  /** Human-readable name */
+  readonly name: string;
+  /**
+   * Generate OpenAPI schemas for CRUD operations
+   *
+   * This method allows each adapter to generate schemas specific to its ORM/database.
+   * For example, Mongoose adapter can use mongokit to generate schemas from Mongoose models.
+   *
+   * @param options - Schema generation options (field rules, populate settings, etc.)
+   * @returns OpenAPI schemas for CRUD operations or null if not supported
+   */
+  generateSchemas?(options?: RouteSchemaOptions): OpenApiSchemas | null;
+  /** Extract schema metadata for OpenAPI/introspection */
+  getSchemaMetadata?(): SchemaMetadata | null;
+  /** Validate data against schema before persistence */
+  validate?(data: unknown): Promise<ValidationResult> | ValidationResult;
+  /** Health check for database connection */
+  healthCheck?(): Promise<boolean>;
+  /**
+   * Custom filter matching for policy enforcement.
+   * Falls back to built-in MongoDB-style matching if not provided.
+   * Override this for SQL adapters or non-MongoDB query operators.
+   */
+  matchesFilter?: (item: unknown, filters: Record<string, unknown>) => boolean;
+  /** Close/cleanup resources */
+  close?(): Promise<void>;
+}
+interface SchemaMetadata {
+  name: string;
+  fields: Record<string, FieldMetadata>;
+  indexes?: Array<{
+    fields: string[];
+    unique?: boolean;
+    sparse?: boolean;
+  }>;
+  relations?: Record<string, RelationMetadata>;
+}
+interface FieldMetadata {
+  type: 'string' | 'number' | 'boolean' | 'date' | 'object' | 'array' | 'objectId' | 'enum';
+  required?: boolean;
+  unique?: boolean;
+  default?: unknown;
+  enum?: Array<string | number>;
+  min?: number;
+  max?: number;
+  minLength?: number;
+  maxLength?: number;
+  pattern?: string;
+  description?: string;
+  ref?: string;
+  array?: boolean;
+}
+interface RelationMetadata {
+  type: 'one-to-one' | 'one-to-many' | 'many-to-many';
+  target: string;
+  foreignKey?: string;
+  through?: string;
+}
+interface ValidationResult {
+  valid: boolean;
+  errors?: Array<{
+    field: string;
+    message: string;
+    code?: string;
+  }>;
+}
+type AdapterFactory<TDoc> = (config: unknown) => DataAdapter<TDoc>;
+//#endregion
+export { beforeUpdate as $, PaginationParams as A, DefineHookOptions as B, RegisterOptions as C, CrudRepository as D, defineResource as E, OperationFilter as F, HookRegistration as G, HookHandler as H, PipelineConfig as I, afterCreate as J, HookSystem as K, PipelineContext as L, Guard as M, Interceptor as N, InferDoc as O, NextFunction as P, beforeDelete as Q, PipelineStep as R, RouteHandler as S, ResourceDefinition as T, HookOperation as U, HookContext as V, HookPhase as W, afterUpdate as X, afterDelete as Y, beforeCreate as Z, ControllerLike as _, RepositoryLike as a, IControllerResponse as b, BaseController as c, QueryResolverConfig as d, createHookSystem as et, BodySanitizer as f, ControllerHandler as g, AccessControlConfig as h, RelationMetadata as i, QueryOptions as j, PaginatedResult as k, BaseControllerOptions as l, AccessControl as m, DataAdapter as n, SchemaMetadata as o, BodySanitizerConfig as p, HookSystemOptions as q, FieldMetadata as r, ValidationResult as s, AdapterFactory as t, defineHook as tt, QueryResolver as u, FastifyHandler as v, ResourceRegistry as w, IRequestContext as x, IController as y, Transform as z };
+//# sourceMappingURL=interface-Ch8HU9uM.d.mts.map