@90soft/parse-server-kit 2.9.0 → 2.10.1

package/CLAUDE.md

@@ -1,698 +1,698 @@
-# @90soft/parse-server-kit — Complete Reference
-
-Decorator-driven toolkit for Parse Server. **v2.8.0**
-
-This document is the full API contract. Every signature here is taken from the
-source, not paraphrased. If you are generating code against this library, read
-[Silent failures](#silent-failures) first — most of the ways this library goes
-wrong produce no error at all.
-
----
-
-## Contents
-
-- [Requirements](#requirements) · [Boot order](#boot-order)
-- [Models](#models) — `@ParseClass`, `@ParseField`, `BaseModel`
-- [Cloud functions](#cloud-functions) — `@CloudFunction`, `@Route`
-- [Triggers](#triggers) · [Cron](#cron)
-- [Transactions](#transactions) · [Optimistic locking](#optimistic-locking)
-- [ACL](#acl) · [Middleware](#middleware) · [Indexes](#indexes)
-- [Schema](#schema) · [Validation](#validation) · [Swagger](#swagger)
-- [Utilities](#utilities) · [Constants](#constants) · [Types](#types)
-- [Silent failures](#silent-failures) · [Version matrix](#version-matrix)
-
----
-
-## Requirements
-
-**tsconfig — `experimentalDecorators` is mandatory:**
-
-```jsonc
-{"compilerOptions": {"experimentalDecorators": true}}
-```
-
-This library uses **legacy** decorators. TypeScript 5 defaults to standard
-(TC39) decorators, which are a different feature. Without the flag, every
-decorator misbehaves. `emitDecoratorMetadata` is **not** needed — the library
-reads no `design:type` metadata.
-
-**`Parse` is a global.** The library never imports `parse`; it reads
-`global.Parse` the way cloud code sees it. Install `@types/parse` for the
-type declarations. Do not declare your own global `Parse` namespace — it will
-collide.
-
-**Peers:** `parse >=5`, `express >=4`, `reflect-metadata >=0.1.13`.
-**Optional:** `parse-server >=8.3`, `node-cron >=3`, `swagger-ui-express >=4`,
-`@types/parse >=3`.
-
----
-
-## Boot order
-
-Order is load-bearing. This sequence is the contract:
-
-```ts
-// 1. Models FIRST — @ParseClass calls Parse.Object.registerSubclass at
-//    decorator-evaluation time, so Parse must already be global.
-importFiles(join(__dirname, 'cloudCode/models'));
-importFiles(join(__dirname, 'cloudCode/modules'));
-import './cloudCode/cron';               // @Cron definitions
-
-// 2. Parse Server
-const parseServer = await initializeParseServer();
-
-// 3. Middleware — this order matters
-app.use(removeResultMiddleware);
-app.use(cors());
-app.use(process.env.mountPath, validateEntityRoutes);
-app.use(conditionalJsonMiddleware);
-app.use(process.env.mountPath, restrictRoutes);
-
-// 4. Mount
-app.use(process.env.mountPath, parseServer.app);
-
-// 5. Registries — AFTER mount
-CloudFunctionRegistry.initialize();   // also runs RouteRegistry + version check
-TriggerRegistry.initialize();
-CronRegistry.initialize();
-
-// 6. Docs
-setupSwagger(app, {title: 'My API', version: '1.0.0'});
-
-// 7. After listen
-await applyAllIndexes(parseServer);
-await applyMongoValidators(parseServer);
-```
-
----
-
-## Models
-
-### `@ParseClass(className, options?)`
-
-Class decorator. Registers the Parse subclass, CLP, ACL template, compound
-indexes; auto-registers the model with Swagger and flushes any pending triggers.
-
-```ts
-interface ParseClassOptions {
-  clp?: classLevelPermissions;
-  protectedFields?: {[role: string]: string[]};
-  ACL?: ClassAclTemplate;
-  description?: string;              // Swagger
-  compoundIndexes?: CompoundIndex[];
-}
-```
-
-```ts
-@ParseClass('Product', {
-  clp: {
-    find:   {[roleKey(UserRoles.ADMIN)]: true},
-    get:    {[roleKey(UserRoles.ADMIN)]: true},
-    create: {[roleKey(UserRoles.ADMIN)]: true},
-    update: {[roleKey(UserRoles.ADMIN)]: true},
-    delete: {[roleKey(UserRoles.ADMIN)]: true},
-    count:  {[roleKey(UserRoles.ADMIN)]: true},
-  },
-  compoundIndexes: [{fields: ['status', 'createdAt'], unique: false}],
-})
-export default class Product extends BaseModel { ... }
-```
-
-A `Parse.Role` subclass is detected and **not** registered via
-`registerSubclass` (Parse rejects that).
-
-### `@ParseField(options)`
-
-Property decorator. Defines a getter/setter on the prototype mapping to
-`Parse.Object.get/set`, so `product.name` **is** the supported API — not
-`product.get('name')`.
-
-```ts
-interface ParseFieldOptions {
-  type: 'String' | 'Number' | 'Boolean' | 'Date' | 'Object' | 'Array'
-      | 'GeoPoint' | 'File' | 'Bytes' | 'Polygon' | 'Pointer' | 'Relation';
-  required?: boolean;
-  targetClass?: string;      // REQUIRED for Pointer / Relation
-  description?: string;      // Swagger
-  indexName?: string;        // override generated index name
-  min?: number; max?: number;              // Number only
-  minLength?: number; maxLength?: number;  // String only
-  enum?: string[];           // String only
-  pattern?: string;          // String only, valid RegExp
-  geo?: boolean;             // GeoPoint only → 2dsphere index
-  ttlSeconds?: number;       // Date only → TTL index
-  index?: boolean | 1 | -1;  // mutually exclusive with `unique`
-  unique?: boolean;          // mutually exclusive with `index`
-}
-```
-
-**Options are validated at import time** and throw immediately — a Pointer with
-no `targetClass`, `min` on a String, an invalid regex, `geo` combined with
-`index`, a negative `ttlSeconds`. Failures happen at boot, not in production.
-
-`index` and `unique` are mutually exclusive in the type system. `geo` and
-`ttlSeconds` cannot be combined with either.
-
-### `BaseModel`
-
-```ts
-class BaseModel extends Parse.Object {
-  protected static EXCLUDED_POINTER_CLASSES: string[];  // default ['IMG','File']
-  static pointer<T>(id: string): InstanceType<T>;
-  static fromParams<T>(params: any): InstanceType<T>;
-}
-```
-
-- **`Model.pointer(id)`** — a reference by id, no fetch.
-- **`Model.fromParams(req.params)`** — builds an instance from request params,
-  reading `@ParseField` metadata to convert Pointers, Arrays-of-Pointers, Dates
-  and GeoPoints. Use this in create/update rather than manual `set()`.
-  - Pointer fields whose `targetClass` is in `EXCLUDED_POINTER_CLASSES` are
-    **skipped** (`IMG`, `File` need their own handling).
-  - An Array field converts to pointers **only if `targetClass` is set**.
-  - A Pointer given `null` or `{}` is set to `null` (explicit clear).
-
-`Parse.Query` returns `Parse.Object`, not your typed class — cast the result
-(`row as Product`) or direct property access is unavailable.
-
----
-
-## Cloud functions
-
-### `@CloudFunction(config)`
-
-Static-method decorator. Registers the function and wraps it with role checking.
-
-```ts
-interface RouteConfig {
-  methods: HttpMethod[];                      // 'GET'|'POST'|'PUT'|'DELETE'|'PATCH'
-  requiresAuth?: boolean;
-  rateLimit?: {windowMs: number; max: number};
-  validation?: Parse.Cloud.Validator;
-  description?: string;
-  requireRoles?: string[];
-  requireAllRoles?: boolean;                  // default false = ANY role
-  customErrorMessage?: string;
-  swagger?: {summary?; description?; tags?; deprecated?; responses?};
-}
-```
-
-`requireRoles` is enforced by the wrapper before your body runs: no user →
-`OBJECT_NOT_FOUND 'Authentication required'`; wrong roles →
-`OPERATION_FORBIDDEN`. `requireAllRoles: true` demands every listed role.
-
-**GET params arrive as strings** — `validateEntityRoutes` merges the query
-string into the body. Declare them `{type: String}` and convert:
-
-```ts
-const limit = Number(req.params.limit) || 10;
-const active = req.params.isActive === 'true';
-```
-
-### `@ProtectedCloudFunction(config?)`
-
-`@CloudFunction` with `methods: ['POST']` and `validation: {requireUser: true}`
-pre-applied; your config overrides.
-
-### `@Route(ModelOrString)`
-
-Class decorator mapping methods to REST routes. Captures **both** prototype and
-static method names.
-
-```ts
-@Route(Product)         // → /api/products/*    (kebab-plural of the JS class name)
-@Route('menu-items')    // → /api/menu-items/*
-```
-
-The route is `/{prefix}/{methodName}` — **the method name is the route**, matched
-against the class's real method list, so there is no string parsing and no
-collision between `getProduct` and `getProductCategory`.
-
-```
-createProduct → POST /api/products/createProduct
-listProducts  → GET  /api/products/listProducts
-```
-
----
-
-## Triggers
-
-All are static-method decorators taking `{description?, validation?}`.
-
-> **Triggers only register if the class also has `@ParseClass`.** They park in
-> metadata until `@ParseClass` names the class and flushes them. On a plain
-> class they are silently never registered.
-
-| Decorator | Registers as |
-|---|---|
-| `@BeforeSave` `@AfterSave` | `Parse.Cloud.beforeSave(className, …)` |
-| `@BeforeDelete` `@AfterDelete` | `beforeDelete` / `afterDelete` |
-| `@BeforeFind` `@AfterFind` | `beforeFind` / `afterFind` |
-| `@BeforeLogin` `@AfterLogin` `@AfterLogout` | auth triggers (no className) |
-| `@BeforePasswordResetRequest` | `beforePasswordResetRequest` — parse-server 8.5+ |
-| `@BeforeSaveFile` `@AfterSaveFile` | `beforeSave(Parse.File, …)` |
-| `@BeforeDeleteFile` `@AfterDeleteFile` | `beforeDelete(Parse.File, …)` |
-| `@BeforeFindFile` `@AfterFindFile` | `beforeFind(Parse.File, …)` — 8.1+ |
-| `@BeforeSaveConfig` `@AfterSaveConfig` | `beforeSave(Parse.Config, …)` — 7.3+ |
-| `@BeforeConnect` `@BeforeSubscribe` `@AfterEvent` | LiveQuery (`afterEvent` → `afterLiveQueryEvent`) |
-
-File and Config triggers pass the **class itself**, not a name. parse-server
-removed the old `beforeSaveFile()` style methods; this library handles the
-translation.
-
-One trigger per `className:type` — a second registration warns and overwrites.
-
-```ts
-@ParseClass('Product', {...})
-export default class Product extends BaseModel {
-  @BeforeSave()
-  static async onBeforeSave(req: Parse.Cloud.BeforeSaveRequest<Product>) {
-    if (!req.object.get('name')) throw new Parse.Error(142, 'Name is required');
-  }
-}
-```
-
----
-
-## Cron
-
-```ts
-interface CronConfig {
-  schedule: string;      // cron expression, validated at initialize()
-  description?: string;
-  enabled?: boolean;     // default true
-  timezone?: string;     // default 'UTC'
-}
-```
-
-```ts
-class Jobs {
-  @Cron({schedule: CronSchedule.DAILY_MIDNIGHT, description: 'Cleanup'})
-  static async cleanup() { ... }
-}
-```
-
-`CronSchedule`: `EVERY_MINUTE`, `EVERY_5_MINUTES`, `EVERY_10_MINUTES`,
-`EVERY_15_MINUTES`, `EVERY_30_MINUTES`, `EVERY_HOUR`, `EVERY_2_HOURS`,
-`EVERY_6_HOURS`, `EVERY_12_HOURS`, `DAILY_MIDNIGHT`, `DAILY_NOON`,
-`WEEKLY_SUNDAY`, `WEEKLY_MONDAY`, `MONTHLY_FIRST`, `YEARLY`.
-
-`CronRegistry`: `initialize()`, `getJobs()`, `getJob(name)`, `stopJob(name)`,
-`startJob(name)`, `stopAll()`, `runNow(name)`. Without `node-cron` installed,
-`initialize()` warns and skips — jobs never run.
-
----
-
-## Transactions
-
-MongoDB only. Requires a **replica set** and parse-server `directAccess: true`.
-
-```ts
-const parseServer = new ParseServer({
-  databaseAdapter: createVersionedMongoAdapter({
-    uri: process.env.DATABASE_URI, collectionPrefix: '', mongoOptions: {},
-  }),
-  directAccess: true,   // REQUIRED — see below
-});
-```
-
-```ts
-function Transactional(): MethodDecorator;
-function withTransaction<T>(body: () => Promise<T>): Promise<T>;
-function inTransaction(): boolean;
-function currentSession(): unknown;
-const CONFLICT = 5001;
-const CONFLICT_MESSAGE: string;
-```
-
-### ⚠️ Decorator order
-
-```ts
-@CloudFunction({...})   // MUST be above — sees the wrapped method
-@Transactional()        // MUST be below — does the wrapping
-static async submitJob(req) { ... }
-```
-
-Decorators apply bottom-up and `@CloudFunction` captures the method when
-applied. Reversed, the registry keeps the **unwrapped** method and the
-transaction **never opens** — no error, no log.
-
-### Semantics
-
-- Every `save()` / `destroy()` / query inside the body joins automatically
-  (`AsyncLocalStorage` follows the call chain). No session threading.
-- **Nested calls join** the outer transaction; the outermost caller commits.
-- **The body may re-run** (up to 3 attempts) on a transient conflict, so it must
-  be safe to repeat. After 3 losses the caller gets `CONFLICT`.
-- Each concurrent request gets its **own** session — unlike Parse Server's
-  built-in transaction, which is `DatabaseController`-global.
-- Never joined: `_SCHEMA`, `_Idempotency`, `_Hooks`, `_JobStatus`,
-  `_GlobalConfig` — schema creation must survive a rollback.
-- Unfiltered `count()` reads **outside** the transaction (MongoDB refuses
-  `count` inside one).
-
-Without `directAccess`, a `save()` in cloud code becomes an internal HTTP
-request landing in a fresh async context, and writes **outside** the
-transaction. That failure has no symptom.
-
----
-
-## Optimistic locking
-
-```ts
-@ParseClass('Job')
-class Job extends BaseModel {
-  @ParseVersionField()   // declares the Number field itself — no @ParseField
-  version!: number;
-}
-```
-
-That is the entire feature. No endpoint reads or writes the field:
-
-- every object **read** carries the version it was read at; every `save()` /
-  `saveAll()` asserts it automatically;
-- the adapter moves the assertion into the write's **filter** and `$inc`s the
-  field, so the next reader gets a fresh number;
-- a lost race is refused with `CONFLICT` (5001); a genuinely missing row still
-  reads as missing;
-- creates get version `1` from the adapter — callers never supply one;
-- an object built from a bare id (never read) has nothing to assert and is
-  **not protected**.
-
-```ts
-try {
-  await job.save(null, {useMasterKey: true});
-} catch (error) {
-  if (error instanceof Parse.Error && error.code === CONFLICT) {
-    // Reload, re-apply, retry — or surface CONFLICT_MESSAGE, already
-    // written for the end user.
-  }
-  throw error;
-}
-```
-
-`VERSION_CONFLICT` === `CONFLICT` — a lost lock and a lost transaction race are
-the same event to the person on the screen.
-
-`VersionRegistry`: `fieldFor(className)`, `isVersioned(className)`,
-`classNames()`, `adapterIsInstalled()`, `verify()`.
-
----
-
-## ACL
-
-```ts
-function implementACL(
-  params: {
-    publicRead?: boolean;
-    publicWrite?: boolean;
-    roleRules?: {role: string; read?: boolean; write?: boolean}[];
-    excludedRoles?: string[];
-    owner?: {user?: string | any; read?: boolean; write?: boolean}[];
-  },
-  existingACL?: Parse.ACL
-): Parse.ACL;
-```
-
-**It takes one params object and RETURNS an ACL.** It does not take the object
-as an argument.
-
-```ts
-// CORRECT
-product.setACL(implementACL({
-  roleRules: [
-    {role: UserRoles.ADMIN, read: true, write: true},
-    {role: UserRoles.EMPLOYEE, read: true},
-  ],
-  publicRead: status === 'active',
-  owner: [{user: userId, read: true, write: true}],
-}));
-
-// WRONG — no such signature, will not compile
-implementACL(product, {readRoles: [...], writeRoles: [...]});
-```
-
-```ts
-function syncImageAcl(parent: Parse.Object, fields: string[], acl?: Parse.ACL): void;
-function cloneAcl(acl: Parse.ACL): Parse.ACL;
-```
-
-`syncImageAcl` copies the parent's ACL onto nested image pointers (single or
-array) so they follow the parent's visibility. Call it **after** setting the
-parent's final ACL and **before** saving. For status-derived visibility set in a
-`beforeSave` trigger, pass `publicRead` into `implementACL` at the call site —
-`syncImageAcl` runs before the trigger.
-
----
-
-## Middleware
-
-| Export | Purpose |
-|---|---|
-| `validateEntityRoutes` | Resolves `/api/{entity}/{action}` → cloud function; enforces the declared HTTP method (405); applies `rateLimit`; merges GET query into body; rewrites to `/functions/{name}` as POST |
-| `restrictRoutes` | Blocks `/classes`, `/schemas`, `/batch`. Allows `/health`, `/serverInfo`, `/files`, registered prefixes, `/functions`. Master key bypasses |
-| `removeResultMiddleware` | Unwraps Parse's `{result: …}` response |
-| `conditionalJsonMiddleware` | `express.json({limit:'10mb', type:['text/plain']})`, skipping `{mountPath}/files` |
-| `validateFunctionRoutes` | Legacy `/functions/*` validation |
-| `checkRateLimit(req,res,name,cfg)` | In-process token bucket; returns `false` after sending 429 |
-
-**Master key** is read from the `X-Parse-Master-Key` header (preferred) or the
-request body (deprecated, warns once). Rate limiting is **per process** — no
-enforcement across instances.
-
----
-
-## Indexes
-
-```ts
-function applyAllIndexes(parseServerInstance?: any): Promise<void>;
-const applyUniqueIndexes = applyAllIndexes;   // permanent alias
-function getUniqueIndexes(): UniqueIndexInfo[];
-function getCompoundIndexes(): CompoundIndexInfo[];
-function getFieldIndexes(): FieldIndexInfo[];
-```
-
-Call after `listen()`. Creates, from decorator metadata:
-
-| Source | Index |
-|---|---|
-| `@ParseField({unique: true})` | unique (drops a conflicting non-unique index first) |
-| `@ParseField({index: true \| 1 \| -1})` | B-tree asc/desc |
-| `@ParseField({geo: true})` on GeoPoint | 2dsphere |
-| `@ParseField({ttlSeconds: N})` on Date | TTL |
-| `@ParseClass({compoundIndexes})` | compound |
-
-```ts
-interface CompoundIndex {
-  fields: string[];
-  unique?: boolean;
-  name?: string;
-  sparse?: boolean;
-  partialFilterNulls?: boolean;                       // only index docs where all fields exist
-  fieldTypes?: Record<string, 1|-1|'text'|'2dsphere'|'hashed'>;
-  options?: Record<string, unknown>;                  // e.g. default_language
-}
-```
-
-Existing indexes (codes 85/86) are reported, not treated as errors. If the
-adapter can't be reached it prints the equivalent `db.x.createIndex(...)`
-commands. MongoDB allows only **one text index per collection**.
-
----
-
-## Schema
-
-```ts
-function createSchemaConfig(options?: SchemaConfigOptions): {...};
-
-interface SchemaConfigOptions {
-  adminRole?: string;               // default 'SuperAdmin'
-  lockSchemas?: boolean;            // default false
-  strict?: boolean;                 // default true
-  recreateModifiedFields?: boolean; // default false — DANGEROUS
-  deleteExtraFields?: boolean;      // default false — DANGEROUS
-  keepUnknownIndexes?: boolean;     // default TRUE — parse-server 8.3+
-}
-```
-
-Builds the `schema` option from every registered `@ParseClass`, plus a `_Role`
-definition locked to `adminRole`.
-
-`keepUnknownIndexes` defaults to **true** because `applyAllIndexes` creates
-indexes out-of-band; parse-server's default (`false`) drops indexes it cannot
-account for during schema migration. **Requires parse-server 8.3+** — it refuses
-to start on an unrecognised option.
-
----
-
-## Validation
-
-```ts
-function validateObject(object: Parse.Object): {valid: boolean; errors: {field, message, value?}[]};
-function validateOrThrow(object: Parse.Object): void;   // throws Parse.Error VALIDATION_ERROR
-function getValidators(): {className, validator}[];
-function applyMongoValidators(parseServerInstance?: any): Promise<void>;
-```
-
-Checks `required`, `min`/`max`, `minLength`/`maxLength`, `enum`, `pattern` from
-`@ParseField`. `validateOrThrow` is intended for `@BeforeSave`.
-`applyMongoValidators` pushes the same constraints into MongoDB `$jsonSchema`
-validators (`validationLevel: 'moderate'`, `validationAction: 'error'`), so the
-database enforces them even for writes that bypass your code.
-
----
-
-## Swagger
-
-```ts
-function setupSwagger(app: Express, config: SwaggerConfig, path?: string): void;  // default '/api-docs'
-function generateSwaggerSpec(config: SwaggerConfig): object;
-function getSwaggerJson(config: SwaggerConfig): string;
-
-interface SwaggerConfig {
-  title: string; version: string;
-  description?: string; basePath?: string; host?: string; schemes?: string[];
-}
-```
-
-Models and endpoints are registered automatically from `@ParseClass` /
-`@CloudFunction` — no annotation needed. Endpoints document their real `@Route`
-path. **GET/HEAD emit query `parameters`; everything else emits a JSON
-`requestBody`** (a browser cannot send a GET body). Security schemes derive from
-`requireUser` / `requireMaster` / `requireRoles`.
-
-The spec is always served at `{path}/json`. Without `swagger-ui-express`
-installed, the browser UI is skipped with a warning; the spec still serves.
-
----
-
-## Utilities
-
-```ts
-function catchError<T>(p: Promise<T>): Promise<[undefined, T] | [Error]>;
-function getUserRoles(user: Parse.User): Promise<string[]>;
-function getUsersRoles(users: Parse.User[]): Promise<Map<string, string[]>>;
-function importFiles(dir: string, options?: {extensions?: string[]; verbose?: boolean}): void;
-function generateRandomPassword(length?, includeNumbers?, includeSymbols?): string;
-function generateRandomString(length?: number): string;
-function generateRandomInteger(length: number): string;
-function sleep(ms: number): Promise<unknown>;
-function formatCount(num: any, locale?: string): string;   // compact notation
-```
-
-**`catchError` is the error convention** — use it for all async work rather than
-`try/catch` around `await`:
-
-```ts
-const [err, saved] = await catchError(product.save(null, {sessionToken}));
-if (err) throw err;
-```
-
-**`importFiles` defaults to `.js` only.** Under ts-node/tsx pass
-`{extensions: ['.js', '.ts']}` or nothing is imported at all. Never point it at
-a tree holding both compiled and source copies — every class registers twice.
-
-`getUsersRoles` costs one query per **role** (capped at 100), not per user.
-
-### Role cache (opt-in, off by default)
-
-```ts
-function configureRoleCache(config: {ttlMs: number; maxUsers?: number} | false): void;
-function invalidateRoles(userId?: string): void;   // no arg = everyone
-function roleCacheEnabled(): boolean;
-function roleCacheStats(): {enabled: boolean; size: number; ttlMs: number | null};
-```
-
-`@CloudFunction({requireRoles})` and `getUserRoles()` each cost a database
-round-trip per call. Role membership rarely changes, so it caches well — but a
-**revoked role keeps working until the entry expires**, which is why nothing
-happens until you opt in:
-
-```ts
-configureRoleCache({ttlMs: 30_000});                    // global
-@CloudFunction({requireRoles: [...], roleCacheMs: 0})   // this endpoint never caches
-```
-
-Call `invalidateRoles(userId)` wherever you grant or revoke, and the TTL becomes
-a backstop for changes made outside your code rather than the primary control.
-`maxUsers` (default 10000) bounds memory; the oldest entry is evicted past it.
-There is no timer — entries expire on read.
-
----
-
-## Constants
-
-```ts
-enum UserRoles {ADMIN = 'SuperAdmin', EMPLOYEE = 'Employee'}
-function roleKey(role: UserRoles): `role:${UserRoles}`;
-const MAX_QUERY_LIMIT = 10000;
-```
-
-Use `roleKey(UserRoles.ADMIN)` for CLP/ACL keys — never hardcode
-`'role:SuperAdmin'`.
-
----
-
-## Types
-
-`ClassNameType`, `CLPParamsOption`, `classLevelPermissions`, `ClassAclTemplate`,
-`AclTemplatePermissions`, `ProtectedFields`, `CompoundIndex`, `IndexFieldType`,
-`Fields`, `Indexes`, `SchemaDefinition`, `HttpMethod`, `RouteConfig`,
-`CloudFunctionMetadata`, `SwaggerDocConfig`, `TriggerType`, `TriggerMetadata`,
-`TriggerConfig`, `CronConfig`, `CronJobMetadata`, `RoleString`,
-`ParseClassOptions`, `ParseFieldOptions`, `AllowedFieldType`,
-`SwaggerModelSchema`, `SwaggerPropertySchema`, `SwaggerFunctionSchema`,
-`SchemaConfigOptions`, `TransactionalAdapter`, `VersionedMongoAdapter`,
-`MongoAdapterConstructor`.
-
-```ts
-interface AuthRole  {id: string; name: string}
-interface MultiLangs {ar?: string; en?: string}
-interface Filter    {key: string; value: string|number|string[];
-                     type: 'string'|'min'|'max'|'array'|'text'|'dropdown'}
-```
-
-**Registration hooks** (for custom integrations):
-`onClassRegistered`, `onFieldRegistered`, `onFunctionRegistered`.
-Also exported: `getSchemaDefinition(target)`, `classNames`.
-
----
-
-## Silent failures
-
-Every item here produces **no error**. This is the list to check when something
-"doesn't work" but nothing is logged.
-
-| Symptom | Cause |
-|---|---|
-| Decorators do nothing / odd behaviour | `experimentalDecorators` not set — TS 5 defaults to standard decorators |
-| Transaction never opens | `@Transactional()` placed **above** `@CloudFunction` instead of below |
-| Writes land outside the transaction | parse-server `directAccess` not `true` |
-| No models, empty schema, no routes | `importFiles` ran over `.ts` sources with the default `['.js']` |
-| Every class registered twice | `importFiles` pointed at a tree with both compiled and source copies |
-| Trigger never fires | Declared on a class without `@ParseClass` — pending triggers are never flushed |
-| Unique indexes vanish after restart | `keepUnknownIndexes` false, or parse-server < 8.3 |
-| Pointer field ignored by `fromParams` | `targetClass` missing, or it is `IMG`/`File` (excluded by design) |
-| Array of pointers stays raw | Array field has no `targetClass` |
-| Direct property access unavailable | Query result not cast to the typed model |
-| Cron jobs never run | `node-cron` not installed — `initialize()` warns and skips |
-| Object not protected by version field | Built from a bare id, never read, so there is nothing to assert |
-
-Three of these now **do** log as of v2.8.0: `@ParseVersionField` with no adapter
-(or on Postgres), and a Parse SDK where `_getSaveJSON` has moved. Check the boot
-output for `[Versioning]`.
-
----
-
-## Version matrix
-
-| | Requirement |
-|---|---|
-| Node | ≥ 18 for this package; **≥ 20.19** with parse-server 9 |
-| parse-server | ≥ 8.3 (optional peer) — `keepUnknownIndexes`, adapter internals |
-| MongoDB | ≥ 7.0.16 for parse-server 9; **replica set** for transactions |
-| Parse SDK | ≥ 5; verified on 5.3.0 and 8.6.0 |
-| TypeScript | any, with `experimentalDecorators: true` |
-
-**Transactions and `@ParseVersionField` are MongoDB-only.** On Postgres the
-version field is declared but never enforced.
+# @90soft/parse-server-kit — Complete Reference
+
+Decorator-driven toolkit for Parse Server. **v2.10.1**
+
+This document is the full API contract. Every signature here is taken from the
+source, not paraphrased. If you are generating code against this library, read
+[Silent failures](#silent-failures) first — most of the ways this library goes
+wrong produce no error at all.
+
+---
+
+## Contents
+
+- [Requirements](#requirements) · [Boot order](#boot-order)
+- [Models](#models) — `@ParseClass`, `@ParseField`, `BaseModel`
+- [Cloud functions](#cloud-functions) — `@CloudFunction`, `@Route`
+- [Triggers](#triggers) · [Cron](#cron)
+- [Transactions](#transactions) · [Optimistic locking](#optimistic-locking)
+- [ACL](#acl) · [Middleware](#middleware) · [Indexes](#indexes)
+- [Schema](#schema) · [Validation](#validation) · [Swagger](#swagger)
+- [Utilities](#utilities) · [Constants](#constants) · [Types](#types)
+- [Silent failures](#silent-failures) · [Version matrix](#version-matrix)
+
+---
+
+## Requirements
+
+**tsconfig — `experimentalDecorators` is mandatory:**
+
+```jsonc
+{"compilerOptions": {"experimentalDecorators": true}}
+```
+
+This library uses **legacy** decorators. TypeScript 5 defaults to standard
+(TC39) decorators, which are a different feature. Without the flag, every
+decorator misbehaves. `emitDecoratorMetadata` is **not** needed — the library
+reads no `design:type` metadata.
+
+**`Parse` is a global.** The library never imports `parse`; it reads
+`global.Parse` the way cloud code sees it. Install `@types/parse` for the
+type declarations. Do not declare your own global `Parse` namespace — it will
+collide.
+
+**Peers:** `parse >=5`, `express >=4`, `reflect-metadata >=0.1.13`.
+**Optional:** `parse-server >=8.3`, `node-cron >=3`, `swagger-ui-express >=4`,
+`@types/parse >=3`.
+
+---
+
+## Boot order
+
+Order is load-bearing. This sequence is the contract:
+
+```ts
+// 1. Models FIRST — @ParseClass calls Parse.Object.registerSubclass at
+//    decorator-evaluation time, so Parse must already be global.
+importFiles(join(__dirname, 'cloudCode/models'));
+importFiles(join(__dirname, 'cloudCode/modules'));
+import './cloudCode/cron';               // @Cron definitions
+
+// 2. Parse Server
+const parseServer = await initializeParseServer();
+
+// 3. Middleware — this order matters
+app.use(removeResultMiddleware);
+app.use(cors());
+app.use(process.env.mountPath, validateEntityRoutes);
+app.use(conditionalJsonMiddleware);
+app.use(process.env.mountPath, restrictRoutes);
+
+// 4. Mount
+app.use(process.env.mountPath, parseServer.app);
+
+// 5. Registries — AFTER mount
+CloudFunctionRegistry.initialize();   // also runs RouteRegistry + version check
+TriggerRegistry.initialize();
+CronRegistry.initialize();
+
+// 6. Docs
+setupSwagger(app, {title: 'My API', version: '1.0.0'});
+
+// 7. After listen
+await applyAllIndexes(parseServer);
+await applyMongoValidators(parseServer);
+```
+
+---
+
+## Models
+
+### `@ParseClass(className, options?)`
+
+Class decorator. Registers the Parse subclass, CLP, ACL template, compound
+indexes; auto-registers the model with Swagger and flushes any pending triggers.
+
+```ts
+interface ParseClassOptions {
+  clp?: classLevelPermissions;
+  protectedFields?: {[role: string]: string[]};
+  ACL?: ClassAclTemplate;
+  description?: string;              // Swagger
+  compoundIndexes?: CompoundIndex[];
+}
+```
+
+```ts
+@ParseClass('Product', {
+  clp: {
+    find:   {[roleKey(UserRoles.ADMIN)]: true},
+    get:    {[roleKey(UserRoles.ADMIN)]: true},
+    create: {[roleKey(UserRoles.ADMIN)]: true},
+    update: {[roleKey(UserRoles.ADMIN)]: true},
+    delete: {[roleKey(UserRoles.ADMIN)]: true},
+    count:  {[roleKey(UserRoles.ADMIN)]: true},
+  },
+  compoundIndexes: [{fields: ['status', 'createdAt'], unique: false}],
+})
+export default class Product extends BaseModel { ... }
+```
+
+A `Parse.Role` subclass is detected and **not** registered via
+`registerSubclass` (Parse rejects that).
+
+### `@ParseField(options)`
+
+Property decorator. Defines a getter/setter on the prototype mapping to
+`Parse.Object.get/set`, so `product.name` **is** the supported API — not
+`product.get('name')`.
+
+```ts
+interface ParseFieldOptions {
+  type: 'String' | 'Number' | 'Boolean' | 'Date' | 'Object' | 'Array'
+      | 'GeoPoint' | 'File' | 'Bytes' | 'Polygon' | 'Pointer' | 'Relation';
+  required?: boolean;
+  targetClass?: string;      // REQUIRED for Pointer / Relation
+  description?: string;      // Swagger
+  indexName?: string;        // override generated index name
+  min?: number; max?: number;              // Number only
+  minLength?: number; maxLength?: number;  // String only
+  enum?: string[];           // String only
+  pattern?: string;          // String only, valid RegExp
+  geo?: boolean;             // GeoPoint only → 2dsphere index
+  ttlSeconds?: number;       // Date only → TTL index
+  index?: boolean | 1 | -1;  // mutually exclusive with `unique`
+  unique?: boolean;          // mutually exclusive with `index`
+}
+```
+
+**Options are validated at import time** and throw immediately — a Pointer with
+no `targetClass`, `min` on a String, an invalid regex, `geo` combined with
+`index`, a negative `ttlSeconds`. Failures happen at boot, not in production.
+
+`index` and `unique` are mutually exclusive in the type system. `geo` and
+`ttlSeconds` cannot be combined with either.
+
+### `BaseModel`
+
+```ts
+class BaseModel extends Parse.Object {
+  protected static EXCLUDED_POINTER_CLASSES: string[];  // default ['IMG','File']
+  static pointer<T>(id: string): InstanceType<T>;
+  static fromParams<T>(params: any): InstanceType<T>;
+}
+```
+
+- **`Model.pointer(id)`** — a reference by id, no fetch.
+- **`Model.fromParams(req.params)`** — builds an instance from request params,
+  reading `@ParseField` metadata to convert Pointers, Arrays-of-Pointers, Dates
+  and GeoPoints. Use this in create/update rather than manual `set()`.
+  - Pointer fields whose `targetClass` is in `EXCLUDED_POINTER_CLASSES` are
+    **skipped** (`IMG`, `File` need their own handling).
+  - An Array field converts to pointers **only if `targetClass` is set**.
+  - A Pointer given `null` or `{}` is set to `null` (explicit clear).
+
+`Parse.Query` returns `Parse.Object`, not your typed class — cast the result
+(`row as Product`) or direct property access is unavailable.
+
+---
+
+## Cloud functions
+
+### `@CloudFunction(config)`
+
+Static-method decorator. Registers the function and wraps it with role checking.
+
+```ts
+interface RouteConfig {
+  methods: HttpMethod[];                      // 'GET'|'POST'|'PUT'|'DELETE'|'PATCH'
+  requiresAuth?: boolean;
+  rateLimit?: {windowMs: number; max: number};
+  validation?: Parse.Cloud.Validator;
+  description?: string;
+  requireRoles?: string[];
+  requireAllRoles?: boolean;                  // default false = ANY role
+  customErrorMessage?: string;
+  swagger?: {summary?; description?; tags?; deprecated?; responses?};
+}
+```
+
+`requiresAuth` and `requireRoles` are both enforced by the wrapper before your body runs: no user →
+`OBJECT_NOT_FOUND 'Authentication required'`; wrong roles →
+`OPERATION_FORBIDDEN`. `requireAllRoles: true` demands every listed role.
+
+**GET params arrive as strings** — `validateEntityRoutes` merges the query
+string into the body. Declare them `{type: String}` and convert:
+
+```ts
+const limit = Number(req.params.limit) || 10;
+const active = req.params.isActive === 'true';
+```
+
+### `@ProtectedCloudFunction(config?)`
+
+`@CloudFunction` with `methods: ['POST']` and `validation: {requireUser: true}`
+pre-applied; your config overrides.
+
+### `@Route(ModelOrString)`
+
+Class decorator mapping methods to REST routes. Captures **both** prototype and
+static method names.
+
+```ts
+@Route(Product)         // → /api/products/*    (kebab-plural of the JS class name)
+@Route('menu-items')    // → /api/menu-items/*
+```
+
+The route is `/{prefix}/{methodName}` — **the method name is the route**, matched
+against the class's real method list, so there is no string parsing and no
+collision between `getProduct` and `getProductCategory`.
+
+```
+createProduct → POST /api/products/createProduct
+listProducts  → GET  /api/products/listProducts
+```
+
+---
+
+## Triggers
+
+All are static-method decorators taking `{description?, validation?}`.
+
+> **Triggers only register if the class also has `@ParseClass`.** They park in
+> metadata until `@ParseClass` names the class and flushes them. On a plain
+> class they are silently never registered.
+
+| Decorator | Registers as |
+|---|---|
+| `@BeforeSave` `@AfterSave` | `Parse.Cloud.beforeSave(className, …)` |
+| `@BeforeDelete` `@AfterDelete` | `beforeDelete` / `afterDelete` |
+| `@BeforeFind` `@AfterFind` | `beforeFind` / `afterFind` |
+| `@BeforeLogin` `@AfterLogin` `@AfterLogout` | auth triggers (no className) |
+| `@BeforePasswordResetRequest` | `beforePasswordResetRequest` — parse-server 8.5+ |
+| `@BeforeSaveFile` `@AfterSaveFile` | `beforeSave(Parse.File, …)` |
+| `@BeforeDeleteFile` `@AfterDeleteFile` | `beforeDelete(Parse.File, …)` |
+| `@BeforeFindFile` `@AfterFindFile` | `beforeFind(Parse.File, …)` — 8.1+ |
+| `@BeforeSaveConfig` `@AfterSaveConfig` | `beforeSave(Parse.Config, …)` — 7.3+ |
+| `@BeforeConnect` `@BeforeSubscribe` `@AfterEvent` | LiveQuery (`afterEvent` → `afterLiveQueryEvent`) |
+
+File and Config triggers pass the **class itself**, not a name. parse-server
+removed the old `beforeSaveFile()` style methods; this library handles the
+translation.
+
+One trigger per `className:type` — a second registration warns and overwrites.
+
+```ts
+@ParseClass('Product', {...})
+export default class Product extends BaseModel {
+  @BeforeSave()
+  static async onBeforeSave(req: Parse.Cloud.BeforeSaveRequest<Product>) {
+    if (!req.object.get('name')) throw new Parse.Error(142, 'Name is required');
+  }
+}
+```
+
+---
+
+## Cron
+
+```ts
+interface CronConfig {
+  schedule: string;      // cron expression, validated at initialize()
+  description?: string;
+  enabled?: boolean;     // default true
+  timezone?: string;     // default 'UTC'
+}
+```
+
+```ts
+class Jobs {
+  @Cron({schedule: CronSchedule.DAILY_MIDNIGHT, description: 'Cleanup'})
+  static async cleanup() { ... }
+}
+```
+
+`CronSchedule`: `EVERY_MINUTE`, `EVERY_5_MINUTES`, `EVERY_10_MINUTES`,
+`EVERY_15_MINUTES`, `EVERY_30_MINUTES`, `EVERY_HOUR`, `EVERY_2_HOURS`,
+`EVERY_6_HOURS`, `EVERY_12_HOURS`, `DAILY_MIDNIGHT`, `DAILY_NOON`,
+`WEEKLY_SUNDAY`, `WEEKLY_MONDAY`, `MONTHLY_FIRST`, `YEARLY`.
+
+`CronRegistry`: `initialize()`, `getJobs()`, `getJob(name)`, `stopJob(name)`,
+`startJob(name)`, `stopAll()`, `runNow(name)`. Without `node-cron` installed,
+`initialize()` warns and skips — jobs never run.
+
+---
+
+## Transactions
+
+MongoDB only. Requires a **replica set** and parse-server `directAccess: true`.
+
+```ts
+const parseServer = new ParseServer({
+  databaseAdapter: createVersionedMongoAdapter({
+    uri: process.env.DATABASE_URI, collectionPrefix: '', mongoOptions: {},
+  }),
+  directAccess: true,   // REQUIRED — see below
+});
+```
+
+```ts
+function Transactional(): MethodDecorator;
+function withTransaction<T>(body: () => Promise<T>): Promise<T>;
+function inTransaction(): boolean;
+function currentSession(): unknown;
+const CONFLICT = 5001;
+const CONFLICT_MESSAGE: string;
+```
+
+### ⚠️ Decorator order
+
+```ts
+@CloudFunction({...})   // MUST be above — sees the wrapped method
+@Transactional()        // MUST be below — does the wrapping
+static async submitJob(req) { ... }
+```
+
+Decorators apply bottom-up and `@CloudFunction` captures the method when
+applied. Reversed, the registry keeps the **unwrapped** method and the
+transaction **never opens** — no error, no log.
+
+### Semantics
+
+- Every `save()` / `destroy()` / query inside the body joins automatically
+  (`AsyncLocalStorage` follows the call chain). No session threading.
+- **Nested calls join** the outer transaction; the outermost caller commits.
+- **The body may re-run** (up to 3 attempts) on a transient conflict, so it must
+  be safe to repeat. After 3 losses the caller gets `CONFLICT`.
+- Each concurrent request gets its **own** session — unlike Parse Server's
+  built-in transaction, which is `DatabaseController`-global.
+- Never joined: `_SCHEMA`, `_Idempotency`, `_Hooks`, `_JobStatus`,
+  `_GlobalConfig` — schema creation must survive a rollback.
+- Unfiltered `count()` reads **outside** the transaction (MongoDB refuses
+  `count` inside one).
+
+Without `directAccess`, a `save()` in cloud code becomes an internal HTTP
+request landing in a fresh async context, and writes **outside** the
+transaction. That failure has no symptom.
+
+---
+
+## Optimistic locking
+
+```ts
+@ParseClass('Job')
+class Job extends BaseModel {
+  @ParseVersionField()   // declares the Number field itself — no @ParseField
+  version!: number;
+}
+```
+
+That is the entire feature. No endpoint reads or writes the field:
+
+- every object **read** carries the version it was read at; every `save()` /
+  `saveAll()` asserts it automatically;
+- the adapter moves the assertion into the write's **filter** and `$inc`s the
+  field, so the next reader gets a fresh number;
+- a lost race is refused with `CONFLICT` (5001); a genuinely missing row still
+  reads as missing;
+- creates get version `1` from the adapter — callers never supply one;
+- an object built from a bare id (never read) has nothing to assert and is
+  **not protected**.
+
+```ts
+try {
+  await job.save(null, {useMasterKey: true});
+} catch (error) {
+  if (error instanceof Parse.Error && error.code === CONFLICT) {
+    // Reload, re-apply, retry — or surface CONFLICT_MESSAGE, already
+    // written for the end user.
+  }
+  throw error;
+}
+```
+
+`VERSION_CONFLICT` === `CONFLICT` — a lost lock and a lost transaction race are
+the same event to the person on the screen.
+
+`VersionRegistry`: `fieldFor(className)`, `isVersioned(className)`,
+`classNames()`, `adapterIsInstalled()`, `verify()`.
+
+---
+
+## ACL
+
+```ts
+function implementACL(
+  params: {
+    publicRead?: boolean;
+    publicWrite?: boolean;
+    roleRules?: {role: string; read?: boolean; write?: boolean}[];
+    excludedRoles?: string[];
+    owner?: {user?: string | any; read?: boolean; write?: boolean}[];
+  },
+  existingACL?: Parse.ACL
+): Parse.ACL;
+```
+
+**It takes one params object and RETURNS an ACL.** It does not take the object
+as an argument.
+
+```ts
+// CORRECT
+product.setACL(implementACL({
+  roleRules: [
+    {role: UserRoles.ADMIN, read: true, write: true},
+    {role: UserRoles.EMPLOYEE, read: true},
+  ],
+  publicRead: status === 'active',
+  owner: [{user: userId, read: true, write: true}],
+}));
+
+// WRONG — no such signature, will not compile
+implementACL(product, {readRoles: [...], writeRoles: [...]});
+```
+
+```ts
+function syncImageAcl(parent: Parse.Object, fields: string[], acl?: Parse.ACL): void;
+function cloneAcl(acl: Parse.ACL): Parse.ACL;
+```
+
+`syncImageAcl` copies the parent's ACL onto nested image pointers (single or
+array) so they follow the parent's visibility. Call it **after** setting the
+parent's final ACL and **before** saving. For status-derived visibility set in a
+`beforeSave` trigger, pass `publicRead` into `implementACL` at the call site —
+`syncImageAcl` runs before the trigger.
+
+---
+
+## Middleware
+
+| Export | Purpose |
+|---|---|
+| `validateEntityRoutes` | Resolves `/api/{entity}/{action}` → cloud function; enforces the declared HTTP method (405); applies `rateLimit`; merges GET query into body; rewrites to `/functions/{name}` as POST |
+| `restrictRoutes` | Blocks `/classes`, `/schemas`, `/batch`. Allows `/health`, `/serverInfo`, `/files`, registered prefixes, `/functions`. Master key bypasses |
+| `removeResultMiddleware` | Unwraps Parse's `{result: …}` response |
+| `conditionalJsonMiddleware` | `express.json({limit:'10mb', type:['text/plain']})`, skipping `{mountPath}/files` |
+| `validateFunctionRoutes` | Legacy `/functions/*` validation |
+| `checkRateLimit(req,res,name,cfg)` | In-process token bucket; returns `false` after sending 429 |
+
+**Master key** is read from the `X-Parse-Master-Key` header (preferred) or the
+request body (deprecated, warns once). Rate limiting is **per process** — no
+enforcement across instances.
+
+---
+
+## Indexes
+
+```ts
+function applyAllIndexes(parseServerInstance?: any): Promise<void>;
+const applyUniqueIndexes = applyAllIndexes;   // permanent alias
+function getUniqueIndexes(): UniqueIndexInfo[];
+function getCompoundIndexes(): CompoundIndexInfo[];
+function getFieldIndexes(): FieldIndexInfo[];
+```
+
+Call after `listen()`. Creates, from decorator metadata:
+
+| Source | Index |
+|---|---|
+| `@ParseField({unique: true})` | unique (drops a conflicting non-unique index first) |
+| `@ParseField({index: true \| 1 \| -1})` | B-tree asc/desc |
+| `@ParseField({geo: true})` on GeoPoint | 2dsphere |
+| `@ParseField({ttlSeconds: N})` on Date | TTL |
+| `@ParseClass({compoundIndexes})` | compound |
+
+```ts
+interface CompoundIndex {
+  fields: string[];
+  unique?: boolean;
+  name?: string;
+  sparse?: boolean;
+  partialFilterNulls?: boolean;                       // only index docs where all fields exist
+  fieldTypes?: Record<string, 1|-1|'text'|'2dsphere'|'hashed'>;
+  options?: Record<string, unknown>;                  // e.g. default_language
+}
+```
+
+Existing indexes (codes 85/86) are reported, not treated as errors. If the
+adapter can't be reached it prints the equivalent `db.x.createIndex(...)`
+commands. MongoDB allows only **one text index per collection**.
+
+---
+
+## Schema
+
+```ts
+function createSchemaConfig(options?: SchemaConfigOptions): {...};
+
+interface SchemaConfigOptions {
+  adminRole?: string;               // default 'SuperAdmin'
+  lockSchemas?: boolean;            // default false
+  strict?: boolean;                 // default true
+  recreateModifiedFields?: boolean; // default false — DANGEROUS
+  deleteExtraFields?: boolean;      // default false — DANGEROUS
+  keepUnknownIndexes?: boolean;     // default TRUE — parse-server 8.3+
+}
+```
+
+Builds the `schema` option from every registered `@ParseClass`, plus a `_Role`
+definition locked to `adminRole`.
+
+`keepUnknownIndexes` defaults to **true** because `applyAllIndexes` creates
+indexes out-of-band; parse-server's default (`false`) drops indexes it cannot
+account for during schema migration. **Requires parse-server 8.3+** — it refuses
+to start on an unrecognised option.
+
+---
+
+## Validation
+
+```ts
+function validateObject(object: Parse.Object): {valid: boolean; errors: {field, message, value?}[]};
+function validateOrThrow(object: Parse.Object): void;   // throws Parse.Error VALIDATION_ERROR
+function getValidators(): {className, validator}[];
+function applyMongoValidators(parseServerInstance?: any): Promise<void>;
+```
+
+Checks `required`, `min`/`max`, `minLength`/`maxLength`, `enum`, `pattern` from
+`@ParseField`. `validateOrThrow` is intended for `@BeforeSave`.
+`applyMongoValidators` pushes the same constraints into MongoDB `$jsonSchema`
+validators (`validationLevel: 'moderate'`, `validationAction: 'error'`), so the
+database enforces them even for writes that bypass your code.
+
+---
+
+## Swagger
+
+```ts
+function setupSwagger(app: Express, config: SwaggerConfig, path?: string): void;  // default '/api-docs'
+function generateSwaggerSpec(config: SwaggerConfig): object;
+function getSwaggerJson(config: SwaggerConfig): string;
+
+interface SwaggerConfig {
+  title: string; version: string;
+  description?: string; basePath?: string; host?: string; schemes?: string[];
+}
+```
+
+Models and endpoints are registered automatically from `@ParseClass` /
+`@CloudFunction` — no annotation needed. Endpoints document their real `@Route`
+path. **GET/HEAD emit query `parameters`; everything else emits a JSON
+`requestBody`** (a browser cannot send a GET body). Security schemes derive from
+`requireUser` / `requireMaster` / `requireRoles`.
+
+The spec is always served at `{path}/json`. Without `swagger-ui-express`
+installed, the browser UI is skipped with a warning; the spec still serves.
+
+---
+
+## Utilities
+
+```ts
+function catchError<T>(p: Promise<T>): Promise<[undefined, T] | [Error]>;
+function getUserRoles(user: Parse.User): Promise<string[]>;
+function getUsersRoles(users: Parse.User[]): Promise<Map<string, string[]>>;
+function importFiles(dir: string, options?: {extensions?: string[]; verbose?: boolean}): void;
+function generateRandomPassword(length?, includeNumbers?, includeSymbols?): string;
+function generateRandomString(length?: number): string;
+function generateRandomInteger(length: number): string;
+function sleep(ms: number): Promise<unknown>;
+function formatCount(num: any, locale?: string): string;   // compact notation
+```
+
+**`catchError` is the error convention** — use it for all async work rather than
+`try/catch` around `await`:
+
+```ts
+const [err, saved] = await catchError(product.save(null, {sessionToken}));
+if (err) throw err;
+```
+
+**`importFiles` defaults to `.js` only.** Under ts-node/tsx pass
+`{extensions: ['.js', '.ts']}` or nothing is imported at all. Never point it at
+a tree holding both compiled and source copies — every class registers twice.
+
+`getUsersRoles` costs one query per **role** (capped at 100), not per user.
+
+### Role cache (opt-in, off by default)
+
+```ts
+function configureRoleCache(config: {ttlMs: number; maxUsers?: number} | false): void;
+function invalidateRoles(userId?: string): void;   // no arg = everyone
+function roleCacheEnabled(): boolean;
+function roleCacheStats(): {enabled: boolean; size: number; ttlMs: number | null};
+```
+
+`@CloudFunction({requireRoles})` and `getUserRoles()` each cost a database
+round-trip per call. Role membership rarely changes, so it caches well — but a
+**revoked role keeps working until the entry expires**, which is why nothing
+happens until you opt in:
+
+```ts
+configureRoleCache({ttlMs: 30_000});                    // global
+@CloudFunction({requireRoles: [...], roleCacheMs: 0})   // this endpoint never caches
+```
+
+Call `invalidateRoles(userId)` wherever you grant or revoke, and the TTL becomes
+a backstop for changes made outside your code rather than the primary control.
+`maxUsers` (default 10000) bounds memory; the oldest entry is evicted past it.
+There is no timer — entries expire on read.
+
+---
+
+## Constants
+
+```ts
+enum UserRoles {ADMIN = 'SuperAdmin', EMPLOYEE = 'Employee'}
+function roleKey(role: UserRoles): `role:${UserRoles}`;
+const MAX_QUERY_LIMIT = 10000;
+```
+
+Use `roleKey(UserRoles.ADMIN)` for CLP/ACL keys — never hardcode
+`'role:SuperAdmin'`.
+
+---
+
+## Types
+
+`ClassNameType`, `CLPParamsOption`, `classLevelPermissions`, `ClassAclTemplate`,
+`AclTemplatePermissions`, `ProtectedFields`, `CompoundIndex`, `IndexFieldType`,
+`Fields`, `Indexes`, `SchemaDefinition`, `HttpMethod`, `RouteConfig`,
+`CloudFunctionMetadata`, `SwaggerDocConfig`, `TriggerType`, `TriggerMetadata`,
+`TriggerConfig`, `CronConfig`, `CronJobMetadata`, `RoleString`,
+`ParseClassOptions`, `ParseFieldOptions`, `AllowedFieldType`,
+`SwaggerModelSchema`, `SwaggerPropertySchema`, `SwaggerFunctionSchema`,
+`SchemaConfigOptions`, `TransactionalAdapter`, `VersionedMongoAdapter`,
+`MongoAdapterConstructor`.
+
+```ts
+interface AuthRole  {id: string; name: string}
+interface MultiLangs {ar?: string; en?: string}
+interface Filter    {key: string; value: string|number|string[];
+                     type: 'string'|'min'|'max'|'array'|'text'|'dropdown'}
+```
+
+**Registration hooks** (for custom integrations):
+`onClassRegistered`, `onFieldRegistered`, `onFunctionRegistered`.
+Also exported: `getSchemaDefinition(target)`, `classNames`.
+
+---
+
+## Silent failures
+
+Every item here produces **no error**. This is the list to check when something
+"doesn't work" but nothing is logged.
+
+| Symptom | Cause |
+|---|---|
+| Decorators do nothing / odd behaviour | `experimentalDecorators` not set — TS 5 defaults to standard decorators |
+| Transaction never opens | `@Transactional()` placed **above** `@CloudFunction` instead of below |
+| Writes land outside the transaction | parse-server `directAccess` not `true` |
+| No models, empty schema, no routes | `importFiles` ran over `.ts` sources with the default `['.js']` |
+| Every class registered twice | `importFiles` pointed at a tree with both compiled and source copies |
+| Trigger never fires | Declared on a class without `@ParseClass` — pending triggers are never flushed |
+| Unique indexes vanish after restart | `keepUnknownIndexes` false, or parse-server < 8.3 |
+| Pointer field ignored by `fromParams` | `targetClass` missing, or it is `IMG`/`File` (excluded by design) |
+| Array of pointers stays raw | Array field has no `targetClass` |
+| Direct property access unavailable | Query result not cast to the typed model |
+| Cron jobs never run | `node-cron` not installed — `initialize()` warns and skips |
+| Object not protected by version field | Built from a bare id, never read, so there is nothing to assert |
+
+Three of these now **do** log as of v2.8.0: `@ParseVersionField` with no adapter
+(or on Postgres), and a Parse SDK where `_getSaveJSON` has moved. Check the boot
+output for `[Versioning]`.
+
+---
+
+## Version matrix
+
+| | Requirement |
+|---|---|
+| Node | ≥ 18 for this package; **≥ 20.19** with parse-server 9 |
+| parse-server | ≥ 8.3 (optional peer) — `keepUnknownIndexes`, adapter internals |
+| MongoDB | ≥ 7.0.16 for parse-server 9; **replica set** for transactions |
+| Parse SDK | ≥ 5; verified on 5.3.0 and 8.6.0 |
+| TypeScript | any, with `experimentalDecorators: true` |
+
+**Transactions and `@ParseVersionField` are MongoDB-only.** On Postgres the
+version field is declared but never enforced.