@atscript/db-client 0.1.43 → 0.1.45

package/dist/index.d.mts

@@ -1,371 +1,104 @@
-//#region ../../node_modules/.pnpm/@uniqu+core@0.1.2/node_modules/@uniqu/core/dist/index.d.ts
-/** All comparison operators supported by the filter format. */
-type ComparisonOp = '$eq' | '$ne' | '$gt' | '$gte' | '$lt' | '$lte' | '$in' | '$nin' | '$regex' | '$exists';
-/**
- * Per-field typed operator map. When `V` is the field's value type, operators
- * are constrained accordingly:
- * - `$regex` is only available when `V` extends `string`
- * - `$gt/$gte/$lt/$lte` are only available when `V` extends `number | string | Date`
- */
-type FieldOpsFor<V> = {
-  $eq?: V;
-  $ne?: V;
-  $in?: V[];
-  $nin?: V[];
-  $exists?: boolean;
-} & (V extends string ? {
-  $regex?: RegExp | string;
-} : {}) & (V extends number | string | Date ? {
-  $gt?: V;
-  $gte?: V;
-  $lt?: V;
-  $lte?: V;
-} : {});
-/** Untyped operator map. */
-/**
- * A filter expression is either a comparison leaf or a logical branch.
- * `T` is the entity shape — provides type-safe field names and value types.
- * Defaults to `Record<string, unknown>` (untyped).
- */
-type FilterExpr<T = Record<string, unknown>> = ComparisonNode<T> | LogicalNode<T>;
-/**
- * Leaf node: one or more field comparisons.
- * When `T` is typed, only known keys are allowed.
- * When untyped (default), any string key is accepted.
- */
-type ComparisonNode<T = Record<string, unknown>> = { [K in keyof T & string]?: T[K] | FieldOpsFor<T[K]> };
-/**
- * Branch node: logical combination of child expressions.
- * Each variant forbids the other logical keys via `never` to prevent
- * mixing comparison fields with logical operators at the type level.
- */
-type LogicalNode<T = Record<string, unknown>> = {
-  $and: FilterExpr<T>[];
-  $or?: never;
-  $not?: never;
-} | {
-  $or: FilterExpr<T>[];
-  $and?: never;
-  $not?: never;
-} | {
-  $not: FilterExpr<T>;
-  $and?: never;
-  $or?: never;
-};
-/** Known aggregate function names. Consumers may support additional functions via the (string & {}) escape hatch. */
-type AggregateFn = 'sum' | 'count' | 'avg' | 'min' | 'max';
-/** A single aggregate function call within $select. Generic params preserve literal types for result inference. */
-interface AggregateExpr<Fn extends string = AggregateFn | (string & {}), Field extends string = string, Alias extends string = string> {
-  /** Function name (sum, count, avg, min, max, or custom). */
-  $fn: Fn;
-  /** Field to aggregate. '*' for count(*). */
-  $field: Field;
-  /** Alias for the result. Auto-generated by URL parser if omitted. */
-  $as?: Alias;
-}
-/**
- * Projection definition.
- * - Array form: inclusion list with optional aggregates.
- *   Plain strings select fields; AggregateExpr objects define computed columns.
- * - Object form: inclusion/exclusion map (0 or 1 per field). No aggregates in this form.
- */
-type SelectExpr<T = Record<string, unknown>> = ((keyof T & string) | AggregateExpr)[] | Partial<Record<keyof T & string, 0 | 1>>;
-/** Query controls (pagination, projection, sorting, grouping). Generic `T` constrains field names. */
-interface UniqueryControls<T = Record<string, unknown>, Nav extends Record<string, unknown> = Record<string, unknown>> {
-  $sort?: Partial<Record<keyof T & string, 1 | -1>>;
-  $skip?: number;
-  $limit?: number;
-  $count?: boolean;
-  $select?: SelectExpr<T>;
-  /** Fields to group by for aggregate queries. */
-  $groupBy?: (keyof T & string)[];
-  /** Post-aggregation filter. Operates on aggregate aliases and dimension fields. */
-  $having?: FilterExpr;
-  /** Relations to populate alongside the query. */
-  $with?: TypedWithRelation<Nav>[];
-  /** Pass-through for unknown $-prefixed keywords. */
-  [key: `$${string}`]: unknown;
-}
-/**
- * Canonical query representation.
- * When `name` is present this is a nested relation (sub-query inside `$with`).
- * When absent it is the root query.
- */
-interface Uniquery<T = Record<string, unknown>, Nav extends Record<string, unknown> = Record<string, unknown>> {
-  /** Relation name. Present only for nested `$with` sub-queries. */
-  name?: string;
-  filter?: FilterExpr<T>;
-  controls?: UniqueryControls<T, Nav>;
-  /** Pre-computed insights. */
-  insights?: UniqueryInsights;
-}
-/** Unwrap array types to get the element type for nav props. */
-type NavTarget<T> = T extends Array<infer U> ? U : T;
-/**
- * A typed $with relation entry.
- * When Nav is typed (from __navProps), name is constrained to known nav prop keys.
- * Each entry gets its own filter/controls typed to the target entity.
- * Falls back to untyped WithRelation when Nav has no known keys.
- */
-type TypedWithRelation<Nav extends Record<string, unknown>> = [keyof Nav & string] extends [never] ? WithRelation | string : { [K in keyof Nav & string]: {
-  name: K;
-  filter?: FilterExpr<NavTarget<Nav[K]> extends {
-    __ownProps: infer F;
-  } ? F : Record<string, unknown>>;
-  controls?: UniqueryControls<NavTarget<Nav[K]> extends {
-    __ownProps: infer F;
-  } ? F : Record<string, unknown>, NavTarget<Nav[K]> extends {
-    __navProps: infer N extends Record<string, unknown>;
-  } ? N : Record<string, unknown>>;
-  insights?: UniqueryInsights;
-} }[keyof Nav & string] | (keyof Nav & string);
-/** Untyped $with relation — used when Nav generic is not provided. */
-type WithRelation = {
-  name: string;
-  filter?: FilterExpr;
-  controls?: UniqueryControls;
-  insights?: UniqueryInsights;
-};
-/**
- * Insight operator includes comparison ops, control ops ($-prefixed),
- * and aggregate function names (bare, e.g. 'sum', 'avg').
- */
-type InsightOp = ComparisonOp | '$select' | '$order' | '$with' | '$groupBy' | '$having' | AggregateFn | (string & {});
-/** Map of field names to the set of operators used on that field. */
-type UniqueryInsights = Map<string, Set<InsightOp>>;
-/** Aggregate query controls. Separate from UniqueryControls: $groupBy is required, $with is forbidden. */
-interface AggregateControls<T = Record<string, unknown>, D extends keyof T & string = keyof T & string, M extends keyof T & string = keyof T & string> {
-  $groupBy: D[];
-  $select?: (D | AggregateExpr<AggregateFn, M | '*'>)[];
-  $having?: FilterExpr;
-  $sort?: Record<string, 1 | -1>;
-  $skip?: number;
-  $limit?: number;
-  $count?: boolean;
-  [key: `$${string}`]: unknown;
-}
-/** Aggregate query — no name (can't nest), no Nav (no $with). */
-interface AggregateQuery<T = Record<string, unknown>, D extends keyof T & string = keyof T & string, M extends keyof T & string = keyof T & string> {
-  filter?: FilterExpr<T>;
-  controls: AggregateControls<T, D, M>;
-  insights?: UniqueryInsights;
-}
-/** Resolve the output alias of an AggregateExpr. Uses $as if provided, otherwise generates {fn}_{field}. */
-//#endregion
-//#region ../../node_modules/.pnpm/@atscript+typescript@0.1.41_@atscript+core@0.1.41_@atscript+db@packages+db_@prostojs+lo_041ff52083ad05a1dfbd1c9f541c1d21/node_modules/@atscript/typescript/dist/utils.d.ts
-/** Top-level serialized annotated type. JSON-safe representation of a {@link TAtscriptAnnotatedType}. */
-interface TSerializedAnnotatedType extends TSerializedAnnotatedTypeInner {
-  /** Format version for forward compatibility */
-  $v: number;
-}
-/** Serialized annotated type node (used for nested types within the top-level). */
-interface TSerializedAnnotatedTypeInner {
-  type: TSerializedTypeDef;
-  metadata: Record<string, unknown>;
-  optional?: boolean;
-  id?: string;
-}
-interface TSerializedTypeFinal {
-  kind: '';
-  designType: string;
-  value?: string | number | boolean;
-  tags: string[];
-}
-interface TSerializedTypeObject {
-  kind: 'object';
-  props: Record<string, TSerializedAnnotatedTypeInner>;
-  propsPatterns: Array<{
-    pattern: {
-      source: string;
-      flags: string;
-    };
-    def: TSerializedAnnotatedTypeInner;
-  }>;
-  tags: string[];
-}
-interface TSerializedTypeArray {
-  kind: 'array';
-  of: TSerializedAnnotatedTypeInner;
-  tags: string[];
-}
-interface TSerializedTypeComplex {
-  kind: 'union' | 'intersection' | 'tuple';
-  items: TSerializedAnnotatedTypeInner[];
-  tags: string[];
-}
-interface TSerializedTypeRef {
-  kind: '$ref';
-  id: string;
-}
-type TSerializedTypeDef = TSerializedTypeFinal | TSerializedTypeObject | TSerializedTypeArray | TSerializedTypeComplex | TSerializedTypeRef;
-/** Context passed to {@link TSerializeOptions.processAnnotation} for each annotation entry. */
-//#endregion
-//#region src/types.d.ts
-/** Options for creating a Client instance. */
-interface ClientOptions {
-  /**
-   * Custom fetch implementation. Defaults to `globalThis.fetch`.
-   * Use this to inject auth headers, interceptors, or a custom HTTP client.
-   */
-  fetch?: typeof globalThis.fetch;
-  /**
-   * Default headers to include with every request.
-   * Can be a static object or an async factory (e.g. for refreshing auth tokens).
-   */
-  headers?: Record<string, string> | (() => Record<string, string> | Promise<Record<string, string>>);
-  /**
-   * Base URL prefix. Prepended to the client path for full URL construction.
-   * @example "https://api.example.com"
-   */
-  baseUrl?: string;
-}
-/** Search index metadata from the server. */
-interface SearchIndexInfo {
-  name: string;
-  description?: string;
-  type?: "text" | "vector";
-}
-/** Relation summary in meta response. */
-interface RelationInfo {
-  name: string;
-  direction: "to" | "from" | "via";
-  isArray: boolean;
-}
-/** Per-field capability flags. */
-interface FieldMeta {
-  sortable: boolean;
-  filterable: boolean;
-}
-/** Enhanced meta response from the server. */
-interface MetaResponse {
-  searchable: boolean;
-  vectorSearchable: boolean;
-  searchIndexes: SearchIndexInfo[];
-  primaryKeys: string[];
-  readOnly: boolean;
-  relations: RelationInfo[];
-  fields: Record<string, FieldMeta>;
-  type: TSerializedAnnotatedType;
-}
-interface InsertResult {
-  insertedId: unknown;
-}
-interface InsertManyResult {
-  insertedCount: number;
-  insertedIds: unknown[];
-}
-interface UpdateResult {
-  matchedCount: number;
-  modifiedCount: number;
-}
-interface DeleteResult {
-  deletedCount: number;
-}
-/** Paginated response shape (matches moost-db /pages response). */
-interface PagesResponse<T> {
-  data: T[];
-  page: number;
-  itemsPerPage: number;
-  pages: number;
-  count: number;
-}
-/** Server error response shape (matches moost-db error transform). */
-interface ServerError {
-  message: string;
-  statusCode: number;
-  errors?: Array<{
-    path: string;
-    message: string;
-    details?: unknown[];
-  }>;
-}
-/** Extract the data type from an Atscript annotated type `T`. */
-type DataOf<T> = T extends {
-  type: {
-    __dataType?: infer D;
-  };
-} ? unknown extends D ? T extends (new (...a: any[]) => infer I) ? I : Record<string, unknown> : D & Record<string, unknown> : Record<string, unknown>;
-/** Extract own (non-nav) properties from an Atscript annotated type. */
-type OwnOf<T> = T extends {
-  __ownProps: infer O;
-} ? O : DataOf<T>;
-/** Extract nav properties from an Atscript annotated type. */
-type NavOf<T> = T extends {
-  __navProps: infer N extends Record<string, unknown>;
-} ? N : Record<string, never>;
-/** Extract primary key type from an Atscript annotated type. */
-type IdOf<T> = T extends {
-  __pk: infer PK;
-} ? PK : unknown;
-/**
- * Shared interface for both server-side `AtscriptDbTable` and client-side `Client`.
- * Enables SSR isomorphism: same code runs on server (direct DB) and browser (HTTP).
- *
- * ```typescript
- * const users: DbInterface<typeof User> = isServer ? serverTable : httpClient
- * await users.findMany({ filter: { active: true } })
- * ```
- */
-interface DbInterface<T = Record<string, unknown>> {
-  findOne(query: Uniquery<OwnOf<T>, NavOf<T>>): Promise<DataOf<T> | null>;
-  findMany(query?: Uniquery<OwnOf<T>, NavOf<T>>): Promise<DataOf<T>[]>;
-  findById(id: IdOf<T>, query?: {
-    controls?: UniqueryControls<OwnOf<T>, NavOf<T>>;
-  }): Promise<DataOf<T> | null>;
-  count(query?: Uniquery<OwnOf<T>, NavOf<T>>): Promise<number>;
-  search(text: string, query?: Uniquery<OwnOf<T>, NavOf<T>>, indexName?: string): Promise<DataOf<T>[]>;
-  aggregate(query: AggregateQuery): Promise<Record<string, unknown>[]>;
-  insertOne(data: Partial<DataOf<T>>): Promise<InsertResult>;
-  insertMany(data: Partial<DataOf<T>>[]): Promise<InsertManyResult>;
-  updateOne(data: Partial<DataOf<T>>): Promise<UpdateResult>;
-  bulkUpdate(data: Partial<DataOf<T>>[]): Promise<UpdateResult>;
-  replaceOne(data: DataOf<T>): Promise<UpdateResult>;
-  bulkReplace(data: DataOf<T>[]): Promise<UpdateResult>;
-  deleteOne(id: IdOf<T>): Promise<DeleteResult>;
-}
-//#endregion
+import { C as TDbUpdateResult, E as UniqueryControls, S as TDbInsertResult, T as Uniquery, _ as RelationInfo, b as TDbDeleteResult, c as ClientOptions, d as FilterExpr, f as IdOf, g as PageResult, h as OwnOf, i as ValidatorMode, l as DataOf, m as NavOf, n as ClientValidator, o as AggregateQuery, p as MetaResponse, s as AggregateResult, t as ClientValidationError, u as FieldMeta, v as SearchIndexInfo, w as TypedWithRelation, x as TDbInsertManyResult, y as ServerError } from "./validator-D0lqruKm.mjs";
+import { TSerializedAnnotatedType } from "@atscript/typescript/utils";
+import { AggregateQuery as AggregateQuery$1, AggregateResult as AggregateResult$1, Uniquery as Uniquery$1, UniqueryControls as UniqueryControls$1 } from "@uniqu/core";
+import { TDbDeleteResult as TDbDeleteResult$1, TDbInsertManyResult as TDbInsertManyResult$1, TDbInsertResult as TDbInsertResult$1, TDbUpdateResult as TDbUpdateResult$1 } from "@atscript/db";
+
 //#region src/client.d.ts
+type Own<T> = OwnOf<T>;
+type Nav<T> = NavOf<T>;
+type Data<T> = DataOf<T>;
+type Id<T> = IdOf<T>;
 /**
- * Browser-compatible HTTP client for moost-db REST endpoints.
+ * HTTP client for moost-db REST endpoints.
  *
- * Two usage modes (same class, different generic):
- * ```typescript
- * // Untyped — broad Record<string, unknown> typing
- * const users = new Client('/db/tables/users')
+ * Each method maps 1:1 to a controller endpoint:
+ * - `query()` → `GET /query`
+ * - `count()` → `GET /query` with `$count`
+ * - `aggregate()` → `GET /query` with `$groupBy`
+ * - `pages()` → `GET /pages`
+ * - `one()`   → `GET /one/:id` or `GET /one?compositeKeys`
+ * - `insert()`  → `POST /`
+ * - `update()`  → `PATCH /`
+ * - `replace()` → `PUT /`
+ * - `remove()`  → `DELETE /:id` or `DELETE /?compositeKeys`
+ * - `meta()`  → `GET /meta`
  *
- * // Type-safe — Atscript type as generic parameter
- * const users = new Client<typeof User>('/db/tables/users')
+ * ```typescript
+ * const users = new Client<typeof User>('/api/users')
+ * const all = await users.query()
+ * const page = await users.pages({ filter: { active: true } }, 1, 20)
  * ```
  */
-declare class Client<T = Record<string, unknown>> implements DbInterface<T> {
+declare class Client<T = Record<string, unknown>> {
   private readonly _path;
   private readonly _baseUrl;
   private readonly _fetch;
   private readonly _headers?;
   private _metaPromise?;
+  private _validatorPromise?;
   constructor(path: string, opts?: ClientOptions);
-  findOne(query: Uniquery<OwnOf<T>, NavOf<T>>): Promise<DataOf<T> | null>;
-  findMany(query?: Uniquery<OwnOf<T>, NavOf<T>>): Promise<DataOf<T>[]>;
-  findById(id: IdOf<T>, query?: {
-    controls?: UniqueryControls<OwnOf<T>, NavOf<T>>;
-  }): Promise<DataOf<T> | null>;
-  count(query?: Uniquery<OwnOf<T>, NavOf<T>>): Promise<number>;
-  findManyWithCount(query: Uniquery<OwnOf<T>, NavOf<T>>): Promise<{
-    data: DataOf<T>[];
-    count: number;
-  }>;
-  pages(query?: Uniquery<OwnOf<T>, NavOf<T>>): Promise<PagesResponse<DataOf<T>>>;
-  search(text: string, query?: Uniquery<OwnOf<T>, NavOf<T>>, indexName?: string): Promise<DataOf<T>[]>;
-  aggregate(query: AggregateQuery): Promise<Record<string, unknown>[]>;
-  insertOne(data: Partial<DataOf<T>>): Promise<InsertResult>;
-  insertMany(data: Partial<DataOf<T>>[]): Promise<InsertManyResult>;
-  updateOne(data: Partial<DataOf<T>>): Promise<UpdateResult>;
-  bulkUpdate(data: Partial<DataOf<T>>[]): Promise<UpdateResult>;
-  replaceOne(data: DataOf<T>): Promise<UpdateResult>;
-  bulkReplace(data: DataOf<T>[]): Promise<UpdateResult>;
-  deleteOne(id: IdOf<T>): Promise<DeleteResult>;
+  /**
+   * `GET /query` — query records with typed filter, sort, select, and relations.
+   */
+  query(query?: Uniquery$1<Own<T>, Nav<T>>): Promise<Data<T>[]>;
+  /**
+   * `GET /query` with `$count: true` — returns record count.
+   */
+  count(query?: {
+    filter?: Uniquery$1<Own<T>, Nav<T>>["filter"];
+  }): Promise<number>;
+  /**
+   * `GET /query` with `$groupBy` — aggregate query with typed dimension/measure fields.
+   */
+  aggregate<Q extends AggregateQuery$1<Own<T>>>(query: Q): Promise<Q["controls"]["$select"] extends readonly (string | {
+    $fn: string;
+    $field: string;
+  })[] ? AggregateResult$1<Own<T>, Q["controls"]["$select"]>[] : Record<string, unknown>[]>;
+  /**
+   * `GET /pages` — paginated query with typed filter and relations.
+   */
+  pages(query?: Uniquery$1<Own<T>, Nav<T>>, page?: number, size?: number): Promise<PageResult<Data<T>>>;
+  /**
+   * `GET /one/:id` or `GET /one?k1=v1&k2=v2` — single record by primary key.
+   *
+   * Returns `null` on 404.
+   */
+  one(id: Id<T>, query?: {
+    controls?: UniqueryControls$1<Own<T>, Nav<T>>;
+  }): Promise<Data<T> | null>;
+  /**
+   * `POST /` — insert one record.
+   */
+  insert(data: Partial<Data<T>>): Promise<TDbInsertResult$1>;
+  /**
+   * `POST /` — insert many records.
+   */
+  insert(data: Partial<Data<T>>[]): Promise<TDbInsertManyResult$1>;
+  /**
+   * `PATCH /` — partial update one or many records by primary key.
+   */
+  update(data: Partial<Data<T>> | Partial<Data<T>>[]): Promise<TDbUpdateResult$1>;
+  /**
+   * `PUT /` — full replace one or many records by primary key.
+   */
+  replace(data: Data<T> | Data<T>[]): Promise<TDbUpdateResult$1>;
+  /**
+   * `DELETE /:id` or `DELETE /?k1=v1&k2=v2` — remove a record by primary key.
+   */
+  remove(id: Id<T>): Promise<TDbDeleteResult$1>;
+  /**
+   * `GET /meta` — table/view metadata (cached after first call).
+   */
   meta(): Promise<MetaResponse>;
+  /**
+   * Returns a lazily-initialized {@link ClientValidator} backed by the `/meta` type.
+   * Useful for accessing `flatMap` and `navFields` (e.g. for form generation).
+   */
+  getValidator(): Promise<ClientValidator>;
+  private _validateData;
+  private _getValidator;
   private _idToParams;
+  private _getOrNull;
   private _get;
   private _resolveHeaders;
   private _request;
@@ -395,4 +128,4 @@ declare class ClientError extends Error {
   }[];
 }
 //#endregion
-export { type AggregateQuery, Client, ClientError, type ClientOptions, type DataOf, type DbInterface, type DeleteResult, type FieldMeta, type FilterExpr, type IdOf, type InsertManyResult, type InsertResult, type MetaResponse, type NavOf, type OwnOf, type PagesResponse, type RelationInfo, type SearchIndexInfo, type ServerError, type TSerializedAnnotatedType, type TypedWithRelation, type Uniquery, type UniqueryControls, type UpdateResult };
+export { type AggregateQuery, type AggregateResult, Client, ClientError, type ClientOptions, type ClientValidationError, type ClientValidator, type DataOf, type FieldMeta, type FilterExpr, type IdOf, type MetaResponse, type NavOf, type OwnOf, type PageResult, type RelationInfo, type SearchIndexInfo, type ServerError, type TDbDeleteResult, type TDbInsertManyResult, type TDbInsertResult, type TDbUpdateResult, type TSerializedAnnotatedType, type TypedWithRelation, type Uniquery, type UniqueryControls, type ValidatorMode };