@antelopejs/interface-data-api 0.4.0 → 0.6.0

package/README.md

@@ -1,24 +1,26 @@
-# @antelopejs/interface-data-api
+# `@antelopejs/interface-data-api`
 
 <div align="center">
-<a href="https://www.npmjs.com/package/@antelopejs/interface-data-api"><img alt="npm" src="https://img.shields.io/npm/v/@antelopejs/interface-data-api?style=for-the-badge&labelColor=000000&color=000000"></a>
-<a href="./LICENSE"><img alt="License" src="https://img.shields.io/npm/l/@antelopejs/interface-data-api?style=for-the-badge&labelColor=000000&color=000000"></a>
-<a href="https://discord.gg/sjK28QHrA7"><img alt="Discord" src="https://img.shields.io/badge/Discord-18181B?logo=discord&style=for-the-badge&color=000000"></a>
-<a href="https://interfaces.antelopejs.com/docs/data-api"><img alt="Docs" src="https://img.shields.io/badge/Docs-18181B?style=for-the-badge&color=000000"></a>
+<a href="https://www.npmjs.com/package/@antelopejs/interface-data-api"><img data-illustration alt="npm" src="https://img.shields.io/npm/v/@antelopejs/interface-data-api?style=for-the-badge&labelColor=000000&color=000000"></a>
+<a href="./LICENSE"><img data-illustration alt="License" src="https://img.shields.io/npm/l/@antelopejs/interface-data-api?style=for-the-badge&labelColor=000000&color=000000"></a>
+<a href="https://discord.gg/g4pFt6eXqu"><img data-illustration alt="Discord" src="https://img.shields.io/badge/Discord-18181B?logo=discord&style=for-the-badge&color=000000"></a>
+<a href="https://interfaces.antelopejs.com/docs/data-api"><img data-illustration alt="Docs" src="https://img.shields.io/badge/Docs-18181B?style=for-the-badge&color=000000"></a>
 </div>
 
-CRUD REST endpoints generated from a database table: declare a data controller and its fields, and get `get`, `list`, `new`, `edit` and `delete` routes with access rules, validation and pagination.
+The AntelopeJS interface that generates CRUD REST endpoints from a database table. Declare a data controller and its fields, and it serves the `get`, `list`, `new`, `edit` and `delete` routes with access rules, validation and pagination.
+
+Part of [AntelopeJS](https://github.com/AntelopeJS/antelopejs). Used by [AntelopeJS DMS](https://github.com/AntelopeJS/dms), the open-source back office for your PostgreSQL, MongoDB or RethinkDB database.
 
 ## What it offers
 
 - `DataController` and `@RegisterDataController()` turn a table class into a controller with the default routes you pick from `DefaultRoutes`.
-- `@Access`, `@Mandatory` and `@Validator` decide which fields each route reads and writes, and check them.
+- `@Access` decides which fields each route reads and writes. `@Mandatory` and `@Validator` check the written values.
 - `@Listable`, `@Sortable` and `@Filter` shape the paginated `list` route.
 - `@Foreign`, `@Joined` and `@Computed` resolve references, flatten remote fields and add values computed in the database.
 
 ## Implementations
 
-The package runs in your module and has no implementing module of its own. The project needs modules that implement the interfaces it builds on:
+The package runs in your module and has no implementing module of its own. The project needs modules that implement the interfaces it builds on.
 
 | Interface                        | Module                                                                                                                               |
 | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
@@ -27,13 +29,13 @@ The package runs in your module and has no implementing module of its own. The p
 
 ## Install
 
-Add the package and the interfaces your controllers import to your module:
+Add the package and its peer interfaces to your module.
 
 ```bash
-pnpm add @antelopejs/interface-data-api @antelopejs/interface-api @antelopejs/interface-database-decorators
+pnpm add @antelopejs/interface-data-api @antelopejs/interface-api @antelopejs/interface-api-util @antelopejs/interface-core @antelopejs/interface-database @antelopejs/interface-database-decorators
 ```
 
-Then add the implementations to the project:
+Then add the implementations to the project.
 
 ```bash
 ajs project modules add @antelopejs/api @antelopejs/mongodb
@@ -101,7 +103,7 @@ export async function construct() {
 }
 ```
 
-The controller serves `GET /tasks/get?id=`, `GET /tasks/list`, `POST /tasks/new`, `PUT /tasks/edit?id=` and `DELETE /tasks/delete?id=`. Fields without `@Access` stay out of every response.
+The controller serves `GET /tasks/get?id=`, `GET /tasks/list`, `POST /tasks/new`, `PUT /tasks/edit?id=` and `DELETE /tasks/delete?id=`. A field without `@Access` stays out of every response and every write, unless `@Joined` or `@Computed` makes it read-only.
 
 ## Documentation
 
@@ -119,21 +121,23 @@ The controller serves `GET /tasks/get?id=`, `GET /tasks/list`, `POST /tasks/new`
 
 ## Compatibility
 
-Use with `@antelopejs/core` 1.x and the following peer dependencies:
+The package declares these `@antelopejs/*` peer dependencies.
+
+<!-- antelopejs-docs-compat:start -->
 
-<!-- docs-compat: ./package.json#peerDependencies -->
+| Package                                     | Supported         | Tested with |
+| ------------------------------------------- | ----------------- | ----------- |
+| `@antelopejs/interface-api`                 | `>=0.3.0 <1.0.0`  | `0.2.0`     |
+| `@antelopejs/interface-api-util`            | `>=0.1.3 <1.0.0`  | `0.3.0`     |
+| `@antelopejs/interface-core`                | `>=0.2.4 <1.0.0`  | `0.4.0`     |
+| `@antelopejs/interface-database`            | `>=0.1.10 <1.0.0` | `0.3.0`     |
+| `@antelopejs/interface-database-decorators` | `>=0.1.10 <1.0.0` | `0.2.0`     |
 
-| Package                                     | Range             |
-| ------------------------------------------- | ----------------- |
-| `@antelopejs/interface-api`                 | `>=0.0.15 <1.0.0` |
-| `@antelopejs/interface-api-util`            | `>=0.1.3 <1.0.0`  |
-| `@antelopejs/interface-core`                | `>=0.2.4 <1.0.0`  |
-| `@antelopejs/interface-database`            | `>=0.1.10 <1.0.0` |
-| `@antelopejs/interface-database-decorators` | `>=0.1.10 <1.0.0` |
+<!-- antelopejs-docs-compat:end -->
 
 ## Contributing
 
-Read [CONTRIBUTING.md](./CONTRIBUTING.md) before you open a pull request. The local checks are:
+Read [CONTRIBUTING.md](./CONTRIBUTING.md) before you open a pull request. Run the local checks with these commands.
 
 ```bash
 pnpm install

package/dist/antelope.test.js

@@ -22,11 +22,7 @@ exports.default = (0, config_1.defineConfig)({
             },
         },
         api: {
-            source: {
-                type: "package",
-                package: "@antelopejs/api",
-                version: "1.3.0",
-            },
+            source: { type: "local", path: "node_modules/@antelopejs/api" },
             config: {
                 publicBaseUrl: "http://127.0.0.1:5010",
                 servers: [{ protocol: "http", host: "127.0.0.1", port: 5010 }],

package/dist/antelope.test.js.map

@@ -1 +1 @@
-{"version":3,"file":"antelope.test.js","sourceRoot":"","sources":["../src/antelope.test.ts"],"names":[],"mappings":";;AAAA,2EAA+D;AAC/D,8DAAiE;AAEjE,IAAI,MAAyB,CAAC;AAE9B,kBAAe,IAAA,qBAAY,EAAC;IAC1B,IAAI,EAAE,yBAAyB;IAC/B,WAAW,EAAE,iBAAiB;IAC9B,OAAO,EAAE;QACP,KAAK,EAAE;YACL,MAAM,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,GAAG,EAAE;YACpC,eAAe,EAAE;gBACf,2BAA2B,EAAE,KAAK;gBAClC,gCAAgC,EAAE,SAAS;aAC5C;SACF;QACD,OAAO,EAAE;YACP,MAAM,EAAE;gBACN,IAAI,EAAE,SAAS;gBACf,OAAO,EAAE,qBAAqB;gBAC9B,OAAO,EAAE,OAAO;aACjB;SACF;QACD,GAAG,EAAE;YACH,MAAM,EAAE;gBACN,IAAI,EAAE,SAAS;gBACf,OAAO,EAAE,iBAAiB;gBAC1B,OAAO,EAAE,OAAO;aACjB;YACD,MAAM,EAAE;gBACN,aAAa,EAAE,uBAAuB;gBACtC,OAAO,EAAE,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;aAC/D;SACF;KACF;IACD,IAAI,EAAE;QACJ,MAAM,EAAE,YAAY;QACpB,KAAK,CAAC,KAAK;YACT,MAAM,GAAG,MAAM,8CAAiB,CAAC,MAAM,EAAE,CAAC;YAC1C,OAAO;gBACL,OAAO,EAAE;oBACP,OAAO,EAAE;wBACP,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,EAAE,QAAQ,EAAE,iBAAiB,EAAE;qBAC9D;iBACF;aACF,CAAC;QACJ,CAAC;QACD,KAAK,CAAC,OAAO;YACX,MAAM,MAAM,CAAC,IAAI,EAAE,CAAC;QACtB,CAAC;KACF;CACF,CAAC,CAAC"}
+{"version":3,"file":"antelope.test.js","sourceRoot":"","sources":["../src/antelope.test.ts"],"names":[],"mappings":";;AAAA,2EAA+D;AAC/D,8DAAiE;AAEjE,IAAI,MAAyB,CAAC;AAE9B,kBAAe,IAAA,qBAAY,EAAC;IAC1B,IAAI,EAAE,yBAAyB;IAC/B,WAAW,EAAE,iBAAiB;IAC9B,OAAO,EAAE;QACP,KAAK,EAAE;YACL,MAAM,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,GAAG,EAAE;YACpC,eAAe,EAAE;gBACf,2BAA2B,EAAE,KAAK;gBAClC,gCAAgC,EAAE,SAAS;aAC5C;SACF;QACD,OAAO,EAAE;YACP,MAAM,EAAE;gBACN,IAAI,EAAE,SAAS;gBACf,OAAO,EAAE,qBAAqB;gBAC9B,OAAO,EAAE,OAAO;aACjB;SACF;QACD,GAAG,EAAE;YACH,MAAM,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,8BAA8B,EAAE;YAC/D,MAAM,EAAE;gBACN,aAAa,EAAE,uBAAuB;gBACtC,OAAO,EAAE,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;aAC/D;SACF;KACF;IACD,IAAI,EAAE;QACJ,MAAM,EAAE,YAAY;QACpB,KAAK,CAAC,KAAK;YACT,MAAM,GAAG,MAAM,8CAAiB,CAAC,MAAM,EAAE,CAAC;YAC1C,OAAO;gBACL,OAAO,EAAE;oBACP,OAAO,EAAE;wBACP,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,EAAE,QAAQ,EAAE,iBAAiB,EAAE;qBAC9D;iBACF;aACF,CAAC;QACJ,CAAC;QACD,KAAK,CAAC,OAAO;YACX,MAAM,MAAM,CAAC,IAAI,EAAE,CAAC;QACtB,CAAC;KACF;CACF,CAAC,CAAC"}

package/dist/components.d.ts

@@ -1,9 +1,20 @@
-import type { DataModel } from "@antelopejs/interface-database-decorators/model";
 import { type RequestContext } from "@antelopejs/interface-api";
-import { type Datum, type SchemaInstance, Stream, type Table, type ValueProxy } from "@antelopejs/interface-database";
-import { type DataAPIMeta, type FieldFilter } from "./metadata";
+import type { Datum, SchemaInstance, Stream, Table, ValueProxy } from "@antelopejs/interface-database";
+import "@antelopejs/interface-database";
+import { type DataAPIMeta, type DataControllerCallbackWithOptions, type DataControllerInstance, type FieldFilter, type FieldValues, type RowFields } from "./metadata";
+import * as extractors from "./internal/extractors";
+import * as tables from "./internal/tables";
 export declare namespace Parameters {
-    export function GetOptionOverrides<T extends Record<string, any>>(reqCtx: RequestContext): T;
+    /**
+     * A request context as a data route holds it: {@link RegisterDataController}
+     * sets the route's entry on it. `Options` is what the route's parameter
+     * reads, which `WithOptions` wrote.
+     */
+    interface DataRequestContext<Options = any> extends RequestContext {
+        dataAPIEntry?: DataControllerCallbackWithOptions<Options>;
+    }
+    /** The options the route's `WithOptions` set, none when it set none. */
+    function GetOptionOverrides<Options>(reqCtx: DataRequestContext<Options>): Partial<Options>;
     /**
      * Extracts request filters and mandatory route filters, with route field
      * keys winning. A field the request filters once (`?filter_status=open`)
@@ -11,19 +22,27 @@ export declare namespace Parameters {
      * (`?filter_age=ge:18&filter_age=lt:65`) gets them all, which a row must
      * all pass. Returns fresh tuples.
      */
-    export function ExtractFilters(reqCtx: RequestContext, meta: DataAPIMeta): Record<string, FieldFilter>;
-    const converters: {
-        number: (val: string) => number;
-        int: (val: string) => number;
-        bool: (val: string) => boolean;
-        string: (val: string) => string;
+    function ExtractFilters(reqCtx: DataRequestContext<ListParameters>, meta: DataAPIMeta): Record<string, FieldFilter>;
+    type ParameterExtractor<Value> = extractors.ParameterExtractor<Value>;
+    type ParameterExtractors<T> = extractors.ParameterExtractors<T>;
+    const FromSearch: {
+        number: extractors.ParameterExtractor<number>;
+        int: extractors.ParameterExtractor<number>;
+        bool: extractors.ParameterExtractor<boolean>;
+        string: extractors.ParameterExtractor<string>;
+        numbers: extractors.ParameterExtractor<number[]>;
+        ints: extractors.ParameterExtractor<number[]>;
+        bools: extractors.ParameterExtractor<boolean[]>;
+        strings: extractors.ParameterExtractor<string[]>;
     };
-    type ConvertersKey = keyof typeof converters;
-    type GenericParams<T extends Record<string, any>> = {
-        [K in keyof T]: ConvertersKey | `multi:${ConvertersKey}` | ((reqCtx: RequestContext, meta: DataAPIMeta) => any);
-    };
-    export function ExtractGeneric<T extends Record<string, any>>(reqCtx: RequestContext, meta: DataAPIMeta, dynamic: GenericParams<Partial<T>>): Partial<T>;
-    export interface ListParameters {
+    /**
+     * Builds a route's parameters: the options its `WithOptions` set, then each
+     * extracted field those options leave out. An extractor of `undefined` is
+     * skipped like an absent key. {@link ExtractFilters} also runs for a route
+     * that sets `filters`, since it combines them with the request's.
+     */
+    function ExtractGeneric<T extends Record<string, any>>(reqCtx: DataRequestContext<T>, meta: DataAPIMeta, dynamic: ParameterExtractors<T>): Partial<T>;
+    interface ListParameters {
         /**
          * The filters of the request, by field; a row passes every filter of
          * every field. Mandatory route filters when supplied through
@@ -39,40 +58,42 @@ export declare namespace Parameters {
         noPluck?: boolean;
         pluckMode?: string;
     }
-    export const List: () => import("@antelopejs/interface-core/decorators").PropertyDecorator & import("@antelopejs/interface-core/decorators").ParameterDecorator;
-    export interface GetParameters {
+    const List: () => import("@antelopejs/interface-core/decorators").PropertyDecorator & import("@antelopejs/interface-core/decorators").ParameterDecorator;
+    interface GetParameters {
         id: string;
         index?: string;
         noForeign?: string;
     }
-    export const Get: () => import("@antelopejs/interface-core/decorators").PropertyDecorator & import("@antelopejs/interface-core/decorators").ParameterDecorator;
-    export interface NewParameters {
+    const Get: () => import("@antelopejs/interface-core/decorators").PropertyDecorator & import("@antelopejs/interface-core/decorators").ParameterDecorator;
+    interface NewParameters {
         noMandatory?: string;
     }
-    export const New: () => import("@antelopejs/interface-core/decorators").PropertyDecorator & import("@antelopejs/interface-core/decorators").ParameterDecorator;
-    export interface EditParameters {
+    const New: () => import("@antelopejs/interface-core/decorators").PropertyDecorator & import("@antelopejs/interface-core/decorators").ParameterDecorator;
+    interface EditParameters {
         id: string;
         index?: string;
         noMandatory?: string;
     }
-    export const Edit: () => import("@antelopejs/interface-core/decorators").PropertyDecorator & import("@antelopejs/interface-core/decorators").ParameterDecorator;
-    export interface DeleteParameters {
+    const Edit: () => import("@antelopejs/interface-core/decorators").PropertyDecorator & import("@antelopejs/interface-core/decorators").ParameterDecorator;
+    interface DeleteParameters {
         id: string[];
     }
-    export const Delete: () => import("@antelopejs/interface-core/decorators").PropertyDecorator & import("@antelopejs/interface-core/decorators").ParameterDecorator;
-    export {};
+    const Delete: () => import("@antelopejs/interface-core/decorators").PropertyDecorator & import("@antelopejs/interface-core/decorators").ParameterDecorator;
 }
 export declare namespace Query {
-    function GetModel(obj: any, meta: DataAPIMeta): InstanceType<DataModel> & {
-        constructor: DataModel;
-    };
+    /**
+     * The database model a controller holds under its `@ModelReference` field,
+     * typed by the table rows it reads.
+     */
+    type ModelInstance = tables.ModelInstance;
+    function GetModel(obj: DataControllerInstance, meta: DataAPIMeta): ModelInstance;
     function Foreign(db: SchemaInstance<any>, meta: DataAPIMeta, query: Stream<any>, pluck?: Set<string>): Stream<any>;
     function Foreign(db: SchemaInstance<any>, meta: DataAPIMeta, query: Datum<any>, pluck?: Set<string>): Datum<any>;
     function Joined(db: SchemaInstance<any>, meta: DataAPIMeta, query: Stream<any>, only?: Set<string>): Stream<any>;
     function Joined(db: SchemaInstance<any>, meta: DataAPIMeta, query: Datum<any>, only?: Set<string>): Datum<any>;
     function Computed(db: SchemaInstance<any>, meta: DataAPIMeta, query: Stream<any>, only?: Set<string>): Stream<any>;
     function Computed(db: SchemaInstance<any>, meta: DataAPIMeta, query: Datum<any>, only?: Set<string>): Datum<any>;
-    function ReadProperties(obj: any, meta: DataAPIMeta, dbData: any, action?: string, onlyList?: boolean): Promise<Record<string, any>>;
+    function ReadProperties(obj: DataControllerInstance, meta: DataAPIMeta, dbData: RowFields, action?: string, onlyList?: boolean): Promise<RowFields>;
     /**
      * Writes the writable fields of `bodyData` into a database row.
      *
@@ -83,8 +104,8 @@ export declare namespace Query {
      * row and only their setters run: an absent field keeps its stored value,
      * `null` clears it.
      */
-    function WriteProperties(obj: any, meta: DataAPIMeta, bodyData: Record<string, any>, action?: string, existingDBData?: Record<string, any>): Promise<Record<string, any>>;
-    function Get(table: Table<any>, id: string | ValueProxy<string>, index?: string): Datum<any>;
+    function WriteProperties(obj: DataControllerInstance, meta: DataAPIMeta, bodyData: FieldValues, action?: string, existingDBData?: RowFields): Promise<RowFields>;
+    function Get<T extends object>(table: Table<T>, id: string | ValueProxy<string>, index?: string): import("@antelopejs/interface-database").SingleSelection<T> | Datum<T | null>;
     interface ListOptions {
         /**
          * Return the joined field names {@link List} did not materialize as the
@@ -94,6 +115,13 @@ export declare namespace Query {
          */
         exposeDeferredJoined?: boolean;
     }
+    /** What {@link List} takes after the request context. */
+    type ListTail = [
+        sorting?: [string, "asc" | "desc" | undefined],
+        filters?: Record<string, FieldFilter>,
+        db?: SchemaInstance<any>,
+        options?: ListOptions
+    ];
     /**
      * Builds the filtered and sorted stream of a list request along with its
      * total count. Joined fields that no filter or sort references are not
@@ -104,7 +132,7 @@ export declare namespace Query {
      * since no lookup can be built without one — the raw stream is returned
      * and the third element names the joined fields left for the caller.
      */
-    function List<T extends Record<string, any>>(obj: any, meta: DataAPIMeta, request: Table<T>, reqCtx: RequestContext, sorting?: [string, "asc" | "desc" | undefined], filters?: Record<string, FieldFilter>, db?: SchemaInstance<any>, options?: ListOptions): [sorted: Stream<T>, total: Datum<number>, deferredJoined: Set<string>];
+    function List<T extends Record<string, any>>(obj: DataControllerInstance, meta: DataAPIMeta, request: Table<T>, reqCtx: RequestContext, ...[sorting, filters, db, options]: ListTail): [sorted: Stream<T>, total: Datum<number>, deferredJoined: Set<string>];
     /** How {@link ListPage} reads one page of a {@link List} stream. */
     interface ListPageOptions {
         offset: number;
@@ -139,7 +167,7 @@ export declare namespace Query {
 }
 export declare namespace Validation {
     /** A request body, parsed. */
-    type RequestBody = Record<string, any>;
+    type RequestBody = FieldValues;
     /** The `code` of a 400 naming the mandatory fields a body lacks. */
     const MISSING_MANDATORY_FIELDS = "missing_mandatory_fields";
     /** The `code` of a 400 naming the fields whose validator refused the value. */
@@ -160,7 +188,7 @@ export declare namespace Validation {
      * other action, it is missing when absent from the body. The body of the
      * 400 is a {@link FieldsErrorBody} with {@link MISSING_MANDATORY_FIELDS}.
      */
-    function MandatoryFields(meta: DataAPIMeta, obj: any, type: string): void;
+    function MandatoryFields(meta: DataAPIMeta, obj: RequestBody, type: string): void;
     /**
      * Runs the validator of each field present in `obj` and rejects with 400
      * when one fails, with a {@link FieldsErrorBody} of
@@ -185,8 +213,8 @@ export declare namespace Validation {
      * untouched keeps its stored locked value: read while locked it would be
      * `undefined`, and locking it again would store that over it.
      */
-    function Lock(obj: any, meta: DataAPIMeta, data: any): void;
-    function Unlock(obj: any, meta: DataAPIMeta, dbData: any): void;
-    function UnlockRequest<T extends {}, K extends keyof T>(obj: any, meta: DataAPIMeta, row: ValueProxy<T>, field: K): ValueProxy<T[K]>;
-    function ClearInternal(meta: DataAPIMeta, obj: Record<string, any> | Array<Record<string, any>>): void;
+    function Lock(obj: DataControllerInstance, meta: DataAPIMeta, data: RowFields): void;
+    function Unlock(obj: DataControllerInstance, meta: DataAPIMeta, dbData: RowFields): void;
+    function UnlockRequest<T extends {}, K extends keyof T>(obj: DataControllerInstance, meta: DataAPIMeta, row: ValueProxy<T>, field: K): ValueProxy<T[K]>;
+    function ClearInternal(meta: DataAPIMeta, obj: RowFields | RowFields[]): void;
 }