cloesce 0.0.4-unstable.2 → 0.0.4-unstable.4

package/README.md

@@ -17,7 +17,7 @@ Internal documentation going over design decisions and general thoughts for each
 - Create an NPM project and install cloesce
 
 ```sh
-npm i cloesce@0.0.4-unstable.2
+npm i cloesce@0.0.4-unstable.3
 ```
 
 2. TypeScript
@@ -266,7 +266,7 @@ export class Person {
 }
 ```
 
-Data sources are just SQL views and can be invoked in your queries. They are aliased in such a way that its similiar to object properties. The frontend chooses which datasource to use in it's API client. `null` is a valid option, meaning no joins will occur.
+Data sources are just SQL views and can be invoked in your queries. They are aliased in such a way that its similiar to object properties. The frontend chooses which datasource to use in it's API client (all instantiated methods have an implicit DataSource parameter). `null` is a valid option, meaning no joins will occur.
 
 ```ts
 @D1
@@ -288,17 +288,107 @@ export class Person {
   @GET
   static async get(id: number, @Inject env: WranglerEnv): Promise<Person> {
     let records = await env.db
-      .prepare("SELECT * FROM [Person.default] WHERE [Person.id] = ?") // Person.default is the SQL view generated from the IncludeTree
+      .prepare("SELECT * FROM [Person.default] WHERE [id] = ?") // Person.default is the SQL view generated from the IncludeTree
       .bind(id)
       .run();
 
-    let persons = Orm.fromSql(Person, records.results, Person.default);
+    let persons = Orm.mapSql(Person, records.results, Person.default);
     return persons.value[0];
   }
 }
 ```
 
-Note that the `get` code can be simplified using CRUD methods or ORM primitives.
+Note that the `get` code can be simplified using CRUD methods or the ORM primitive `get`.
+
+#### View Aliasing
+
+The generated views will always be aliased so that they can be accessed in an object like notation. For example, given some `Horse` that has a relationship with `Like`:
+
+```ts
+@D1
+export class Horse {
+  @PrimaryKey
+  id: Integer;
+
+  name: string;
+  bio: string | null;
+
+  @OneToMany("horseId1")
+  likes: Like[];
+
+  @DataSource
+  static readonly default: IncludeTree<Horse> = {
+    likes: { horse2: {} },
+  };
+}
+
+@D1
+export class Like {
+  @PrimaryKey
+  id: Integer;
+
+  @ForeignKey(Horse)
+  horseId1: Integer;
+
+  @ForeignKey(Horse)
+  horseId2: Integer;
+
+  @OneToOne("horseId2")
+  horse2: Horse | undefined;
+}
+```
+
+If you wanted to find all horses that like one another, a valid SQL query using the `default` data source would look like:
+
+```sql
+SELECT * FROM [Horse.default] as H1
+WHERE
+    H1.[id] = ?
+    AND EXISTS (
+        SELECT 1
+        FROM [Horse.default] AS H2
+        WHERE H2.[id] = H1.[likes.horse2.id]
+          AND H2.[likes.horse2.id] = H1.[id]
+    );
+```
+
+The actual generated view for `default` looks like:
+
+```sql
+CREATE VIEW IF NOT EXISTS "Horse.default" AS
+SELECT
+    "Horse"."id"          AS "id",
+    "Horse"."name"        AS "name",
+    "Horse"."bio"         AS "bio",
+    "Like"."id"           AS "likes.id",
+    "Like"."horseId1"     AS "likes.horseId1",
+    "Like"."horseId2"     AS "likes.horseId2",
+    "Horse1"."id"         AS "likes.horse2.id",
+    "Horse1"."name"       AS "likes.horse2.name",
+    "Horse1"."bio"        AS "likes.horse2.bio"
+FROM
+    "Horse"
+LEFT JOIN
+    "Like" ON "Horse"."id" = "Like"."horseId1"
+LEFT JOIN
+    "Horse" AS "Horse1" ON "Like"."horseId2" = "Horse1"."id";
+```
+
+#### DataSourceOf<T>
+
+If it is important to determine what data source the frontend called the instantiated method with, the type `DataSourceOf<T>` allows explicit data source parameters:
+
+```ts
+@D1
+class Foo {
+  ...
+
+  @POST
+  bar(ds: DataSourceOf<Foo>) {
+    // ds = "DataSource1" | "DataSource2" | ... | "none"
+  }
+}
+```
 
 ### One to Many
 
@@ -404,10 +494,12 @@ class Horse {
 
 ### CRUD Methods
 
-Generic GET, POST, PATCH (and in a future version, DEL) boilerplate methods do not need to be copied around. Cloesce supports CRUD generation, a syntactic sugar that adds the methods to the compiler output.
+Generic `GET, POST, PATCH` (and in a future version, DEL) boilerplate methods do not need to be copied around. Cloesce supports CRUD generation, a syntactic sugar that adds the methods to the compiler output.
+
+The `SAVE` method is an `upsert`, meaning it both inserts and updates in the same query.
 
 ```ts
-@CRUD(["POST", "GET", "LIST"])
+@CRUD(["SAVE", "GET", "LIST"])
 @D1
 export class CrudHaver {
   @PrimaryKey

package/dist/cli.js

@@ -189,7 +189,7 @@ async function extract(opts) {
         const json = JSON.stringify(ast, null, 4);
         fs.mkdirSync(path.dirname(outPath), { recursive: true });
         fs.writeFileSync(outPath, json);
-        console.log(`CIDL generated successfully at ${outPath}`);
+        console.log(`CIDL extracted to ${outPath}`);
         return { outPath, projectName: cloesceProjectName };
     }
     catch (err) {
@@ -293,10 +293,13 @@ function formatErr(e) {
     const { description, suggestion } = getErrorInfo(e.code);
     const contextLine = e.context ? `Context: ${e.context}\n` : "";
     const snippetLine = e.snippet ? `${e.snippet}\n\n` : "";
-    return `==== CLOESCE ERROR ====
+    return `
+==== CLOESCE ERROR ====
 Error [${ExtractorErrorCode[e.code]}]: ${description}
 Phase: TypeScript IDL Extraction
-${contextLine}${snippetLine}Suggested fix: ${suggestion}`;
+${contextLine}${snippetLine}Suggested fix: ${suggestion}
+
+`;
 }
 run(cmds, process.argv.slice(2)).catch((err) => {
     console.error(err);

package/dist/common.d.ts

@@ -1,21 +1,9 @@
-export type DeepPartial<T> = T extends (infer U)[] ? DeepPartial<U>[] : T extends object ? {
-    [K in keyof T]?: DeepPartial<T[K]>;
-} : T;
-export type Either<L, R> = {
-    ok: false;
-    value: L;
-} | {
-    ok: true;
-    value: R;
-};
-export declare function left<L>(value: L): Either<L, never>;
-export declare function right<R>(value: R): Either<never, R>;
 export declare enum ExtractorErrorCode {
     MissingExport = 0,
     AppMissingDefaultExport = 1,
     UnknownType = 2,
     MultipleGenericType = 3,
-    DataSourceMissingStatic = 4,
+    InvalidDataSourceDefinition = 4,
     InvalidPartialType = 5,
     InvalidIncludeTree = 6,
     InvalidAttributeModifier = 7,
@@ -25,9 +13,10 @@ export declare enum ExtractorErrorCode {
     MissingNavigationPropertyReference = 11,
     MissingManyToManyUniqueId = 12,
     MissingPrimaryKey = 13,
-    MissingWranglerEnv = 14,
-    TooManyWranglerEnvs = 15,
-    MissingFile = 16
+    MissingDatabaseBinding = 14,
+    MissingWranglerEnv = 15,
+    TooManyWranglerEnvs = 16,
+    MissingFile = 17
 }
 export declare function getErrorInfo(code: ExtractorErrorCode): {
     description: string;
@@ -40,6 +29,141 @@ export declare class ExtractorError {
     constructor(code: ExtractorErrorCode);
     addContext(fn: (val: string | undefined) => string | undefined): void;
 }
+type DeepPartialInner<T> = T extends (infer U)[] ? DeepPartialInner<U>[] : T extends object ? {
+    [K in keyof T]?: DeepPartialInner<T[K]>;
+} : T | (null extends T ? null : never);
+/**
+ * Recursively makes all properties of a type optional — including nested objects and arrays.
+ *
+ * Similar to TypeScript's built-in `Partial<T>`, but applies the transformation deeply across
+ * all nested structures. Useful for defining "patch" or "update" objects where only a subset
+ * of properties may be provided.
+ *
+ * **Apart of the Cloesce method grammar**, meaning the type can be apart of method parameters
+ * or return types and the generated workers and client API will act accordingly.
+ *
+ * @template T
+ * The target type to make deeply partial.
+ *
+ * @remarks
+ * - **Objects:** All properties become optional, and their values are recursively wrapped in `DeepPartial`.
+ * - **Arrays:** Arrays are preserved, but their elements are recursively made partial.
+ * - **Scalars:** Primitive values (string, number, boolean, etc.) remain unchanged.
+ * - **Nullable types:** If `null` is assignable to the type, it remains allowed.
+ *
+ * @example
+ * ```ts
+ * class User {
+ *   id: string;
+ *   profile: {
+ *     name: string;
+ *     age: number;
+ *   };
+ *   tags: string[];
+ * }
+ *
+ * // The resulting type:
+ * // {
+ * //   id?: string;
+ * //   profile?: { name?: string; age?: number };
+ * //   tags?: (string | undefined)[];
+ * // }
+ * type PartialUser = DeepPartial<User>;
+ *
+ * const patch: PartialUser = {
+ *   profile: { age: 30 } // ok
+ * };
+ * ```
+ */
+export type DeepPartial<T> = DeepPartialInner<T> & {
+    __brand?: "Partial";
+};
+/**
+ * A functional result type representing a computation that can either succeed (`ok: true`)
+ * or fail (`ok: false`).
+ *
+ * `Either<L, R>` is used throughout Cloesce to return structured success/error values
+ * instead of throwing exceptions.
+ * - When `ok` is `true`, `value` contains the success result of type `R`.
+ * - When `ok` is `false`, `value` contains the error information of type `L`.
+ *
+ * This pattern makes control flow predictable and encourages explicit handling
+ * of failure cases.
+ *
+ * Example:
+ * ```ts
+ * const result: Either<string, number> = compute();
+ *
+ * if (!result.ok) {
+ *   console.error("Failed:", result.value);
+ * } else {
+ *   console.log("Success:", result.value);
+ * }
+ * ```
+ */
+export type Either<L, R> = {
+    ok: false;
+    value: L;
+} | {
+    ok: true;
+    value: R;
+};
+/**
+ * Creates a failed `Either` result.
+ *
+ * Typically used to represent an error condition or unsuccessful operation.
+ *
+ * @param value The error or failure value to wrap.
+ * @returns An `Either` with `ok: false` and the given value.
+ */
+export declare function left<L>(value: L): Either<L, never>;
+/**
+ * Creates a successful `Either` result.
+ *
+ * Typically used to represent a successful operation while maintaining
+ * a consistent `Either`-based return type.
+ *
+ * @param value The success value to wrap.
+ * @returns An `Either` with `ok: true` and the given value.
+ */
+export declare function right<R>(value: R): Either<never, R>;
+/**
+ * Represents the result of an HTTP operation in a monadic style.
+ *
+ * This type provides a uniform way to handle both success and error
+ * outcomes of HTTP requests, similar to a `Result` or `Either` monad.
+ *
+ * It ensures that every HTTP response can be handled in a type-safe,
+ * predictable way without throwing exceptions.
+ *
+ * @template T The type of the successful response data.
+ *
+ * @property {boolean} ok
+ * Indicates whether the HTTP request was successful (`true` for success, `false` for error).
+ * This is analogous to `Response.ok` in the Fetch API.
+ *
+ * @property {number} status
+ * The numeric HTTP status code (e.g., 200, 404, 500).
+ *
+ * @property {T} [data]
+ * The parsed response payload, present only when `ok` is `true`.
+ *
+ * @property {string} [message]
+ * An optional human-readable error message or diagnostic information,
+ * typically provided when `ok` is `false`.
+ *
+ * ## Worker APIs
+ *
+ * HttpResult is a first-class-citizen in the grammar in Cloesce. Methods can return HttpResults
+ * which will be serialized on the client api.
+ *
+ * @example
+ * ```ts
+ *  bar(): HttpResult<Integer> {
+ *    return { ok: false, status: 401, message: "forbidden"}
+ *  }
+ * ```
+ */
 export type HttpResult<T = unknown> = {
     ok: boolean;
     status: number;
@@ -57,18 +181,93 @@ export type KeysOfType<T, U> = {
     [K in keyof T]: T[K] extends U ? (K extends string ? K : never) : never;
 }[keyof T];
 /**
- * A container for middleware. If an instance is exported from `app.cloesce.ts`, it will be used in the
- * appropriate location, with global middleware happening before any routing occurs.
+ * Represents the core middleware container for a Cloesce application.
+ *
+ * The `CloesceApp` class provides scoped middleware registration and
+ * management across three primary levels of execution:
+ *
+ * 1. **Global Middleware** — Executed before any routing or model resolution occurs.
+ * 2. **Model-Level Middleware** — Executed for requests targeting a specific model type.
+ * 3. **Method-Level Middleware** — Executed for requests targeting a specific method on a model.
+ *
+ * When an instance of `CloesceApp` is exported from `app.cloesce.ts`,
+ * it becomes the central container that the Cloesce runtime uses to
+ * assemble and apply middleware in the correct execution order.
+ *
+ * ### Middleware Execution Order
+ * Middleware is executed in FIFO order per scope. For example:
+ * ```ts
+ * app.use(Foo, A);
+ * app.use(Foo, B);
+ * app.use(Foo, C);
+ * // Executed in order: A → B → C
+ * ```
+ *
+ * Each middleware function (`MiddlewareFn`) can optionally short-circuit
+ * execution by returning a result, in which case subsequent middleware
+ * at the same or lower scope will not run.
+ *
+ * ### Example Usage
+ * ```ts
+ * import { app } from "cloesce";
+ *
+ * // Global authentication middleware
+ * app.useGlobal((request, env, di) => {
+ *   // ... authenticate and inject user
+ * });
+ *
+ * // Model-level authorization
+ * app.useModel(User, (user) => user.hasPermissions([UserPermissions.canUseFoo]));
+ *
+ * // Method-level middleware (e.g., CRUD operation)
+ * app.useMethod(Foo, "someMethod", (user) => user.hasPermissions([UserPermissions.canUseFooMethod]));
+ * ```
  */
 export declare class CloesceApp {
     global: MiddlewareFn[];
     model: Map<string, MiddlewareFn[]>;
     method: Map<string, Map<string, MiddlewareFn[]>>;
+    /**
+     * Registers a new global middleware function.
+     *
+     * Global middleware runs before all routing and model resolution.
+     * It is the ideal place to perform tasks such as:
+     * - Authentication (e.g., JWT verification)
+     * - Global request logging
+     * - Dependency injection of shared context
+     *
+     * @param m - The middleware function to register.
+     */
     useGlobal(m: MiddlewareFn): void;
+    /**
+     * Registers middleware for a specific model type.
+     *
+     * Model-level middleware runs after all global middleware,
+     * but before method-specific middleware. This scope allows
+     * logic to be applied consistently across all endpoints
+     * associated with a given model (e.g., authorization).
+     *
+     * @typeParam T - The model type.
+     * @param ctor - The model constructor (used to derive its name).
+     * @param m - The middleware function to register.
+     */
     useModel<T>(ctor: new () => T, m: MiddlewareFn): void;
+    /**
+     * Registers middleware for a specific method on a model.
+     *
+     * Method-level middleware is executed after model middleware,
+     * and before the method implementation itself. It can be used for:
+     * - Fine-grained permission checks
+     * - Custom logging or tracing per endpoint
+     *
+     * @typeParam T - The model type.
+     * @param ctor - The model constructor (used to derive its name).
+     * @param method - The method name on the model.
+     * @param m - The middleware function to register.
+     */
     useMethod<T>(ctor: new () => T, method: KeysOfType<T, (...args: any) => any>, m: MiddlewareFn): void;
 }
-export type CrudKind = "POST" | "GET" | "LIST";
+export type CrudKind = "SAVE" | "GET" | "LIST";
 export type CidlType = "Void" | "Integer" | "Real" | "Text" | "Blob" | "DateIso" | "Boolean" | {
     DataSource: string;
 } | {
@@ -133,6 +332,7 @@ export interface Model {
     navigation_properties: NavigationProperty[];
     methods: Record<string, ModelMethod>;
     data_sources: Record<string, DataSource>;
+    cruds: CrudKind[];
     source_path: string;
 }
 export interface PlainOldObject {
@@ -151,6 +351,7 @@ export interface DataSource {
 export interface WranglerEnv {
     name: string;
     source_path: string;
+    db_binding: string;
 }
 export interface CloesceAst {
     version: string;
@@ -161,4 +362,5 @@ export interface CloesceAst {
     poos: Record<string, PlainOldObject>;
     app_source: string | null;
 }
+export {};
 //# sourceMappingURL=common.d.ts.map

package/dist/common.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"common.d.ts","sourceRoot":"","sources":["../src/common.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"common.d.ts","sourceRoot":"","sources":["../src/common.ts"],"names":[],"mappings":"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"}

package/dist/common.js

@@ -1,16 +1,10 @@
-export function left(value) {
-    return { ok: false, value };
-}
-export function right(value) {
-    return { ok: true, value };
-}
 export var ExtractorErrorCode;
 (function (ExtractorErrorCode) {
     ExtractorErrorCode[ExtractorErrorCode["MissingExport"] = 0] = "MissingExport";
     ExtractorErrorCode[ExtractorErrorCode["AppMissingDefaultExport"] = 1] = "AppMissingDefaultExport";
     ExtractorErrorCode[ExtractorErrorCode["UnknownType"] = 2] = "UnknownType";
     ExtractorErrorCode[ExtractorErrorCode["MultipleGenericType"] = 3] = "MultipleGenericType";
-    ExtractorErrorCode[ExtractorErrorCode["DataSourceMissingStatic"] = 4] = "DataSourceMissingStatic";
+    ExtractorErrorCode[ExtractorErrorCode["InvalidDataSourceDefinition"] = 4] = "InvalidDataSourceDefinition";
     ExtractorErrorCode[ExtractorErrorCode["InvalidPartialType"] = 5] = "InvalidPartialType";
     ExtractorErrorCode[ExtractorErrorCode["InvalidIncludeTree"] = 6] = "InvalidIncludeTree";
     ExtractorErrorCode[ExtractorErrorCode["InvalidAttributeModifier"] = 7] = "InvalidAttributeModifier";
@@ -20,9 +14,10 @@ export var ExtractorErrorCode;
     ExtractorErrorCode[ExtractorErrorCode["MissingNavigationPropertyReference"] = 11] = "MissingNavigationPropertyReference";
     ExtractorErrorCode[ExtractorErrorCode["MissingManyToManyUniqueId"] = 12] = "MissingManyToManyUniqueId";
     ExtractorErrorCode[ExtractorErrorCode["MissingPrimaryKey"] = 13] = "MissingPrimaryKey";
-    ExtractorErrorCode[ExtractorErrorCode["MissingWranglerEnv"] = 14] = "MissingWranglerEnv";
-    ExtractorErrorCode[ExtractorErrorCode["TooManyWranglerEnvs"] = 15] = "TooManyWranglerEnvs";
-    ExtractorErrorCode[ExtractorErrorCode["MissingFile"] = 16] = "MissingFile";
+    ExtractorErrorCode[ExtractorErrorCode["MissingDatabaseBinding"] = 14] = "MissingDatabaseBinding";
+    ExtractorErrorCode[ExtractorErrorCode["MissingWranglerEnv"] = 15] = "MissingWranglerEnv";
+    ExtractorErrorCode[ExtractorErrorCode["TooManyWranglerEnvs"] = 16] = "TooManyWranglerEnvs";
+    ExtractorErrorCode[ExtractorErrorCode["MissingFile"] = 17] = "MissingFile";
 })(ExtractorErrorCode || (ExtractorErrorCode = {}));
 const errorInfoMap = {
     [ExtractorErrorCode.MissingExport]: {
@@ -45,9 +40,9 @@ const errorInfoMap = {
         description: "Cloesce does not yet support types with multiple generics",
         suggestion: "Simplify your type to use only a single generic parameter, ie Foo<T>",
     },
-    [ExtractorErrorCode.DataSourceMissingStatic]: {
-        description: "Data Sources must be declared as static",
-        suggestion: "Declare your data source as `static readonly`",
+    [ExtractorErrorCode.InvalidDataSourceDefinition]: {
+        description: "Data Sources must be explicitly typed as a static Include Tree",
+        suggestion: "Declare your data source as `static readonly _: IncludeTree<Model>`",
     },
     [ExtractorErrorCode.InvalidIncludeTree]: {
         description: "Invalid Include Tree",
@@ -81,6 +76,10 @@ const errorInfoMap = {
         description: "Missing primary key on a model",
         suggestion: "Add a primary key field to your model (e.g., `id: number`)",
     },
+    [ExtractorErrorCode.MissingDatabaseBinding]: {
+        description: "Missing a database binding in the WranglerEnv definition",
+        suggestion: "Add a `D1Database` to your WranglerEnv",
+    },
     [ExtractorErrorCode.MissingWranglerEnv]: {
         description: "Missing a wrangler environment definition in the project",
         suggestion: "Add a @WranglerEnv class in your project.",
@@ -109,16 +108,101 @@ export class ExtractorError {
     }
 }
 /**
- * A container for middleware. If an instance is exported from `app.cloesce.ts`, it will be used in the
- * appropriate location, with global middleware happening before any routing occurs.
+ * Creates a failed `Either` result.
+ *
+ * Typically used to represent an error condition or unsuccessful operation.
+ *
+ * @param value The error or failure value to wrap.
+ * @returns An `Either` with `ok: false` and the given value.
+ */
+export function left(value) {
+    return { ok: false, value };
+}
+/**
+ * Creates a successful `Either` result.
+ *
+ * Typically used to represent a successful operation while maintaining
+ * a consistent `Either`-based return type.
+ *
+ * @param value The success value to wrap.
+ * @returns An `Either` with `ok: true` and the given value.
+ */
+export function right(value) {
+    return { ok: true, value };
+}
+/**
+ * Represents the core middleware container for a Cloesce application.
+ *
+ * The `CloesceApp` class provides scoped middleware registration and
+ * management across three primary levels of execution:
+ *
+ * 1. **Global Middleware** — Executed before any routing or model resolution occurs.
+ * 2. **Model-Level Middleware** — Executed for requests targeting a specific model type.
+ * 3. **Method-Level Middleware** — Executed for requests targeting a specific method on a model.
+ *
+ * When an instance of `CloesceApp` is exported from `app.cloesce.ts`,
+ * it becomes the central container that the Cloesce runtime uses to
+ * assemble and apply middleware in the correct execution order.
+ *
+ * ### Middleware Execution Order
+ * Middleware is executed in FIFO order per scope. For example:
+ * ```ts
+ * app.use(Foo, A);
+ * app.use(Foo, B);
+ * app.use(Foo, C);
+ * // Executed in order: A → B → C
+ * ```
+ *
+ * Each middleware function (`MiddlewareFn`) can optionally short-circuit
+ * execution by returning a result, in which case subsequent middleware
+ * at the same or lower scope will not run.
+ *
+ * ### Example Usage
+ * ```ts
+ * import { app } from "cloesce";
+ *
+ * // Global authentication middleware
+ * app.useGlobal((request, env, di) => {
+ *   // ... authenticate and inject user
+ * });
+ *
+ * // Model-level authorization
+ * app.useModel(User, (user) => user.hasPermissions([UserPermissions.canUseFoo]));
+ *
+ * // Method-level middleware (e.g., CRUD operation)
+ * app.useMethod(Foo, "someMethod", (user) => user.hasPermissions([UserPermissions.canUseFooMethod]));
+ * ```
  */
 export class CloesceApp {
     global = [];
     model = new Map();
     method = new Map();
+    /**
+     * Registers a new global middleware function.
+     *
+     * Global middleware runs before all routing and model resolution.
+     * It is the ideal place to perform tasks such as:
+     * - Authentication (e.g., JWT verification)
+     * - Global request logging
+     * - Dependency injection of shared context
+     *
+     * @param m - The middleware function to register.
+     */
     useGlobal(m) {
         this.global.push(m);
     }
+    /**
+     * Registers middleware for a specific model type.
+     *
+     * Model-level middleware runs after all global middleware,
+     * but before method-specific middleware. This scope allows
+     * logic to be applied consistently across all endpoints
+     * associated with a given model (e.g., authorization).
+     *
+     * @typeParam T - The model type.
+     * @param ctor - The model constructor (used to derive its name).
+     * @param m - The middleware function to register.
+     */
     useModel(ctor, m) {
         if (this.model.has(ctor.name)) {
             this.model.get(ctor.name).push(m);
@@ -127,6 +211,19 @@ export class CloesceApp {
             this.model.set(ctor.name, [m]);
         }
     }
+    /**
+     * Registers middleware for a specific method on a model.
+     *
+     * Method-level middleware is executed after model middleware,
+     * and before the method implementation itself. It can be used for:
+     * - Fine-grained permission checks
+     * - Custom logging or tracing per endpoint
+     *
+     * @typeParam T - The model type.
+     * @param ctor - The model constructor (used to derive its name).
+     * @param method - The method name on the model.
+     * @param m - The middleware function to register.
+     */
     useMethod(ctor, method, m) {
         if (!this.method.has(ctor.name)) {
             this.method.set(ctor.name, new Map());