@classytic/arc 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,331 @@
+import { d as AnyRecord, e as IController, f as CrudRepository, Q as QueryOptions, g as RouteSchemaOptions, h as QueryParserInterface, i as RepositoryLike, j as IRequestContext, S as ServiceContext, k as ControllerQueryOptions, l as RequestContext, H as HookSystem, m as IControllerResponse, n as PaginatedResult, o as ResourceConfig } from './index-DkAW8BXh.js';
+export { V as AdapterValidationResult, K as AdditionalRoute, u as ApiResponse, a as AuthPluginOptions, a4 as ConfigError, v as ControllerLike, B as CrudController, C as CrudRouteKey, _ as CrudRouterOptions, G as CrudSchemas, D as DataAdapter, N as EventDefinition, w as FastifyRequestExtras, x as FastifyWithAuth, y as FastifyWithDecorators, F as FieldMetadata, E as FieldRule, a9 as GracefulShutdownOptions, a7 as HealthCheck, a8 as HealthOptions, ac as HookContext, ad as HookHandler, $ as InferDocType, a0 as InferResourceDoc, Y as IntrospectionData, I as IntrospectionPluginOptions, J as JWTPayload, M as MiddlewareConfig, Z as OrgScopeOptions, O as OwnershipCheck, L as PresetFunction, P as PresetResult, W as RegistryEntry, X as RegistryStats, q as RelationMetadata, aa as RequestIdOptions, R as RequestWithExtras, t as ResourceDefinition, T as ResourceMetadata, z as RouteHandler, p as SchemaMetadata, a2 as TypedController, a3 as TypedRepository, a1 as TypedResourceConfig, U as UserOrganization, a6 as ValidateOptions, a5 as ValidationResult, s as defineResource, ab as hookSystem, r as resourceRegistry } from './index-DkAW8BXh.js';
+export { MongooseAdapter, MongooseAdapterOptions, PrismaAdapter, PrismaAdapterOptions, createMongooseAdapter, createPrismaAdapter } from './adapters/index.js';
+export { RouteHandlerMethod } from 'fastify';
+export { P as PermissionCheck, a as PermissionContext, b as PermissionResult, U as UserBase } from './types-B99TBmFV.js';
+export { A as ArcError, F as ForbiddenError, N as NotFoundError, U as UnauthorizedError, V as ValidationError } from './errors-8WIxGS_6.js';
+export { e as gracefulShutdownPlugin, a as healthPlugin, _ as requestIdPlugin } from './arcCorePlugin-DTPWXcZN.js';
+export { DomainEvent, EventHandler, eventPlugin } from './events/index.js';
+export { allOf, allowPublic, anyOf, denyAll, requireAuth, requireOwnership, requireRoles, when } from './permissions/index.js';
+export { A as ArcFactory, c as createApp } from './createApp-pzUAkzbz.js';
+export { C as CreateAppOptions } from './types-0IPhH_NR.js';
+import 'mongoose';
+import '@fastify/cors';
+import '@fastify/helmet';
+import '@fastify/rate-limit';
+
+/**
+ * Base Controller - Framework-Agnostic CRUD Operations
+ *
+ * Implements IController interface for framework portability.
+ * Works with Fastify, Express, Next.js, or any framework via adapter pattern.
+ *
+ * @example
+ * import { BaseController } from '@classytic/arc';
+ *
+ * // Use Arc's default query parser (works out of the box)
+ * class ProductController extends BaseController {
+ *   constructor(repository: CrudRepository) {
+ *     super(repository);
+ *   }
+ * }
+ *
+ * // Or use MongoKit's parser for advanced MongoDB features ($lookup, aggregations)
+ * import { QueryParser } from '@classytic/mongokit';
+ * defineResource({
+ *   name: 'product',
+ *   queryParser: new QueryParser(),
+ *   // ...
+ * });
+ *
+ * // Or use a custom parser for SQL databases
+ * defineResource({
+ *   name: 'user',
+ *   queryParser: new PgQueryParser(),
+ *   // ...
+ * });
+ */
+
+/**
+ * Extended repository type that includes optional preset methods
+ * Used internally for type-safe access to preset-added methods
+ */
+interface ExtendedRepository<TDoc> extends CrudRepository<TDoc> {
+    getBySlug?(slug: string, options?: QueryOptions): Promise<TDoc | null>;
+    getDeleted?(options?: QueryOptions): Promise<TDoc[]>;
+    restore?(id: string, options?: QueryOptions): Promise<TDoc | null>;
+    getTree?(options?: QueryOptions): Promise<TDoc[]>;
+    getChildren?(parentId: string, options?: QueryOptions): Promise<TDoc[]>;
+}
+interface BaseControllerOptions {
+    /** Schema options for field sanitization */
+    schemaOptions?: RouteSchemaOptions;
+    /**
+     * Query parser instance
+     * Default: Arc built-in query parser (adapter-agnostic).
+     * You can 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;
+    /** Disable automatic event emission (default: false) */
+    disableEvents?: boolean;
+}
+/**
+ * Framework-agnostic base controller implementing MongoKit's IController
+ *
+ * Use with Fastify adapter for Fastify integration (see createFastifyAdapter in createCrudRouter)
+ */
+declare class BaseController<TDoc = AnyRecord> implements IController<TDoc> {
+    protected repository: ExtendedRepository<TDoc>;
+    protected schemaOptions: RouteSchemaOptions;
+    protected queryParser: QueryParserInterface;
+    protected maxLimit: number;
+    protected defaultLimit: number;
+    protected defaultSort: string;
+    protected resourceName?: string;
+    protected disableEvents: boolean;
+    /** Preset field names for dynamic param reading */
+    protected _presetFields: {
+        slugField?: string;
+        parentField?: string;
+    };
+    constructor(repository: CrudRepository<TDoc> | RepositoryLike, options?: BaseControllerOptions);
+    /**
+     * Inject resource options from defineResource
+     */
+    _setResourceOptions(options: {
+        schemaOptions?: RouteSchemaOptions;
+        presetFields?: {
+            slugField?: string;
+            parentField?: string;
+        };
+        resourceName?: string;
+        queryParser?: QueryParserInterface;
+    }): void;
+    /**
+     * Build service context from IRequestContext
+     */
+    protected _buildContext(context: IRequestContext): ServiceContext;
+    /**
+     * Parse query into QueryOptions using queryParser
+     */
+    protected _parseQueryOptions(context: IRequestContext): ControllerQueryOptions;
+    /**
+     * Apply org and policy filters
+     */
+    protected _applyFilters(options: ControllerQueryOptions, context: IRequestContext): ControllerQueryOptions;
+    /**
+     * Build filter for single-item operations (get/update/delete)
+     * Combines ID filter with policy/org filters for proper security enforcement
+     */
+    protected _buildIdFilter(id: string, context: IRequestContext): AnyRecord;
+    /**
+     * Check if a value matches a MongoDB query operator
+     */
+    protected _matchesOperator(itemValue: unknown, operator: string, filterValue: unknown): boolean;
+    /**
+     * Forbidden paths that could lead to prototype pollution
+     */
+    private static readonly FORBIDDEN_PATHS;
+    /**
+     * Get nested value from object using dot notation (e.g., "owner.id")
+     * Security: Validates path against forbidden patterns to prevent prototype pollution
+     */
+    protected _getNestedValue(obj: AnyRecord, path: string): unknown;
+    /**
+     * Check if item matches a single filter condition
+     * Supports nested paths (e.g., "owner.id", "metadata.status")
+     */
+    protected _matchesFilter(item: AnyRecord, key: string, filterValue: unknown): boolean;
+    /**
+     * Check if item matches policy filters (for get/update/delete operations)
+     * Validates that fetched item satisfies all policy constraints
+     * Supports MongoDB query operators: $eq, $ne, $gt, $gte, $lt, $lte, $in, $nin, $exists, $regex, $and, $or
+     */
+    protected _checkPolicyFilters(item: AnyRecord, context: IRequestContext): boolean;
+    /** Parse lean option (default: true for performance) */
+    protected _parseLean(leanValue: unknown): boolean;
+    /** Get blocked fields from schema options */
+    protected _getBlockedFields(schemaOptions: RouteSchemaOptions): string[];
+    /**
+     * Convert parsed select object to string format
+     * Converts { name: 1, email: 1, password: 0 } → 'name email -password'
+     */
+    protected _selectToString(select: string | string[] | Record<string, 0 | 1> | undefined): string | undefined;
+    /** Sanitize select fields */
+    protected _sanitizeSelect(select: string | undefined, schemaOptions: RouteSchemaOptions): string | undefined;
+    /** Sanitize populate fields */
+    protected _sanitizePopulate(populate: unknown, schemaOptions: RouteSchemaOptions): string[] | undefined;
+    /** Check org scope for a document */
+    protected _checkOrgScope(item: AnyRecord | null, arcContext: RequestContext | undefined): boolean;
+    /** Check ownership for update/delete (ownedByUser preset) */
+    protected _checkOwnership(item: AnyRecord | null, context: IRequestContext): boolean;
+    /**
+     * Get hook system from context (instance-scoped) or fall back to global singleton
+     * This allows proper isolation when running multiple app instances (e.g., in tests)
+     */
+    protected _getHooks(context: IRequestContext): HookSystem;
+    /**
+     * List resources with filtering, pagination, sorting
+     * Implements IController.list()
+     */
+    list(context: IRequestContext): Promise<IControllerResponse<PaginatedResult<TDoc>>>;
+    /**
+     * Get single resource by ID
+     * Implements IController.get()
+     */
+    get(context: IRequestContext): Promise<IControllerResponse<TDoc>>;
+    /**
+     * Create new resource
+     * Implements IController.create()
+     */
+    create(context: IRequestContext): Promise<IControllerResponse<TDoc>>;
+    /**
+     * Update existing resource
+     * Implements IController.update()
+     */
+    update(context: IRequestContext): Promise<IControllerResponse<TDoc>>;
+    /**
+     * Delete resource
+     * Implements IController.delete()
+     */
+    delete(context: IRequestContext): Promise<IControllerResponse<{
+        message: string;
+    }>>;
+    /** Get resource by slug (slugLookup preset) */
+    getBySlug(context: IRequestContext): Promise<IControllerResponse<TDoc>>;
+    /** Get soft-deleted resources (softDelete preset) */
+    getDeleted(context: IRequestContext): Promise<IControllerResponse<PaginatedResult<TDoc>>>;
+    /** Restore soft-deleted resource (softDelete preset) */
+    restore(context: IRequestContext): Promise<IControllerResponse<TDoc>>;
+    /** Get hierarchical tree (tree preset) */
+    getTree(context: IRequestContext): Promise<IControllerResponse<TDoc[]>>;
+    /** Get children of parent (tree preset) */
+    getChildren(context: IRequestContext): Promise<IControllerResponse<TDoc[]>>;
+}
+
+/**
+ * Resource Configuration Validator
+ *
+ * Fail-fast validation at definition time.
+ * Invalid configs throw immediately with clear, actionable errors.
+ *
+ * @example
+ * const result = validateResourceConfig(config);
+ * if (!result.valid) {
+ *   console.error(formatValidationErrors(result.errors));
+ * }
+ */
+
+interface ConfigError {
+    field: string;
+    message: string;
+    suggestion?: string;
+}
+interface ValidationResult {
+    valid: boolean;
+    errors: ConfigError[];
+    warnings: ConfigError[];
+}
+interface ValidateOptions {
+    /** Skip controller method validation (for testing) */
+    skipControllerCheck?: boolean;
+    /** Allow unknown preset names */
+    allowUnknownPresets?: boolean;
+    /** Custom valid permission keys beyond CRUD */
+    additionalPermissionKeys?: string[];
+}
+/**
+ * Validate a resource configuration
+ */
+declare function validateResourceConfig(config: ResourceConfig, options?: ValidateOptions): ValidationResult;
+/**
+ * Format validation errors for display
+ */
+declare function formatValidationErrors(resourceName: string, result: ValidationResult): string;
+/**
+ * Validate and throw if invalid
+ */
+declare function assertValidConfig(config: ResourceConfig, options?: ValidateOptions): void;
+
+/**
+ * @classytic/arc
+ *
+ * Resource-oriented backend framework for Fastify.
+ * Supports MongoDB (Mongoose) and PostgreSQL/MySQL/SQLite (Prisma).
+ *
+ * ## Import Strategy (Tree-Shaking)
+ *
+ * This main entry exports commonly-used items. For better tree-shaking,
+ * import from specific subpaths when needed:
+ *
+ * ```typescript
+ * // Main entry - common items
+ * import { defineResource, createMongooseAdapter, allowPublic } from '@classytic/arc';
+ *
+ * // Subpath imports - specialized modules
+ * import { createTestApp } from '@classytic/arc/testing';
+ * import { createApp } from '@classytic/arc/factory';
+ * import { PrismaQueryParser } from '@classytic/arc/adapters';
+ * import { beforeCreate, afterUpdate } from '@classytic/arc/hooks';
+ * import { MemoryEventTransport } from '@classytic/arc/events';
+ * import { createStateMachine } from '@classytic/arc/utils';
+ * ```
+ *
+ * ## Subpath Exports
+ *
+ * | Subpath | Purpose |
+ * |---------|---------|
+ * | `@classytic/arc/testing` | Test utilities, mocks, TestHarness |
+ * | `@classytic/arc/factory` | App creation (createApp, ArcFactory) |
+ * | `@classytic/arc/adapters` | Database adapters + PrismaQueryParser |
+ * | `@classytic/arc/permissions` | Permission functions |
+ * | `@classytic/arc/presets` | Preset functions |
+ * | `@classytic/arc/hooks` | Hook helpers (beforeCreate, etc.) |
+ * | `@classytic/arc/events` | Event transports |
+ * | `@classytic/arc/plugins` | Fastify plugins |
+ * | `@classytic/arc/utils` | Utilities (state machine, etc.) |
+ * | `@classytic/arc/org` | Organization utilities |
+ * | `@classytic/arc/audit` | Audit trail |
+ * | `@classytic/arc/idempotency` | Idempotency stores |
+ * | `@classytic/arc/types` | TypeScript types |
+ *
+ * @example Basic Resource
+ * ```typescript
+ * import { defineResource, createMongooseAdapter, allowPublic, requireRoles } from '@classytic/arc';
+ *
+ * const productResource = defineResource({
+ *   name: 'product',
+ *   adapter: createMongooseAdapter({ model: ProductModel, repository: productRepo }),
+ *   permissions: {
+ *     list: allowPublic(),
+ *     create: requireRoles(['admin']),
+ *   },
+ * });
+ * ```
+ *
+ * @example Full Application
+ * ```typescript
+ * import { createApp } from '@classytic/arc/factory';
+ * import { productResource } from './modules/product.resource.js';
+ *
+ * const app = await createApp({
+ *   preset: 'production',
+ *   auth: { jwt: { secret: process.env.JWT_SECRET } },
+ *   plugins: async (fastify) => {
+ *     await fastify.register(productResource.toPlugin());
+ *   },
+ * });
+ * ```
+ */
+
+declare const version = "1.0.0";
+
+export { AnyRecord, BaseController, type BaseControllerOptions, CrudRepository, HookSystem, IController, IControllerResponse, IRequestContext, PaginatedResult, QueryOptions, RepositoryLike, RequestContext, ResourceConfig, RouteSchemaOptions, ServiceContext, assertValidConfig, formatValidationErrors, validateResourceConfig, version };