// Express route — 3 lines
const parsed = parser.parse(req.query);
const result = await orderRepo.getAll(
  { filters: parsed.filters, sort: parsed.sort, limit: parsed.limit },
  { populateOptions: parsed.populateOptions, populate: parsed.populate },
);

// Express route — getAll auto-routes to $lookup when lookups are present
const parsed = parser.parse(req.query);
const result = await repo.getAll({
  filters: parsed.filters,
  sort: parsed.sort,
  lookups: parsed.lookups,   // auto-routes to lookupPopulate
  select: parsed.select,
  limit: parsed.limit,
});

import {
  Repository,
  methodRegistryPlugin,
  auditTrailPlugin,
} from "@classytic/mongokit";

const repo = new Repository(JobModel, [
  methodRegistryPlugin(),
  auditTrailPlugin({
    operations: ["create", "update", "delete"], // Which ops to track
    trackChanges: true, // Field-level before/after diff on updates
    trackDocument: false, // Full doc snapshot on create (heavy)
    ttlDays: 90, // Auto-purge after 90 days (MongoDB TTL index)
    excludeFields: ["password", "token"], // Redact sensitive fields
    metadata: (context) => ({
      // Custom metadata per entry
      ip: context.req?.ip,
      userAgent: context.req?.headers?.["user-agent"],
    }),
  }),
]);

// Query audit trail for a specific document (requires methodRegistryPlugin)
const trail = await repo.getAuditTrail(documentId, {
  page: 1,
  limit: 20,
  operation: "update", // Optional filter
});
// → { docs, page, limit, total, pages, hasNext, hasPrev }

import { AuditTrailQuery } from "@classytic/mongokit";

const auditQuery = new AuditTrailQuery(); // 'audit_trails' collection

// All audits for an org
const orgAudits = await auditQuery.getOrgTrail(orgId);

// All actions by a user
const userAudits = await auditQuery.getUserTrail(userId);

// History of a specific document
const docHistory = await auditQuery.getDocumentTrail("Job", jobId);

// Custom query with date range
const recent = await auditQuery.query({
  orgId,
  operation: "delete",
  from: new Date("2025-01-01"),
  to: new Date(),
  page: 1,
  limit: 50,
});

// Direct model access for anything custom
const model = auditQuery.getModel();
const deleteCount = await model.countDocuments({ operation: "delete" });

import type { AuditTrailMethods } from "@classytic/mongokit";

type JobRepoWithAudit = JobRepo & AuditTrailMethods;

const repo = new JobRepo(JobModel, [
  methodRegistryPlugin(),
  auditTrailPlugin({ ttlDays: 90 }),
]) as JobRepoWithAudit;

// Full autocomplete for getAuditTrail
const trail = await repo.getAuditTrail(jobId, { operation: "update" });

import {
  Repository,
  customIdPlugin,
  sequentialId,
  dateSequentialId,
  prefixedId,
} from "@classytic/mongokit";

const invoiceRepo = new Repository(InvoiceModel, [
  customIdPlugin({
    field: "invoiceNumber",
    generator: sequentialId({
      prefix: "INV",
      model: InvoiceModel,
    }),
  }),
]);

const inv1 = await invoiceRepo.create({ amount: 100 });
// inv1.invoiceNumber → "INV-0001"

const inv2 = await invoiceRepo.create({ amount: 200 });
// inv2.invoiceNumber → "INV-0002"

const billRepo = new Repository(BillModel, [
  customIdPlugin({
    field: "billNumber",
    generator: dateSequentialId({
      prefix: "BILL",
      model: BillModel,
      partition: "monthly", // resets each month
    }),
  }),
]);

const bill = await billRepo.create({ total: 250 });
// bill.billNumber → "BILL-2026-02-0001"

const orderRepo = new Repository(OrderModel, [
  customIdPlugin({
    field: "orderRef",
    generator: prefixedId({ prefix: "ORD", length: 10 }),
  }),
]);

const order = await orderRepo.create({ total: 99 });
// order.orderRef → "ORD_a7b3xk9m2p"

const repo = new Repository(OrderModel, [
  customIdPlugin({
    field: "orderRef",
    generator: async (context) => {
      const region = context.data?.region || "US";
      const seq = await getNextSequence("orders");
      return `ORD-${region}-${String(seq).padStart(4, "0")}`;
    },
  }),
]);
// → "ORD-US-0001", "ORD-EU-0002", ...

const docs = await invoiceRepo.createMany([
  { amount: 10 },
  { amount: 20, invoiceNumber: "MANUAL-001" }, // skipped (already has ID)
  { amount: 30 },
]);
// docs[0].invoiceNumber → "INV-0001"
// docs[1].invoiceNumber → "MANUAL-001"  (preserved)
// docs[2].invoiceNumber → "INV-0002"

import { getNextSequence } from "@classytic/mongokit";

const seq = await getNextSequence("my-counter"); // → 1, 2, 3, ...
const batch = await getNextSequence("my-counter", 5); // → jumps by 5

import {
  Repository,
  methodRegistryPlugin,
  elasticSearchPlugin,
} from "@classytic/mongokit";
import { Client } from "@elastic/elasticsearch"; // or '@opensearch-project/opensearch'

const esClient = new Client({ node: "http://localhost:9200" });

const productRepo = new Repository(ProductModel, [
  methodRegistryPlugin(), // Required first
  elasticSearchPlugin({
    client: esClient,
    index: "products",
    idField: "_id", // field in ES doc that maps to MongoDB _id
  }),
]);

// Perform semantic/full-text search
const results = await productRepo.search(
  { match: { description: "wireless headphones" } },
  {
    limit: 20, // capped to 1000 max (safety bound)
    from: 0,
    mongoOptions: {
      select: "name price description",
      lean: true,
    },
  },
);

// results.docs - MongoDB documents in ES ranking order
// results.docs[*]._score - ES relevance score (preserved, including 0)
// results.total - total hits count from ES

import {
  Repository,
  methodRegistryPlugin,
  mongoOperationsPlugin,
} from "@classytic/mongokit";
import type { MongoOperationsMethods } from "@classytic/mongokit";

// 1. Create your repository class
class ProductRepo extends Repository<IProduct> {
  // Add custom methods here
  async findBySku(sku: string) {
    return this.getByQuery({ sku });
  }
}

// 2. Create type helper for autocomplete
type ProductRepoWithPlugins = ProductRepo & MongoOperationsMethods<IProduct>;

// 3. Instantiate with type assertion
const repo = new ProductRepo(ProductModel, [
  methodRegistryPlugin(),
  mongoOperationsPlugin(),
]) as ProductRepoWithPlugins;

// 4. Now TypeScript provides full autocomplete and type checking!
await repo.increment(productId, "views", 1); // ✅ Autocomplete works
await repo.upsert({ sku: "ABC" }, { name: "Product" }); // ✅ Type-safe
await repo.pushToArray(productId, "tags", "featured"); // ✅ Validated
await repo.findBySku("ABC"); // ✅ Custom methods too

import type { WithPlugins } from "@classytic/mongokit";

class UserRepo extends Repository<IUser> {}

const repo = new UserRepo(Model, [
  methodRegistryPlugin(),
  mongoOperationsPlugin(),
  softDeletePlugin(),
]) as WithPlugins<IUser, UserRepo>;

// Full TypeScript autocomplete — field names inferred from IUser!
await repo.increment(id, "age", 1); // ✅ "age" autocompleted from IUser
await repo.groupBy("status"); // ✅ "status" autocompleted
await repo.restore(id); // ✅ Returns Promise<IUser>
await repo.getDeleted(); // ✅ Returns OffsetPaginationResult<IUser>
await repo.invalidateCache(id);

// before:* receives context directly — mutate in-place
repo.on("before:create", async (context) => {
  context.data.processedAt = new Date();
});

// after:* receives { context, result }
repo.on("after:create", ({ context, result }) => {
  console.log("Created:", result);
});

// error:* receives { context, error }
repo.on("error:create", ({ context, error }) => {
  console.error("Failed:", error);
});

// Remove a listener
repo.off("after:create", myListener);

import { HOOK_PRIORITY } from "@classytic/mongokit";

// Publish to Kafka after every create
repo.on("after:create", async ({ context, result }) => {
  await kafka.publish("orders.created", {
    operation: context.operation,
    model: context.model,
    document: result,
    userId: context.user?._id,
    tenantId: context.organizationId,
    timestamp: Date.now(),
  });
}, { priority: HOOK_PRIORITY.OBSERVABILITY });

// Redis Pub-Sub on updates
repo.on("after:update", async ({ context, result }) => {
  await redis.publish("order:updated", JSON.stringify({
    id: result._id,
    changes: context.data,
  }));
}, { priority: HOOK_PRIORITY.OBSERVABILITY });

// RabbitMQ on deletes (including soft-deletes)
repo.on("after:delete", async ({ context, result }) => {
  await rabbitMQ.sendToQueue("order.deleted", {
    id: result.id,
    soft: result.soft,
    tenantId: context.organizationId,
  });
}, { priority: HOOK_PRIORITY.OBSERVABILITY });

import type {
  IController,
  IRequestContext,
  IControllerResponse,
} from "@classytic/mongokit";

// IRequestContext - what your controller receives
interface IRequestContext {
  query: Record<string, unknown>; // URL query params
  body: Record<string, unknown>; // Request body
  params: Record<string, string>; // Route params (:id)
  user?: { id: string; role?: string }; // Auth user
  context?: Record<string, unknown>; // Tenant ID, etc.
}

// IControllerResponse - what your controller returns
interface IControllerResponse<T> {
  success: boolean;
  data?: T;
  error?: string;
  status: number;
}

// IController - implement this interface
interface IController<TDoc> {
  list(
    ctx: IRequestContext,
  ): Promise<IControllerResponse<PaginationResult<TDoc>>>;
  get(ctx: IRequestContext): Promise<IControllerResponse<TDoc>>;
  create(ctx: IRequestContext): Promise<IControllerResponse<TDoc>>;
  update(ctx: IRequestContext): Promise<IControllerResponse<TDoc>>;
  delete(
    ctx: IRequestContext,
  ): Promise<IControllerResponse<{ message: string }>>;
}

import { QueryParser } from "@classytic/mongokit";

const parser = new QueryParser({
  maxLimit: 100, // Prevent excessive queries
  maxFilterDepth: 5, // Prevent nested injection
  maxRegexLength: 100, // ReDoS protection
  allowedFilterFields: ['status', 'name', 'email'], // Whitelist filter fields
  allowedSortFields: ['createdAt', 'name'], // Whitelist sort fields
  allowedOperators: ['eq', 'ne', 'in', 'gt', 'lt'], // Whitelist operators
});

// Parse request query
const { filters, limit, page, sort, search } = parser.parse(req.query);

// Read back configured whitelists (used by Arc MCP integration)
parser.allowedFilterFields; // ['status', 'name', 'email'] or undefined
parser.allowedSortFields; // ['createdAt', 'name'] or undefined
parser.allowedOperators; // ['eq', 'ne', 'in', 'gt', 'lt'] or undefined

import { QueryParser } from "@classytic/mongokit";

const parser = new QueryParser();

// Parse URL: /posts?populate[author][select]=name,email&populate[author][match][active]=true
const parsed = parser.parse(req.query);

// Use with Repository
const posts = await postRepo.getAll(
  { filters: parsed.filters, page: parsed.page, limit: parsed.limit },
  { populateOptions: parsed.populateOptions },
);

// URL: /posts?populate[author][select]=name,avatar&populate[comments][limit]=5&populate[comments][sort]=-createdAt&populate[comments][match][approved]=true

const parsed = parser.parse(req.query);
// parsed.populateOptions = [
//   { path: 'author', select: 'name avatar' },
//   { path: 'comments', match: { approved: true }, options: { limit: 5, sort: { createdAt: -1 } } }
// ]

// Simple string populate still works
// URL: /posts?populate=author,category
// parsed.populate = 'author,category'
// parsed.populateOptions = undefined

import { buildCrudSchemasFromModel } from "@classytic/mongokit";

const { crudSchemas } = buildCrudSchemasFromModel(UserModel, {
  fieldRules: {
    organizationId: { immutable: true }, // Can't update after create
    role: { systemManaged: true }, // Users can't set this
    createdAt: { systemManaged: true },
  },
  strictAdditionalProperties: true, // Reject unknown fields
});

// Generated schemas:
// crudSchemas.createBody  - POST body validation
// crudSchemas.updateBody  - PATCH body validation
// crudSchemas.params      - Route params (:id)
// crudSchemas.listQuery   - GET query validation

import {
  Repository,
  QueryParser,
  buildCrudSchemasFromModel,
  type IController,
  type IRequestContext,
  type IControllerResponse,
} from "@classytic/mongokit";

class UserController implements IController<IUser> {
  private repo = new Repository(UserModel);
  private parser = new QueryParser({ maxLimit: 100 });

  async list(ctx: IRequestContext): Promise<IControllerResponse> {
    const { filters, limit, page, sort } = this.parser.parse(ctx.query);

    // Inject tenant filter
    if (ctx.context?.organizationId) {
      filters.organizationId = ctx.context.organizationId;
    }

    const result = await this.repo.getAll({ filters, limit, page, sort });
    return { success: true, data: result, status: 200 };
  }

  async get(ctx: IRequestContext): Promise<IControllerResponse> {
    const doc = await this.repo.getById(ctx.params.id);
    return { success: true, data: doc, status: 200 };
  }

  async create(ctx: IRequestContext): Promise<IControllerResponse> {
    const doc = await this.repo.create(ctx.body);
    return { success: true, data: doc, status: 201 };
  }

  async update(ctx: IRequestContext): Promise<IControllerResponse> {
    const doc = await this.repo.update(ctx.params.id, ctx.body);
    return { success: true, data: doc, status: 200 };
  }

  async delete(ctx: IRequestContext): Promise<IControllerResponse> {
    await this.repo.delete(ctx.params.id);
    return { success: true, data: { message: "Deleted" }, status: 200 };
  }
}

import { buildCrudSchemasFromModel } from "@classytic/mongokit";

const controller = new UserController();
const { crudSchemas } = buildCrudSchemasFromModel(UserModel);

// Routes with auto-validation and OpenAPI docs
fastify.get(
  "/users",
  { schema: { querystring: crudSchemas.listQuery } },
  async (req, reply) => {
    const ctx = { query: req.query, body: {}, params: {}, user: req.user };
    const response = await controller.list(ctx);
    return reply.status(response.status).send(response);
  },
);

fastify.post(
  "/users",
  { schema: { body: crudSchemas.createBody } },
  async (req, reply) => {
    const ctx = { query: {}, body: req.body, params: {}, user: req.user };
    const response = await controller.create(ctx);
    return reply.status(response.status).send(response);
  },
);

fastify.get(
  "/users/:id",
  { schema: { params: crudSchemas.params } },
  async (req, reply) => {
    const ctx = { query: {}, body: {}, params: req.params, user: req.user };
    const response = await controller.get(ctx);
    return reply.status(response.status).send(response);
  },
);

const controller = new UserController();

app.get("/users", async (req, res) => {
  const ctx = { query: req.query, body: {}, params: {}, user: req.user };
  const response = await controller.list(ctx);
  res.status(response.status).json(response);
});

app.post("/users", async (req, res) => {
  const ctx = { query: {}, body: req.body, params: {}, user: req.user };
  const response = await controller.create(ctx);
  res.status(response.status).json(response);
});

import { Repository } from "@classytic/mongokit";
import type { CacheableOptions, ReadOptions } from "@classytic/mongokit";

const repo = new Repository(UserModel); // TDoc inferred from UserModel

// All return types flow correctly
const user = await repo.getById("123"); // IUser | null
const users = await repo.getAll({ page: 1 }); // OffsetPaginationResult<IUser> | KeysetPaginationResult<IUser>

// Discriminated union — TypeScript narrows the type
if (users.method === "offset") {
  console.log(users.total, users.pages); // ✅ Available
}
if (users.method === "keyset") {
  console.log(users.next, users.hasMore); // ✅ Available
}

// Typed options — import and reuse
const opts: CacheableOptions = { skipCache: true, lean: true };
const fresh = await repo.getById("123", opts);

import type {
  InferDocument,   // Extract TDoc from Model: InferDocument<typeof UserModel>
  InferRawDoc,     // TDoc without Mongoose Document methods
  CreateInput,     // Omit<TDoc, '_id' | 'createdAt' | 'updatedAt' | '__v'>
  UpdateInput,     // Partial<Omit<TDoc, '_id' | 'createdAt' | '__v'>>
  DocField,        // (keyof TDoc & string) | (string & {}) — autocomplete + nested paths
  PartialBy,       // Make specific fields optional
  RequiredBy,      // Make specific fields required
  DeepPartial,     // Recursive partial
  KeysOfType,      // Extract keys by value type: KeysOfType<IUser, string>
} from "@classytic/mongokit";

import {
  Repository,
  softDeletePlugin,
  timestampPlugin,
} from "@classytic/mongokit";
import UserModel, { IUser } from "./models/User.js";

class UserRepository extends Repository<IUser> {
  constructor() {
    super(UserModel, [timestampPlugin(), softDeletePlugin()], {
      defaultLimit: 20,
    });
  }

  // Custom domain methods
  async findByEmail(email: string) {
    return this.getByQuery({ email });
  }

  async findActiveUsers() {
    return this.getAll({
      filters: { status: "active" },
      sort: { createdAt: -1 },
    });
  }

  async deactivate(id: string) {
    return this.update(id, { status: "inactive", deactivatedAt: new Date() });
  }
}

// Usage
const userRepo = new UserRepository();
const user = await userRepo.findByEmail("john@example.com");

class AuditedUserRepository extends Repository<IUser> {
  constructor() {
    super(UserModel);
  }

  // Override create to add audit trail
  async create(data: Partial<IUser>, options = {}) {
    const result = await super.create(
      {
        ...data,
        createdBy: getCurrentUserId(),
      },
      options,
    );

    await auditLog("user.created", result._id);
    return result;
  }
}

import { parseDuplicateKeyError } from "@classytic/mongokit";

// Use in custom error handlers
const dupErr = parseDuplicateKeyError(error);
if (dupErr) {
  // dupErr.status === 409
  // dupErr.message includes field name and value
}