@antelopejs/interface-data-api 0.3.0 → 0.5.0

package/README.md

@@ -129,7 +129,7 @@ Use with `@antelopejs/core` 1.x and the following peer dependencies:
 | `@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.9 <1.0.0`  |
+| `@antelopejs/interface-database-decorators` | `>=0.1.10 <1.0.0` |
 
 ## Contributing
 

package/dist/components.d.ts

@@ -1,7 +1,8 @@
 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 FieldFilter, type FieldValues } from "./metadata";
 export declare namespace Parameters {
     export function GetOptionOverrides<T extends Record<string, any>>(reqCtx: RequestContext): T;
     /**
@@ -72,7 +73,7 @@ export declare namespace Query {
     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: any, meta: DataAPIMeta, dbData: any, action?: string, onlyList?: boolean): Promise<FieldValues>;
     /**
      * Writes the writable fields of `bodyData` into a database row.
      *
@@ -83,7 +84,7 @@ 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 WriteProperties(obj: any, meta: DataAPIMeta, bodyData: FieldValues, action?: string, existingDBData?: Record<string, any>): Promise<Record<string, any>>;
     function Get(table: Table<any>, id: string | ValueProxy<string>, index?: string): Datum<any>;
     interface ListOptions {
         /**
@@ -94,6 +95,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 +112,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: any, 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,17 +147,32 @@ 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. */
+    const INVALID_FIELD_TYPES = "invalid_field_types";
+    /**
+     * The body of a 400 refusing some fields of a request body: what went
+     * wrong (`code`) and the fields concerned, for the client to word it and
+     * show it under each one.
+     */
+    interface FieldsErrorBody {
+        code: typeof MISSING_MANDATORY_FIELDS | typeof INVALID_FIELD_TYPES;
+        fields: string[];
+    }
     /**
      * Rejects with 400 the request bodies missing a field mandatory for `type`.
      * On `edit`, a mandatory field is missing when the body clears it (`null`,
      * `""` or `[]`); a field absent from the body keeps its stored value. On any
-     * other action, it is missing when absent from the body.
+     * 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;
     /**
      * Runs the validator of each field present in `obj` and rejects with 400
-     * when one fails. Returns a copy of `obj` where each validated field holds
+     * when one fails, with a {@link FieldsErrorBody} of
+     * {@link INVALID_FIELD_TYPES}. Returns a copy of `obj` where each validated field holds
      * the value its validator parsed (see {@link FieldValidationResult}).
      */
     function ValidateTypes(meta: DataAPIMeta, obj: RequestBody): Promise<RequestBody>;
@@ -173,5 +196,5 @@ export declare namespace Validation {
     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 ClearInternal(meta: DataAPIMeta, obj: FieldValues | FieldValues[]): void;
 }