@classytic/arc 1.0.0 → 1.0.8

package/dist/BaseController-nNRS3vpA.d.ts

@@ -0,0 +1,233 @@
+import { A as AnyRecord, I as IController, R as RouteSchemaOptions, Q as QueryParserInterface, a as IRequestContext, S as ServiceContext, C as ControllerQueryOptions, b as RequestContext, H as HookSystem, c as IControllerResponse, P as PaginatedResult } from './index-D5QTob1X.js';
+
+/**
+ * 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(),
+ *   // ...
+ * });
+ */
+
+/**
+ * Flexible repository interface that accepts any repository shape
+ * Core CRUD methods use flexible signatures to work with any implementation
+ * Custom methods can be added via the index signature
+ *
+ * @example
+ * // MongoKit repository with custom methods
+ * interface MyRepository extends FlexibleRepository {
+ *   findByEmail(email: string): Promise<User>;
+ *   customMethod(): Promise<void>;
+ * }
+ */
+interface FlexibleRepository {
+    getAll(...args: any[]): Promise<any>;
+    getById(...args: any[]): Promise<any>;
+    create(...args: any[]): Promise<any>;
+    update(...args: any[]): Promise<any>;
+    delete(...args: any[]): Promise<any>;
+    [key: string]: any;
+}
+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
+ *
+ * @template TDoc - The document type
+ * @template TRepository - The repository type (defaults to CrudRepository<TDoc>, preserves custom methods when specified)
+ *
+ * Use with Fastify adapter for Fastify integration (see createFastifyAdapter in createCrudRouter)
+ *
+ * @example
+ * // Without custom repository type (backward compatible)
+ * class SimpleController extends BaseController<Product> {
+ *   constructor(repository: CrudRepository<Product>) {
+ *     super(repository);
+ *   }
+ * }
+ *
+ * @example
+ * // With custom repository type (type-safe access to custom methods)
+ * class ProductController extends BaseController<Product, ProductRepository> {
+ *   constructor(repository: ProductRepository) {
+ *     super(repository);
+ *   }
+ *
+ *   async customMethod(context: IRequestContext) {
+ *     // TypeScript knows about ProductRepository's custom methods
+ *     return await this.repository.findByCategory(...);
+ *   }
+ * }
+ */
+declare class BaseController<TDoc = AnyRecord, TRepository extends FlexibleRepository = FlexibleRepository> 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 disableEvents: boolean;
+    /** Preset field names for dynamic param reading */
+    protected _presetFields: {
+        slugField?: string;
+        parentField?: string;
+    };
+    constructor(repository: TRepository, 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(req: IRequestContext): ServiceContext;
+    /**
+     * Parse query into QueryOptions using queryParser
+     */
+    protected _parseQueryOptions(req: IRequestContext): ControllerQueryOptions;
+    /**
+     * Apply org and policy filters
+     */
+    protected _applyFilters(options: ControllerQueryOptions, req: 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, req: 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, req: 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, req: 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(req: IRequestContext): HookSystem;
+    /**
+     * List resources with filtering, pagination, sorting
+     * Implements IController.list()
+     */
+    list(req: IRequestContext): Promise<IControllerResponse<PaginatedResult<TDoc>>>;
+    /**
+     * Get single resource by ID
+     * Implements IController.get()
+     */
+    get(req: IRequestContext): Promise<IControllerResponse<TDoc>>;
+    /**
+     * Create new resource
+     * Implements IController.create()
+     */
+    create(req: IRequestContext): Promise<IControllerResponse<TDoc>>;
+    /**
+     * Update existing resource
+     * Implements IController.update()
+     */
+    update(req: IRequestContext): Promise<IControllerResponse<TDoc>>;
+    /**
+     * Delete resource
+     * Implements IController.delete()
+     */
+    delete(req: IRequestContext): Promise<IControllerResponse<{
+        message: string;
+    }>>;
+    /** Get resource by slug (slugLookup preset) */
+    getBySlug(req: IRequestContext): Promise<IControllerResponse<TDoc>>;
+    /** Get soft-deleted resources (softDelete preset) */
+    getDeleted(req: IRequestContext): Promise<IControllerResponse<PaginatedResult<TDoc>>>;
+    /** Restore soft-deleted resource (softDelete preset) */
+    restore(req: IRequestContext): Promise<IControllerResponse<TDoc>>;
+    /** Get hierarchical tree (tree preset) */
+    getTree(req: IRequestContext): Promise<IControllerResponse<TDoc[]>>;
+    /** Get children of parent (tree preset) */
+    getChildren(req: IRequestContext): Promise<IControllerResponse<TDoc[]>>;
+}
+
+export { BaseController as B, type BaseControllerOptions as a };

package/dist/adapters/index.d.ts

@@ -1,5 +1,5 @@
-import { D as DataAdapter, f as CrudRepository, i as RepositoryLike, p as SchemaMetadata, g as RouteSchemaOptions, af as OpenApiSchemas, h as QueryParserInterface, ae as ParsedQuery, V as ValidationResult } from '../index-DkAW8BXh.js';
-export { ag as AdapterFactory, F as FieldMetadata, q as RelationMetadata } from '../index-DkAW8BXh.js';
+import { D as DataAdapter, y as CrudRepository, o as RepositoryLike, m as SchemaMetadata, R as RouteSchemaOptions, af as OpenApiSchemas, Q as QueryParserInterface, ae as ParsedQuery, V as ValidationResult } from '../index-D5QTob1X.js';
+export { ag as AdapterFactory, F as FieldMetadata, n as RelationMetadata } from '../index-D5QTob1X.js';
 import { Model } from 'mongoose';
 import 'fastify';
 import '../types-B99TBmFV.js';

package/dist/{arcCorePlugin-DTPWXcZN.d.ts → arcCorePlugin-CAjBQtZB.d.ts}

@@ -1,5 +1,5 @@
 import { FastifyPluginAsync, FastifyInstance, FastifyRequest } from 'fastify';
-import { H as HookSystem, b as ResourceRegistry } from './index-DkAW8BXh.js';
+import { H as HookSystem, j as ResourceRegistry } from './index-D5QTob1X.js';
 
 /**
  * Request ID Plugin

package/dist/auth/index.d.ts

@@ -1,5 +1,5 @@
 import { FastifyPluginAsync } from 'fastify';
-import { A as AuthHelpers, a as AuthPluginOptions } from '../index-DkAW8BXh.js';
+import { g as AuthHelpers, h as AuthPluginOptions } from '../index-D5QTob1X.js';
 import 'mongoose';
 import '../types-B99TBmFV.js';
 

package/dist/cli/commands/generate.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Arc CLI - Generate Command
+ *
+ * Scaffolds resources with consistent naming:
+ * - src/resources/product/product.model.ts
+ * - src/resources/product/product.repository.ts
+ * - src/resources/product/product.resource.ts
+ * - src/resources/product/product.controller.ts
+ * - src/resources/product/product.schemas.ts
+ */
+/**
+ * Generate command handler
+ */
+declare function generate(type: string | undefined, args: string[]): Promise<void>;
+
+export { generate as default, generate };

package/dist/cli/commands/generate.js

@@ -0,0 +1,334 @@
+import { existsSync, mkdirSync, writeFileSync } from 'fs';
+import { join } from 'path';
+
+// src/cli/commands/generate.ts
+function isTypeScriptProject() {
+  return existsSync(join(process.cwd(), "tsconfig.json"));
+}
+function getTemplates(ts) {
+  return {
+    model: (name) => `/**
+ * ${name} Model
+ * Generated by Arc CLI
+ */
+
+import mongoose${ts ? ", { type HydratedDocument }" : ""} from 'mongoose';
+
+const { Schema } = mongoose;
+${ts ? `
+type ${name} = {
+  name: string;
+  description?: string;
+  isActive: boolean;
+};
+
+export type ${name}Document = HydratedDocument<${name}>;
+` : ""}
+const ${name.toLowerCase()}Schema = new Schema${ts ? `<${name}>` : ""}(
+  {
+    name: { type: String, required: true, trim: true },
+    description: { type: String, trim: true },
+    isActive: { type: Boolean, default: true },
+  },
+  { timestamps: true }
+);
+
+// Indexes
+${name.toLowerCase()}Schema.index({ name: 1 });
+${name.toLowerCase()}Schema.index({ isActive: 1 });
+
+const ${name} = mongoose.models.${name}${ts ? ` as mongoose.Model<${name}>` : ""} || mongoose.model${ts ? `<${name}>` : ""}('${name}', ${name.toLowerCase()}Schema);
+export default ${name};
+`,
+    repository: (name) => `/**
+ * ${name} Repository
+ * Generated by Arc CLI
+ */
+
+import {
+  Repository,
+  methodRegistryPlugin,
+  softDeletePlugin,
+  mongoOperationsPlugin,
+} from '@classytic/mongokit';
+${ts ? `import type { ${name}Document } from './${name.toLowerCase()}.model.js';` : ""}
+import ${name} from './${name.toLowerCase()}.model.js';
+
+class ${name}Repository extends Repository${ts ? `<${name}Document>` : ""} {
+  constructor() {
+    super(${name}${ts ? " as any" : ""}, [
+      methodRegistryPlugin(),
+      softDeletePlugin(),
+      mongoOperationsPlugin(),
+    ]);
+  }
+
+  /**
+   * Find all active records
+   */
+  async findActive() {
+    return this.Model.find({ isActive: true, deletedAt: null }).lean();
+  }
+
+  // Add custom repository methods here
+}
+
+const ${name.toLowerCase()}Repository = new ${name}Repository();
+export default ${name.toLowerCase()}Repository;
+export { ${name}Repository };
+`,
+    controller: (name) => `/**
+ * ${name} Controller
+ * Generated by Arc CLI
+ */
+
+import { BaseController } from '@classytic/arc';
+import ${name.toLowerCase()}Repository from './${name.toLowerCase()}.repository.js';
+import { ${name.toLowerCase()}SchemaOptions } from './${name.toLowerCase()}.schemas.js';
+
+class ${name}Controller extends BaseController {
+  constructor() {
+    super(${name.toLowerCase()}Repository${ts ? " as any" : ""}, { schemaOptions: ${name.toLowerCase()}SchemaOptions });
+  }
+
+  // Add custom controller methods here
+}
+
+const ${name.toLowerCase()}Controller = new ${name}Controller();
+export default ${name.toLowerCase()}Controller;
+`,
+    schemas: (name) => `/**
+ * ${name} Schemas
+ * Generated by Arc CLI
+ */
+
+import ${name} from './${name.toLowerCase()}.model.js';
+import { buildCrudSchemasFromModel } from '@classytic/mongokit/utils';
+
+/**
+ * CRUD Schemas with Field Rules
+ */
+const crudSchemas = buildCrudSchemasFromModel(${name}, {
+  strictAdditionalProperties: true,
+  fieldRules: {
+    // Mark fields as system-managed (excluded from create/update)
+    // deletedAt: { systemManaged: true },
+  },
+  query: {
+    filterableFields: {
+      isActive: 'boolean',
+      createdAt: 'date',
+    },
+  },
+});
+
+// Schema options for controller
+export const ${name.toLowerCase()}SchemaOptions${ts ? ": any" : ""} = {
+  query: {
+    filterableFields: {
+      isActive: 'boolean',
+      createdAt: 'date',
+    },
+  },
+};
+
+export default crudSchemas;
+`,
+    resource: (name) => `/**
+ * ${name} Resource
+ * Generated by Arc CLI
+ */
+
+import { defineResource } from '@classytic/arc';
+import { createAdapter } from '#shared/adapter.js';
+import { publicReadPermissions } from '#shared/permissions.js';
+import ${name} from './${name.toLowerCase()}.model.js';
+import ${name.toLowerCase()}Repository from './${name.toLowerCase()}.repository.js';
+import ${name.toLowerCase()}Controller from './${name.toLowerCase()}.controller.js';
+
+const ${name.toLowerCase()}Resource = defineResource({
+  name: '${name.toLowerCase()}',
+  displayName: '${name}s',
+  prefix: '/${name.toLowerCase()}s',
+
+  adapter: createAdapter(${name}, ${name.toLowerCase()}Repository),
+  controller: ${name.toLowerCase()}Controller,
+
+  presets: ['softDelete'],
+
+  permissions: publicReadPermissions,
+
+  // Add custom routes here:
+  // additionalRoutes: [
+  //   {
+  //     method: 'GET',
+  //     path: '/custom',
+  //     summary: 'Custom endpoint',
+  //     handler: async (request, reply) => { ... },
+  //   },
+  // ],
+});
+
+export default ${name.toLowerCase()}Resource;
+`,
+    test: (name) => `/**
+ * ${name} Tests
+ * Generated by Arc CLI
+ */
+
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import mongoose from 'mongoose';
+import { createAppInstance } from '../src/app.js';
+${ts ? "import type { FastifyInstance } from 'fastify';\n" : ""}
+describe('${name} Resource', () => {
+  let app${ts ? ": FastifyInstance" : ""};
+
+  beforeAll(async () => {
+    const testDbUri = process.env.MONGODB_URI || 'mongodb://localhost:27017/test-${name.toLowerCase()}';
+    await mongoose.connect(testDbUri);
+    app = await createAppInstance();
+    await app.ready();
+  });
+
+  afterAll(async () => {
+    await app.close();
+    await mongoose.connection.close();
+  });
+
+  describe('GET /${name.toLowerCase()}s', () => {
+    it('should return a list', async () => {
+      const response = await app.inject({
+        method: 'GET',
+        url: '/${name.toLowerCase()}s',
+      });
+
+      expect(response.statusCode).toBe(200);
+      const body = JSON.parse(response.body);
+      expect(body).toHaveProperty('docs');
+    });
+  });
+});
+`
+  };
+}
+async function generate(type, args) {
+  if (!type) {
+    console.error("Error: Missing type argument");
+    console.log("Usage: arc generate <resource|controller|model|repository|schemas> <name>");
+    process.exit(1);
+  }
+  const [name] = args;
+  if (!name) {
+    console.error("Error: Missing name argument");
+    console.log("Usage: arc generate <type> <name>");
+    console.log("Example: arc generate resource product");
+    process.exit(1);
+  }
+  const capitalizedName = name.charAt(0).toUpperCase() + name.slice(1);
+  const lowerName = name.toLowerCase();
+  const ts = isTypeScriptProject();
+  const ext = ts ? "ts" : "js";
+  const templates = getTemplates(ts);
+  const resourcePath = join(process.cwd(), "src", "resources", lowerName);
+  switch (type) {
+    case "resource":
+    case "r":
+      await generateResource(capitalizedName, lowerName, resourcePath, templates, ext);
+      break;
+    case "controller":
+    case "c":
+      await generateFile(capitalizedName, lowerName, resourcePath, "controller", templates.controller, ext);
+      break;
+    case "model":
+    case "m":
+      await generateFile(capitalizedName, lowerName, resourcePath, "model", templates.model, ext);
+      break;
+    case "repository":
+    case "repo":
+      await generateFile(capitalizedName, lowerName, resourcePath, "repository", templates.repository, ext);
+      break;
+    case "schemas":
+    case "s":
+      await generateFile(capitalizedName, lowerName, resourcePath, "schemas", templates.schemas, ext);
+      break;
+    default:
+      console.error(`Unknown type: ${type}`);
+      console.log("Available types: resource, controller, model, repository, schemas");
+      process.exit(1);
+  }
+}
+async function generateResource(name, lowerName, resourcePath, templates, ext) {
+  console.log(`
+📦 Generating resource: ${name}...
+`);
+  if (!existsSync(resourcePath)) {
+    mkdirSync(resourcePath, { recursive: true });
+    console.log(`  📁 Created: src/resources/${lowerName}/`);
+  }
+  const files = {
+    [`${lowerName}.model.${ext}`]: templates.model(name),
+    [`${lowerName}.repository.${ext}`]: templates.repository(name),
+    [`${lowerName}.controller.${ext}`]: templates.controller(name),
+    [`${lowerName}.schemas.${ext}`]: templates.schemas(name),
+    [`${lowerName}.resource.${ext}`]: templates.resource(name)
+  };
+  for (const [filename, content] of Object.entries(files)) {
+    const filepath = join(resourcePath, filename);
+    if (existsSync(filepath)) {
+      console.warn(`  ⚠  Skipped: ${filename} (already exists)`);
+    } else {
+      writeFileSync(filepath, content);
+      console.log(`  ✅ Created: ${filename}`);
+    }
+  }
+  const testsDir = join(process.cwd(), "tests");
+  if (!existsSync(testsDir)) {
+    mkdirSync(testsDir, { recursive: true });
+  }
+  const testPath = join(testsDir, `${lowerName}.test.${ext}`);
+  if (!existsSync(testPath)) {
+    writeFileSync(testPath, templates.test(name));
+    console.log(`  ✅ Created: tests/${lowerName}.test.${ext}`);
+  }
+  console.log(`
+╔═══════════════════════════════════════════════════════════════╗
+║                    ✅ Resource Generated!                     ║
+╚═══════════════════════════════════════════════════════════════╝
+
+Next steps:
+
+1. Register in src/resources/index.${ext}:
+   import ${lowerName}Resource from './${lowerName}/${lowerName}.resource.js';
+
+   export const resources = [
+     // ... existing resources
+     ${lowerName}Resource,
+   ];
+
+2. Customize the model schema in:
+   src/resources/${lowerName}/${lowerName}.model.${ext}
+
+3. Run tests:
+   npm test
+`);
+}
+async function generateFile(name, lowerName, resourcePath, fileType, template, ext) {
+  console.log(`
+📦 Generating ${fileType}: ${name}...
+`);
+  if (!existsSync(resourcePath)) {
+    mkdirSync(resourcePath, { recursive: true });
+    console.log(`  📁 Created: src/resources/${lowerName}/`);
+  }
+  const filename = `${lowerName}.${fileType}.${ext}`;
+  const filepath = join(resourcePath, filename);
+  if (existsSync(filepath)) {
+    console.error(`  ❌ Error: ${filename} already exists`);
+    process.exit(1);
+  }
+  writeFileSync(filepath, template(name));
+  console.log(`  ✅ Created: ${filename}`);
+}
+var generate_default = generate;
+
+export { generate_default as default, generate };

package/dist/cli/commands/init.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Arc CLI - Init Command
+ *
+ * Scaffolds a new Arc project with clean architecture:
+ * - MongoKit or Custom adapter
+ * - Multi-tenant or Single-tenant
+ * - TypeScript or JavaScript
+ *
+ * Automatically installs dependencies using detected package manager.
+ */
+interface InitOptions {
+    name?: string;
+    adapter?: 'mongokit' | 'custom';
+    tenant?: 'multi' | 'single';
+    typescript?: boolean;
+    skipInstall?: boolean;
+    force?: boolean;
+}
+/**
+ * Initialize a new Arc project
+ */
+declare function init(options?: InitOptions): Promise<void>;
+
+export { type InitOptions, init as default, init };