@atscript/moost-db 0.1.39 → 0.1.41

package/dist/index.d.cts

@@ -0,0 +1,204 @@
+import * as _uniqu_url0 from "@uniqu/url";
+import * as _atscript_db0 from "@atscript/db";
+import { AtscriptDbReadable, AtscriptDbTable, FilterExpr, Uniquery, UniqueryControls } from "@atscript/db";
+import * as _atscript_typescript_utils0 from "@atscript/typescript/utils";
+import { TAtscriptAnnotatedType, TAtscriptDataType, Validator } from "@atscript/typescript/utils";
+import { HttpError } from "@moostjs/event-http";
+import * as moost from "moost";
+import { Moost, TConsoleBase } from "moost";
+
+//#region src/as-db-readable.controller.d.ts
+/**
+ * Read-only database controller for Moost that works with any `AtscriptDbReadable`
+ * (tables or views). Provides query, pages, getOne, and meta endpoints.
+ *
+ * For write operations (insert, replace, update, delete), use {@link AsDbController}.
+ * For views, use {@link AsDbViewController}.
+ */
+declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscriptAnnotatedType, DataType = TAtscriptDataType<T>> {
+  /** Reference to the underlying readable (table or view). */
+  protected readable: AtscriptDbReadable<T>;
+  /** Application-scoped logger. */
+  protected logger: TConsoleBase;
+  /** Cached serialized type definition (static, computed once). */
+  private _serializedType;
+  /** Cached search index list (static, computed once). */
+  private _searchIndexes;
+  constructor(readable: AtscriptDbReadable<T>, app: Moost);
+  /**
+   * One-time initialization hook. Override to seed data, register watchers, etc.
+   */
+  protected init(): void | Promise<void>;
+  private _queryControlsValidator?;
+  private _pagesControlsValidator?;
+  private _getOneControlsValidator?;
+  protected get queryControlsValidator(): Validator<any, unknown>;
+  protected get pagesControlsValidator(): Validator<any, unknown>;
+  protected get getOneControlsValidator(): Validator<any, unknown>;
+  protected validateControls(controls: Record<string, unknown>, type: "query" | "pages" | "getOne"): string | undefined;
+  protected validateInsights(insights: Map<string, unknown>): string | undefined;
+  protected validateParsed(parsed: Uniquery, type: "query" | "pages" | "getOne"): HttpError | undefined;
+  /**
+   * Compute an embedding vector from a search term.
+   * Override in subclass to integrate with your embedding provider (OpenAI, etc.).
+   * Called when `$vector` is present in query controls.
+   */
+  protected computeEmbedding(_search: string, _fieldName?: string): Promise<number[]>;
+  /**
+   * Transform filter before querying. Override to add tenant filtering, etc.
+   */
+  protected transformFilter(filter: FilterExpr): FilterExpr;
+  /**
+   * Transform projection before querying.
+   */
+  protected transformProjection(projection?: UniqueryControls["$select"]): UniqueryControls["$select"] | undefined;
+  protected parseQueryString(url: string): _uniqu_url0.UrlQuery;
+  protected returnOne(result: Promise<DataType | null>): Promise<DataType | HttpError>;
+  /**
+   * Extracts a composite identifier object from query params.
+   * Tries composite primary key first, then compound unique indexes.
+   */
+  protected extractCompositeId(query: Record<string, string>): Record<string, unknown> | HttpError;
+  /**
+   * **GET /query** — returns an array of records or a count.
+   */
+  query(url: string): Promise<DataType[] | number | HttpError>;
+  /**
+   * **GET /pages** — returns paginated records with metadata.
+   */
+  pages(url: string): Promise<{
+    data: DataType[];
+    page: number;
+    itemsPerPage: number;
+    pages: number;
+    count: number;
+  } | HttpError>;
+  /**
+   * **GET /one/:id** — retrieves a single record by ID or unique property.
+   */
+  getOne(id: string, url: string): Promise<DataType | HttpError>;
+  /**
+   * **GET /one?field1=val1&field2=val2** — retrieves a single record by composite key
+   * (composite primary key or compound unique index).
+   */
+  getOneComposite(query: Record<string, string>, url: string): Promise<DataType | HttpError>;
+  /**
+   * **GET /meta** — returns table/view metadata for UI.
+   */
+  meta(): {
+    searchable: boolean;
+    vectorSearchable: boolean;
+    searchIndexes: _atscript_db0.TSearchIndexInfo[];
+    type: _atscript_typescript_utils0.TSerializedAnnotatedType;
+  };
+}
+//#endregion
+//#region src/as-db.controller.d.ts
+/**
+ * Full CRUD database controller for Moost that works with any `AtscriptDbTable` +
+ * `BaseDbAdapter`. Extends {@link AsDbReadableController} with write operations.
+ *
+ * Subclass and provide the table via DI:
+ * ```ts
+ * ‎@TableController(usersTable)
+ * export class UsersController extends AsDbController<typeof UserModel> {}
+ * ```
+ */
+declare class AsDbController<T extends TAtscriptAnnotatedType = TAtscriptAnnotatedType, DataType = TAtscriptDataType<T>> extends AsDbReadableController<T, DataType> {
+  /** Reference to the underlying table (typed for write access). */
+  protected get table(): AtscriptDbTable<T>;
+  constructor(table: AtscriptDbTable<T>, app: Moost);
+  /**
+   * Intercepts write operations. Return `undefined` to abort.
+   */
+  protected onWrite(action: "insert" | "insertMany" | "replace" | "replaceMany" | "update" | "updateMany", data: unknown): unknown;
+  /**
+   * Intercepts delete operations. Return `undefined` to abort.
+   */
+  protected onRemove(id: unknown): unknown;
+  /**
+   * **POST /** — inserts one or many records.
+   */
+  insert(payload: unknown): Promise<unknown>;
+  /**
+   * **PUT /** — fully replaces one or many records matched by primary key.
+   */
+  replace(payload: unknown): Promise<unknown>;
+  /**
+   * **PATCH /** — partially updates one or many records matched by primary key.
+   */
+  update(payload: unknown): Promise<unknown>;
+  /**
+   * **DELETE /:id** — removes a single record by primary key.
+   */
+  remove(id: string): Promise<unknown>;
+  /**
+   * **DELETE /?field1=val1&field2=val2** — removes a record by composite key
+   * (composite primary key or compound unique index).
+   */
+  removeComposite(query: Record<string, string>): Promise<unknown>;
+}
+//#endregion
+//#region src/decorators.d.ts
+/**
+ * DI token under which the {@link AtscriptDbReadable} instance
+ * is exposed to the readable controller's constructor via `@Inject`.
+ */
+declare const READABLE_DEF = "__atscript_db_readable_def";
+/**
+ * DI token under which the {@link AtscriptDbTable} instance
+ * is exposed to the controller's constructor via `@Inject`.
+ * Points to the same token as READABLE_DEF for backward compatibility.
+ */
+declare const TABLE_DEF = "__atscript_db_readable_def";
+/**
+ * Combines the boilerplate needed to turn an {@link AsDbController}
+ * subclass into a fully wired HTTP controller for a given `@db.table` model.
+ *
+ * Internally applies three decorators:
+ * 1. **Provide** — registers the table instance under {@link TABLE_DEF}.
+ * 2. **Controller** — registers the class as a Moost HTTP controller
+ *    with an optional route prefix. Defaults to `table.tableName`.
+ * 3. **Inherit** — copies metadata (routes, guards, etc.) from the
+ *    parent class so they stay active in the derived controller.
+ *
+ * @param table  The {@link AtscriptDbTable} instance for this controller.
+ * @param prefix Optional route prefix. Defaults to `table.tableName`.
+ *
+ * @example
+ * ```ts
+ * ‎@TableController(usersTable)
+ * export class UsersController extends AsDbController<typeof UserModel> {}
+ * ```
+ */
+declare const TableController: (table: AtscriptDbTable, prefix?: string) => MethodDecorator & ClassDecorator & ParameterDecorator & PropertyDecorator;
+/**
+ * Combines the boilerplate needed to turn an {@link AsDbReadableController}
+ * subclass into a fully wired HTTP controller for a given `@db.view` or `@db.table` model.
+ *
+ * @param readable  The {@link AtscriptDbReadable} instance (table or view).
+ * @param prefix    Optional route prefix. Defaults to `readable.tableName`.
+ *
+ * @example
+ * ```ts
+ * ‎@ReadableController(activeTasksView)
+ * export class ActiveTasksController extends AsDbReadableController<typeof ActiveTasks> {}
+ * ```
+ */
+declare const ReadableController: (readable: AtscriptDbReadable, prefix?: string) => MethodDecorator & ClassDecorator & ParameterDecorator & PropertyDecorator;
+/**
+ * Alias for {@link ReadableController} — use with view-backed controllers.
+ *
+ * @example
+ * ```ts
+ * ‎@ViewController(activeTasksView)
+ * export class ActiveTasksController extends AsDbReadableController<typeof ActiveTasks> {}
+ * ```
+ */
+declare const ViewController: (readable: AtscriptDbReadable, prefix?: string) => MethodDecorator & ClassDecorator & ParameterDecorator & PropertyDecorator;
+//#endregion
+//#region src/validation-interceptor.d.ts
+declare const validationErrorTransform: () => moost.TInterceptorDef;
+declare const UseValidationErrorTransform: () => ClassDecorator & MethodDecorator;
+//#endregion
+export { AsDbController, AsDbReadableController, READABLE_DEF, ReadableController, TABLE_DEF, TableController, UseValidationErrorTransform, ViewController, validationErrorTransform };

package/dist/index.d.mts

@@ -0,0 +1,204 @@
+import * as _atscript_typescript_utils0 from "@atscript/typescript/utils";
+import { TAtscriptAnnotatedType, TAtscriptDataType, Validator } from "@atscript/typescript/utils";
+import { HttpError } from "@moostjs/event-http";
+import * as moost from "moost";
+import { Moost, TConsoleBase } from "moost";
+import * as _uniqu_url0 from "@uniqu/url";
+import * as _atscript_db0 from "@atscript/db";
+import { AtscriptDbReadable, AtscriptDbTable, FilterExpr, Uniquery, UniqueryControls } from "@atscript/db";
+
+//#region src/as-db-readable.controller.d.ts
+/**
+ * Read-only database controller for Moost that works with any `AtscriptDbReadable`
+ * (tables or views). Provides query, pages, getOne, and meta endpoints.
+ *
+ * For write operations (insert, replace, update, delete), use {@link AsDbController}.
+ * For views, use {@link AsDbViewController}.
+ */
+declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscriptAnnotatedType, DataType = TAtscriptDataType<T>> {
+  /** Reference to the underlying readable (table or view). */
+  protected readable: AtscriptDbReadable<T>;
+  /** Application-scoped logger. */
+  protected logger: TConsoleBase;
+  /** Cached serialized type definition (static, computed once). */
+  private _serializedType;
+  /** Cached search index list (static, computed once). */
+  private _searchIndexes;
+  constructor(readable: AtscriptDbReadable<T>, app: Moost);
+  /**
+   * One-time initialization hook. Override to seed data, register watchers, etc.
+   */
+  protected init(): void | Promise<void>;
+  private _queryControlsValidator?;
+  private _pagesControlsValidator?;
+  private _getOneControlsValidator?;
+  protected get queryControlsValidator(): Validator<any, unknown>;
+  protected get pagesControlsValidator(): Validator<any, unknown>;
+  protected get getOneControlsValidator(): Validator<any, unknown>;
+  protected validateControls(controls: Record<string, unknown>, type: "query" | "pages" | "getOne"): string | undefined;
+  protected validateInsights(insights: Map<string, unknown>): string | undefined;
+  protected validateParsed(parsed: Uniquery, type: "query" | "pages" | "getOne"): HttpError | undefined;
+  /**
+   * Compute an embedding vector from a search term.
+   * Override in subclass to integrate with your embedding provider (OpenAI, etc.).
+   * Called when `$vector` is present in query controls.
+   */
+  protected computeEmbedding(_search: string, _fieldName?: string): Promise<number[]>;
+  /**
+   * Transform filter before querying. Override to add tenant filtering, etc.
+   */
+  protected transformFilter(filter: FilterExpr): FilterExpr;
+  /**
+   * Transform projection before querying.
+   */
+  protected transformProjection(projection?: UniqueryControls["$select"]): UniqueryControls["$select"] | undefined;
+  protected parseQueryString(url: string): _uniqu_url0.UrlQuery;
+  protected returnOne(result: Promise<DataType | null>): Promise<DataType | HttpError>;
+  /**
+   * Extracts a composite identifier object from query params.
+   * Tries composite primary key first, then compound unique indexes.
+   */
+  protected extractCompositeId(query: Record<string, string>): Record<string, unknown> | HttpError;
+  /**
+   * **GET /query** — returns an array of records or a count.
+   */
+  query(url: string): Promise<DataType[] | number | HttpError>;
+  /**
+   * **GET /pages** — returns paginated records with metadata.
+   */
+  pages(url: string): Promise<{
+    data: DataType[];
+    page: number;
+    itemsPerPage: number;
+    pages: number;
+    count: number;
+  } | HttpError>;
+  /**
+   * **GET /one/:id** — retrieves a single record by ID or unique property.
+   */
+  getOne(id: string, url: string): Promise<DataType | HttpError>;
+  /**
+   * **GET /one?field1=val1&field2=val2** — retrieves a single record by composite key
+   * (composite primary key or compound unique index).
+   */
+  getOneComposite(query: Record<string, string>, url: string): Promise<DataType | HttpError>;
+  /**
+   * **GET /meta** — returns table/view metadata for UI.
+   */
+  meta(): {
+    searchable: boolean;
+    vectorSearchable: boolean;
+    searchIndexes: _atscript_db0.TSearchIndexInfo[];
+    type: _atscript_typescript_utils0.TSerializedAnnotatedType;
+  };
+}
+//#endregion
+//#region src/as-db.controller.d.ts
+/**
+ * Full CRUD database controller for Moost that works with any `AtscriptDbTable` +
+ * `BaseDbAdapter`. Extends {@link AsDbReadableController} with write operations.
+ *
+ * Subclass and provide the table via DI:
+ * ```ts
+ * ‎@TableController(usersTable)
+ * export class UsersController extends AsDbController<typeof UserModel> {}
+ * ```
+ */
+declare class AsDbController<T extends TAtscriptAnnotatedType = TAtscriptAnnotatedType, DataType = TAtscriptDataType<T>> extends AsDbReadableController<T, DataType> {
+  /** Reference to the underlying table (typed for write access). */
+  protected get table(): AtscriptDbTable<T>;
+  constructor(table: AtscriptDbTable<T>, app: Moost);
+  /**
+   * Intercepts write operations. Return `undefined` to abort.
+   */
+  protected onWrite(action: "insert" | "insertMany" | "replace" | "replaceMany" | "update" | "updateMany", data: unknown): unknown;
+  /**
+   * Intercepts delete operations. Return `undefined` to abort.
+   */
+  protected onRemove(id: unknown): unknown;
+  /**
+   * **POST /** — inserts one or many records.
+   */
+  insert(payload: unknown): Promise<unknown>;
+  /**
+   * **PUT /** — fully replaces one or many records matched by primary key.
+   */
+  replace(payload: unknown): Promise<unknown>;
+  /**
+   * **PATCH /** — partially updates one or many records matched by primary key.
+   */
+  update(payload: unknown): Promise<unknown>;
+  /**
+   * **DELETE /:id** — removes a single record by primary key.
+   */
+  remove(id: string): Promise<unknown>;
+  /**
+   * **DELETE /?field1=val1&field2=val2** — removes a record by composite key
+   * (composite primary key or compound unique index).
+   */
+  removeComposite(query: Record<string, string>): Promise<unknown>;
+}
+//#endregion
+//#region src/decorators.d.ts
+/**
+ * DI token under which the {@link AtscriptDbReadable} instance
+ * is exposed to the readable controller's constructor via `@Inject`.
+ */
+declare const READABLE_DEF = "__atscript_db_readable_def";
+/**
+ * DI token under which the {@link AtscriptDbTable} instance
+ * is exposed to the controller's constructor via `@Inject`.
+ * Points to the same token as READABLE_DEF for backward compatibility.
+ */
+declare const TABLE_DEF = "__atscript_db_readable_def";
+/**
+ * Combines the boilerplate needed to turn an {@link AsDbController}
+ * subclass into a fully wired HTTP controller for a given `@db.table` model.
+ *
+ * Internally applies three decorators:
+ * 1. **Provide** — registers the table instance under {@link TABLE_DEF}.
+ * 2. **Controller** — registers the class as a Moost HTTP controller
+ *    with an optional route prefix. Defaults to `table.tableName`.
+ * 3. **Inherit** — copies metadata (routes, guards, etc.) from the
+ *    parent class so they stay active in the derived controller.
+ *
+ * @param table  The {@link AtscriptDbTable} instance for this controller.
+ * @param prefix Optional route prefix. Defaults to `table.tableName`.
+ *
+ * @example
+ * ```ts
+ * ‎@TableController(usersTable)
+ * export class UsersController extends AsDbController<typeof UserModel> {}
+ * ```
+ */
+declare const TableController: (table: AtscriptDbTable, prefix?: string) => MethodDecorator & ClassDecorator & ParameterDecorator & PropertyDecorator;
+/**
+ * Combines the boilerplate needed to turn an {@link AsDbReadableController}
+ * subclass into a fully wired HTTP controller for a given `@db.view` or `@db.table` model.
+ *
+ * @param readable  The {@link AtscriptDbReadable} instance (table or view).
+ * @param prefix    Optional route prefix. Defaults to `readable.tableName`.
+ *
+ * @example
+ * ```ts
+ * ‎@ReadableController(activeTasksView)
+ * export class ActiveTasksController extends AsDbReadableController<typeof ActiveTasks> {}
+ * ```
+ */
+declare const ReadableController: (readable: AtscriptDbReadable, prefix?: string) => MethodDecorator & ClassDecorator & ParameterDecorator & PropertyDecorator;
+/**
+ * Alias for {@link ReadableController} — use with view-backed controllers.
+ *
+ * @example
+ * ```ts
+ * ‎@ViewController(activeTasksView)
+ * export class ActiveTasksController extends AsDbReadableController<typeof ActiveTasks> {}
+ * ```
+ */
+declare const ViewController: (readable: AtscriptDbReadable, prefix?: string) => MethodDecorator & ClassDecorator & ParameterDecorator & PropertyDecorator;
+//#endregion
+//#region src/validation-interceptor.d.ts
+declare const validationErrorTransform: () => moost.TInterceptorDef;
+declare const UseValidationErrorTransform: () => ClassDecorator & MethodDecorator;
+//#endregion
+export { AsDbController, AsDbReadableController, READABLE_DEF, ReadableController, TABLE_DEF, TableController, UseValidationErrorTransform, ViewController, validationErrorTransform };