@atscript/moost-db 0.1.149 → 0.1.150

package/dist/index.d.cts

@@ -6,6 +6,12 @@ import { Mate, Moost, TConsoleBase, TMateParamMeta, TMoostMetadata } from "moost
 import { parseUrl } from "@uniqu/url";
 import { EventContext } from "@wooksjs/event-core";
 
+//#region src/http-path.d.ts
+/** The published path of every model one app serves (`null`: mounted, published nowhere). */
+interface THttpPathScope {
+  readonly paths: ReadonlyMap<TAtscriptAnnotatedType, string | null>;
+}
+//#endregion
 //#region src/as-readable.controller.d.ts
 /**
  * Endpoint a {@link AsReadableController.prepareRequest} call serves. `/one`
@@ -89,8 +95,9 @@ interface TDbParsedRequest {
  * Abstract base class for read-only HTTP controllers over an Atscript interface.
  *
  * Shared responsibilities (implemented here):
- * - Stamps `@db.http.path` on the bound interface's metadata at registration
- *   with the final public path (leading slash + Moost `globalPrefix`).
+ * - Publishes `@db.http.path` (the model's value-help URL) per app after
+ *   `app.init()`, derived from each controller's own bound route (see
+ *   `docs/http/index.md`); the constructor only records which model it serves.
  * - Lazily serializes the bound interface for the `/meta` endpoint
  *   (see {@link getSerializeOptions}).
  * - Provides DTO-backed validators for the Uniquery controls DTOs and the
@@ -120,23 +127,44 @@ declare abstract class AsReadableController<T extends TAtscriptAnnotatedType = T
   protected app: Moost;
   /** Cached serialized type definition (lazy, computed on first access). */
   private _serializedType?;
+  /** App scope every cache below was built for; a different scope drops them all ({@link enterScope}). */
+  private _cacheScope?;
+  /** Scope of the synchronous build in flight — instance-local, cleared in `finally`. */
+  protected _buildScope?: THttpPathScope;
   /** Cached full meta response (computed lazily on first meta() call). */
   private _metaResponse?;
   /** {@link metaCacheKey} the cached response was built for. */
   private _metaResponseKey?;
   /** Cached serialized form schemas keyed by `FormType.name` — populated lazily by {@link metaForm}. */
   private _formSchemas;
-  constructor(boundType: T, controllerName: string, app: Moost, kindTag?: string);
+  /**
+   * @param opts.canonical Multi-mount models only: marks (`true`) or excludes
+   *   (`false`) this controller as the model's published value-help route
+   *   (since 0.1.150). Decorator-bound controllers use the decorator option.
+   */
+  constructor(boundType: T, controllerName: string, app: Moost, kindTag?: string, opts?: {
+    canonical?: boolean;
+  });
   /**
    * Subclass contract: return `true` if `path` addresses a field that exists
    * AND is visible to the current request — see the DB controller's override
    * for the full list of positions that consult it.
    */
   protected abstract hasField(path: string): boolean;
-  /** Sets @db.http.path on the type metadata from the controller's computed prefix. */
-  private _resolveHttpPath;
-  /** Lazily serializes the bound type (after all controllers have set @db.http.path). */
+  /**
+   * The app of the current event, through DI — never the one this
+   * (singleton) instance was constructed in, which may be gone (a re-booted
+   * app, a hot reload). Outside an event it is {@link app}.
+   *
+   * @since 0.1.150
+   */
+  protected currentApp(): Promise<Moost>;
+  /** Lazily serializes the bound type (dropped with the other caches on a scope change). */
   protected getSerializedType(): TSerializedAnnotatedType;
+  /** Drops every scope-dependent cache when `scope` is not the one they were built for. */
+  private enterScope;
+  /** Runs a synchronous build with `scope`'s `db.http.path` overrides applied. */
+  private buildScoped;
   /**
    * Serializes a type for the meta surfaces (`/meta`, `/meta/form/:name`)
    * with {@link getSerializeOptions}, then re-points every reference chain to
@@ -145,6 +173,11 @@ declare abstract class AsReadableController<T extends TAtscriptAnnotatedType = T
    * serialize exactly as before.
    */
   protected serializeForMeta(type: TAtscriptAnnotatedType): TSerializedAnnotatedType;
+  /**
+   * {@link getSerializeOptions} plus the current build's per-app `db.http.path`
+   * overrides (a subclass's own `annotationOverrides` entry wins for the same key).
+   */
+  private _effectiveSerializeOptions;
   /**
    * One-time initialization hook. Override to seed data, register watchers, etc.
    */
@@ -282,6 +315,14 @@ declare abstract class AsReadableController<T extends TAtscriptAnnotatedType = T
    * response by principal.
    */
   meta(): Promise<TMetaResponse>;
+  /**
+   * The root of a controller's own `/meta` carries its own mount as
+   * `db.http.path` (a secondary mount answers with its own route; references to
+   * the model elsewhere carry the canonical one). Left alone for parametric
+   * mounts and when the serialize options strip the key. Never mutates the
+   * cached envelope.
+   */
+  private _withOwnHttpPath;
   /**
    * The `/meta` payload for the current request — the cached envelope
    * through {@link applyMetaOverlay} — WITHOUT the `/meta` route's
@@ -1302,6 +1343,11 @@ declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscrip
   private _searchIndexFieldPaths;
   /** `@db.index.geo` indexes — their fields carry physical names, mapped back to logical paths. */
   private _geoIndexFieldPaths;
+  /**
+   * The index visibility gate applies: {@link hasField} is overridden, or the
+   * model has `@db.writeOnly` fields (never readable through a search hit).
+   */
+  private get _indexGateActive();
   /** Every path `entry` reads is visible to this request. */
   private _indexVisible;
   /**
@@ -1668,6 +1714,14 @@ declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscrip
    * nothing can apply is ignored. Resolvers (query targets, `resolveQuery`)
    * refuse it — a subclass override that applies the term must return a new
    * filter object.
+   *
+   * A string field matches when the term is a substring of its text; an
+   * INTEGER field (`number.int` and its sizes, `@expect.int`,
+   * `@db.default.increment`) when it is a substring of the number's decimal
+   * text — `2946` finds `29461277` (since 0.1.150). To search numeric IDs
+   * declare `@db.column.searchable` (fallback) or `@db.index.fulltext`
+   * (native, exact number) on the integer field — override this hook only for
+   * search rules the annotations cannot express.
    */
   protected applySearchFallback(filter: FilterExpr | undefined, controls: Record<string, unknown>): FilterExpr | undefined;
   /**
@@ -1690,6 +1744,21 @@ declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscrip
    * the same shape as the one this whole path exists to remove.
    */
   private _aggregateControls;
+  /**
+   * `$count` of a native text / vector search: the adapter's own count, so it
+   * agrees with `/query` and `/pages`. A text search counts every match (the
+   * single returned row is discarded); a vector search counts the nearest
+   * neighbours up to `$limit` (default 1000), as `/query` returns them.
+   */
+  private _countSearched;
+  /**
+   * The controls a native search / vector read is run with: the request's
+   * sealed controls (so every search control — `$fuzzy`, … — reaches the
+   * adapter) plus the select, the threshold and the caller's paging. ONE
+   * builder for `/query`, `/pages` and the native `$count`, so they can't
+   * disagree about what a search matches.
+   */
+  private _searchReadControls;
   private _resolveReadStrategy;
   /**
    * Post-read row decoration hook. Not implemented by
@@ -1738,12 +1807,6 @@ declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscrip
    * when implemented.
    */
   private _augmentAndDecorate;
-  /**
-   * The app of the current event, through DI — never the one this
-   * (singleton) instance was constructed in, which may be gone (a re-booted
-   * app, a hot reload).
-   */
-  private _currentApp;
   /** The class's `@DbActionsFrom` delegations, validated on first use (per app). */
   private _delegations;
   /**
@@ -2212,7 +2275,8 @@ declare class AsDbController<T extends TAtscriptAnnotatedType = TAtscriptAnnotat
    * Bulk auto-lift: each item carries its own `version` → `$cas`.
    * NOTE: per-item conflict disambiguation in the response body is deferred
    * (§6.4) — the aggregate `{ matchedCount, modifiedCount }` surfaces partial
-   * application; callers can detect mismatches via `modifiedCount < N`.
+   * application; callers can detect mismatches via `matchedCount < N` (`modifiedCount` may
+   * be lower for unchanged values, e.g. a version-exempt patch on MySQL / Mongo).
    */
   private _resolveBulkCas;
   /**
@@ -2344,7 +2408,9 @@ declare abstract class AsValueHelpController<T extends TAtscriptAnnotatedType =
   protected readonly searchableFields: readonly string[];
   /** The `@meta.id` field name on the bound interface, if any. */
   protected readonly primaryKey: string | undefined;
-  constructor(boundType: T, controllerName: string, app: Moost);
+  constructor(boundType: T, controllerName: string, app: Moost, opts?: {
+    canonical?: boolean;
+  });
   /** Executes a value-help query against the backing source. */
   protected abstract query(controls: ValueHelpQuery<DataType>): Promise<{
     data: DataType[];
@@ -2482,7 +2548,9 @@ declare abstract class AsValueHelpController<T extends TAtscriptAnnotatedType =
 declare class AsJsonValueHelpController<T extends TAtscriptAnnotatedType = TAtscriptAnnotatedType, DataType = TAtscriptDataType<T>> extends AsValueHelpController<T, DataType> {
   protected rows: DataType[];
   private _pkIndex?;
-  constructor(boundType: T, rows: DataType[], app: Moost, controllerName?: string);
+  constructor(boundType: T, rows: DataType[], app: Moost, controllerName?: string, opts?: {
+    canonical?: boolean;
+  });
   protected query(controls: ValueHelpQuery<DataType>): Promise<{
     data: DataType[];
     count: number;
@@ -2621,6 +2689,16 @@ interface TReadableBindingMeta {
   model?: TAtscriptAnnotatedType;
   /** Resolves the readable — lazily for token/factory, identity for instance. */
   resolve: () => AtscriptDbReadable<any>;
+  /** The route prefix the decorator derived (`options.prefix`, `@db.http.path`, table name, …). @since 0.1.150 */
+  prefix?: string;
+  /**
+   * Where {@link prefix} came from: the decorator's `prefix` option (or the
+   * factory form), the model's own `@db.http.path`, or its table / view name.
+   * @since 0.1.150
+   */
+  prefixSource?: "option" | "annotation" | "name";
+  /** The decorator's `canonical` option. @since 0.1.150 */
+  canonical?: boolean;
 }
 /**
  * Class- and method-level metadata written by `@atscript/moost-db`'s
@@ -2753,6 +2831,18 @@ interface TControllerBindingOptions {
    * annotation. Ignored for instance/factory bindings.
    */
   space?: string;
+  /**
+   * Marks (`true`) or excludes (`false`) this controller as the one whose route
+   * is published as the model's value-help path (`db.http.path`) when the same
+   * model is served by several controllers in one app. A single `canonical: true`
+   * mount wins; `canonical: false` mounts are never published; without a marker
+   * the model's own `@db.http.path`-derived mount breaks ties, and any remaining
+   * ambiguity leaves the path unset (with a boot warning). Parametric mounts
+   * (`:param` / `*` segments) are never published.
+   *
+   * @since 0.1.150
+   */
+  canonical?: boolean;
 }
 /**
  * Combines the boilerplate needed to turn an {@link AsDbController}

package/dist/index.d.mts

@@ -6,6 +6,12 @@ import { parseUrl } from "@uniqu/url";
 import { AggregateFn, AtscriptDbReadable, AtscriptDbTable, BucketUnit, FilterExpr, FlatOf, TCrudOp, TCrudOp as TCrudOp$1, TCrudPermissions, TCrudPermissions as TCrudPermissions$1, TDbActionInfo, TDbActionInfo as TDbActionInfo$1, TDbActionIntent, TDbActionIntent as TDbActionIntent$1, TDbActionLevel, TDbActionLevel as TDbActionLevel$1, TDbActionProcessor, TDbActionTargetSummary, TDbActionTargetSummary as TDbActionTargetSummary$1, TDbAvailableActions, TDbAvailableActions as TDbAvailableActions$1, TDbFieldMeta, TDbRemoveGuardContext, TDbRemoveGuardContext as TDbRemoveGuardContext$1, TDbWriteAction, TDbWriteAction as TDbWriteAction$1, TDbWriteCheckContext, TDbWriteCheckContext as TDbWriteCheckContext$1, TDbWriteGuardContext, TDbWriteGuardContext as TDbWriteGuardContext$1, TFilterPredicate, TIdResolveOptions, TIdentification, TMetaResponse, TQueryPathOp, TQueryPathOp as TQueryPathOp$1, TQueryPathRefs, TQueryPathSource, Uniquery, UniqueryControls, collectQueryPaths } from "@atscript/db";
 import { EventContext } from "@wooksjs/event-core";
 
+//#region src/http-path.d.ts
+/** The published path of every model one app serves (`null`: mounted, published nowhere). */
+interface THttpPathScope {
+  readonly paths: ReadonlyMap<TAtscriptAnnotatedType, string | null>;
+}
+//#endregion
 //#region src/as-readable.controller.d.ts
 /**
  * Endpoint a {@link AsReadableController.prepareRequest} call serves. `/one`
@@ -89,8 +95,9 @@ interface TDbParsedRequest {
  * Abstract base class for read-only HTTP controllers over an Atscript interface.
  *
  * Shared responsibilities (implemented here):
- * - Stamps `@db.http.path` on the bound interface's metadata at registration
- *   with the final public path (leading slash + Moost `globalPrefix`).
+ * - Publishes `@db.http.path` (the model's value-help URL) per app after
+ *   `app.init()`, derived from each controller's own bound route (see
+ *   `docs/http/index.md`); the constructor only records which model it serves.
  * - Lazily serializes the bound interface for the `/meta` endpoint
  *   (see {@link getSerializeOptions}).
  * - Provides DTO-backed validators for the Uniquery controls DTOs and the
@@ -120,23 +127,44 @@ declare abstract class AsReadableController<T extends TAtscriptAnnotatedType = T
   protected app: Moost;
   /** Cached serialized type definition (lazy, computed on first access). */
   private _serializedType?;
+  /** App scope every cache below was built for; a different scope drops them all ({@link enterScope}). */
+  private _cacheScope?;
+  /** Scope of the synchronous build in flight — instance-local, cleared in `finally`. */
+  protected _buildScope?: THttpPathScope;
   /** Cached full meta response (computed lazily on first meta() call). */
   private _metaResponse?;
   /** {@link metaCacheKey} the cached response was built for. */
   private _metaResponseKey?;
   /** Cached serialized form schemas keyed by `FormType.name` — populated lazily by {@link metaForm}. */
   private _formSchemas;
-  constructor(boundType: T, controllerName: string, app: Moost, kindTag?: string);
+  /**
+   * @param opts.canonical Multi-mount models only: marks (`true`) or excludes
+   *   (`false`) this controller as the model's published value-help route
+   *   (since 0.1.150). Decorator-bound controllers use the decorator option.
+   */
+  constructor(boundType: T, controllerName: string, app: Moost, kindTag?: string, opts?: {
+    canonical?: boolean;
+  });
   /**
    * Subclass contract: return `true` if `path` addresses a field that exists
    * AND is visible to the current request — see the DB controller's override
    * for the full list of positions that consult it.
    */
   protected abstract hasField(path: string): boolean;
-  /** Sets @db.http.path on the type metadata from the controller's computed prefix. */
-  private _resolveHttpPath;
-  /** Lazily serializes the bound type (after all controllers have set @db.http.path). */
+  /**
+   * The app of the current event, through DI — never the one this
+   * (singleton) instance was constructed in, which may be gone (a re-booted
+   * app, a hot reload). Outside an event it is {@link app}.
+   *
+   * @since 0.1.150
+   */
+  protected currentApp(): Promise<Moost>;
+  /** Lazily serializes the bound type (dropped with the other caches on a scope change). */
   protected getSerializedType(): TSerializedAnnotatedType;
+  /** Drops every scope-dependent cache when `scope` is not the one they were built for. */
+  private enterScope;
+  /** Runs a synchronous build with `scope`'s `db.http.path` overrides applied. */
+  private buildScoped;
   /**
    * Serializes a type for the meta surfaces (`/meta`, `/meta/form/:name`)
    * with {@link getSerializeOptions}, then re-points every reference chain to
@@ -145,6 +173,11 @@ declare abstract class AsReadableController<T extends TAtscriptAnnotatedType = T
    * serialize exactly as before.
    */
   protected serializeForMeta(type: TAtscriptAnnotatedType): TSerializedAnnotatedType;
+  /**
+   * {@link getSerializeOptions} plus the current build's per-app `db.http.path`
+   * overrides (a subclass's own `annotationOverrides` entry wins for the same key).
+   */
+  private _effectiveSerializeOptions;
   /**
    * One-time initialization hook. Override to seed data, register watchers, etc.
    */
@@ -282,6 +315,14 @@ declare abstract class AsReadableController<T extends TAtscriptAnnotatedType = T
    * response by principal.
    */
   meta(): Promise<TMetaResponse>;
+  /**
+   * The root of a controller's own `/meta` carries its own mount as
+   * `db.http.path` (a secondary mount answers with its own route; references to
+   * the model elsewhere carry the canonical one). Left alone for parametric
+   * mounts and when the serialize options strip the key. Never mutates the
+   * cached envelope.
+   */
+  private _withOwnHttpPath;
   /**
    * The `/meta` payload for the current request — the cached envelope
    * through {@link applyMetaOverlay} — WITHOUT the `/meta` route's
@@ -1302,6 +1343,11 @@ declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscrip
   private _searchIndexFieldPaths;
   /** `@db.index.geo` indexes — their fields carry physical names, mapped back to logical paths. */
   private _geoIndexFieldPaths;
+  /**
+   * The index visibility gate applies: {@link hasField} is overridden, or the
+   * model has `@db.writeOnly` fields (never readable through a search hit).
+   */
+  private get _indexGateActive();
   /** Every path `entry` reads is visible to this request. */
   private _indexVisible;
   /**
@@ -1668,6 +1714,14 @@ declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscrip
    * nothing can apply is ignored. Resolvers (query targets, `resolveQuery`)
    * refuse it — a subclass override that applies the term must return a new
    * filter object.
+   *
+   * A string field matches when the term is a substring of its text; an
+   * INTEGER field (`number.int` and its sizes, `@expect.int`,
+   * `@db.default.increment`) when it is a substring of the number's decimal
+   * text — `2946` finds `29461277` (since 0.1.150). To search numeric IDs
+   * declare `@db.column.searchable` (fallback) or `@db.index.fulltext`
+   * (native, exact number) on the integer field — override this hook only for
+   * search rules the annotations cannot express.
    */
   protected applySearchFallback(filter: FilterExpr | undefined, controls: Record<string, unknown>): FilterExpr | undefined;
   /**
@@ -1690,6 +1744,21 @@ declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscrip
    * the same shape as the one this whole path exists to remove.
    */
   private _aggregateControls;
+  /**
+   * `$count` of a native text / vector search: the adapter's own count, so it
+   * agrees with `/query` and `/pages`. A text search counts every match (the
+   * single returned row is discarded); a vector search counts the nearest
+   * neighbours up to `$limit` (default 1000), as `/query` returns them.
+   */
+  private _countSearched;
+  /**
+   * The controls a native search / vector read is run with: the request's
+   * sealed controls (so every search control — `$fuzzy`, … — reaches the
+   * adapter) plus the select, the threshold and the caller's paging. ONE
+   * builder for `/query`, `/pages` and the native `$count`, so they can't
+   * disagree about what a search matches.
+   */
+  private _searchReadControls;
   private _resolveReadStrategy;
   /**
    * Post-read row decoration hook. Not implemented by
@@ -1738,12 +1807,6 @@ declare class AsDbReadableController<T extends TAtscriptAnnotatedType = TAtscrip
    * when implemented.
    */
   private _augmentAndDecorate;
-  /**
-   * The app of the current event, through DI — never the one this
-   * (singleton) instance was constructed in, which may be gone (a re-booted
-   * app, a hot reload).
-   */
-  private _currentApp;
   /** The class's `@DbActionsFrom` delegations, validated on first use (per app). */
   private _delegations;
   /**
@@ -2212,7 +2275,8 @@ declare class AsDbController<T extends TAtscriptAnnotatedType = TAtscriptAnnotat
    * Bulk auto-lift: each item carries its own `version` → `$cas`.
    * NOTE: per-item conflict disambiguation in the response body is deferred
    * (§6.4) — the aggregate `{ matchedCount, modifiedCount }` surfaces partial
-   * application; callers can detect mismatches via `modifiedCount < N`.
+   * application; callers can detect mismatches via `matchedCount < N` (`modifiedCount` may
+   * be lower for unchanged values, e.g. a version-exempt patch on MySQL / Mongo).
    */
   private _resolveBulkCas;
   /**
@@ -2344,7 +2408,9 @@ declare abstract class AsValueHelpController<T extends TAtscriptAnnotatedType =
   protected readonly searchableFields: readonly string[];
   /** The `@meta.id` field name on the bound interface, if any. */
   protected readonly primaryKey: string | undefined;
-  constructor(boundType: T, controllerName: string, app: Moost);
+  constructor(boundType: T, controllerName: string, app: Moost, opts?: {
+    canonical?: boolean;
+  });
   /** Executes a value-help query against the backing source. */
   protected abstract query(controls: ValueHelpQuery<DataType>): Promise<{
     data: DataType[];
@@ -2482,7 +2548,9 @@ declare abstract class AsValueHelpController<T extends TAtscriptAnnotatedType =
 declare class AsJsonValueHelpController<T extends TAtscriptAnnotatedType = TAtscriptAnnotatedType, DataType = TAtscriptDataType<T>> extends AsValueHelpController<T, DataType> {
   protected rows: DataType[];
   private _pkIndex?;
-  constructor(boundType: T, rows: DataType[], app: Moost, controllerName?: string);
+  constructor(boundType: T, rows: DataType[], app: Moost, controllerName?: string, opts?: {
+    canonical?: boolean;
+  });
   protected query(controls: ValueHelpQuery<DataType>): Promise<{
     data: DataType[];
     count: number;
@@ -2621,6 +2689,16 @@ interface TReadableBindingMeta {
   model?: TAtscriptAnnotatedType;
   /** Resolves the readable — lazily for token/factory, identity for instance. */
   resolve: () => AtscriptDbReadable<any>;
+  /** The route prefix the decorator derived (`options.prefix`, `@db.http.path`, table name, …). @since 0.1.150 */
+  prefix?: string;
+  /**
+   * Where {@link prefix} came from: the decorator's `prefix` option (or the
+   * factory form), the model's own `@db.http.path`, or its table / view name.
+   * @since 0.1.150
+   */
+  prefixSource?: "option" | "annotation" | "name";
+  /** The decorator's `canonical` option. @since 0.1.150 */
+  canonical?: boolean;
 }
 /**
  * Class- and method-level metadata written by `@atscript/moost-db`'s
@@ -2753,6 +2831,18 @@ interface TControllerBindingOptions {
    * annotation. Ignored for instance/factory bindings.
    */
   space?: string;
+  /**
+   * Marks (`true`) or excludes (`false`) this controller as the one whose route
+   * is published as the model's value-help path (`db.http.path`) when the same
+   * model is served by several controllers in one app. A single `canonical: true`
+   * mount wins; `canonical: false` mounts are never published; without a marker
+   * the model's own `@db.http.path`-derived mount breaks ties, and any remaining
+   * ambiguity leaves the path unset (with a boot warning). Parametric mounts
+   * (`:param` / `*` segments) are never published.
+   *
+   * @since 0.1.150
+   */
+  canonical?: boolean;
 }
 /**
  * Combines the boilerplate needed to turn an {@link AsDbController}