@antelopejs/interface-data-api 0.5.0 → 0.6.1

package/dist/tests/internal/http.d.ts

@@ -1,3 +1,4 @@
+import { z } from "zod";
 import { type RequestContext } from "@antelopejs/interface-api";
 /**
  * Builds the context a route handler receives for a request that never
@@ -7,17 +8,28 @@ import { type RequestContext } from "@antelopejs/interface-api";
  * @returns A complete request context
  */
 export declare function createRequestContext(url?: string): RequestContext;
-/** What the `list` route answers: one page of rows and where it sits. */
-export interface ListResponse<Row> {
-    results: Row[];
-    total: number;
-    offset: number;
-    limit: number;
-}
 /**
- * Reads a response body as the JSON shape the caller expects.
+ * Schema of what the `list` route answers around a row schema: one page of
+ * rows and where it sits. Fields the row schema does not name pass through.
  *
+ * @param row Schema of one listed row
+ * @returns Schema of one page of rows
+ */
+export declare function listResponseSchema<Row extends z.ZodType>(row: Row): z.ZodObject<{
+    results: z.ZodArray<Row>;
+    total: z.ZodNumber;
+    offset: z.ZodNumber;
+    limit: z.ZodNumber;
+}, z.core.$loose>;
+/** What the `new` route answers: the created row, with its key. */
+export declare const createdRowSchema: z.ZodObject<{
+    _id: z.ZodString;
+}, z.core.$loose>;
+/**
+ * Reads a response body and parses it with the schema the caller expects.
+ *
+ * @param schema Shape the body must have
  * @param response The response whose body is read
  * @returns The parsed body
  */
-export declare function readJson<T>(response: Response): Promise<T>;
+export declare function readJson<Schema extends z.ZodType>(schema: Schema, response: Response): Promise<z.infer<Schema>>;

package/dist/tests/internal/http.js

@@ -1,10 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.createdRowSchema = void 0;
 exports.createRequestContext = createRequestContext;
+exports.listResponseSchema = listResponseSchema;
 exports.readJson = readJson;
 /** @internal @packageDocumentation */
 const node_http_1 = require("node:http");
 const node_net_1 = require("node:net");
+const zod_1 = require("zod");
 const interface_api_1 = require("@antelopejs/interface-api");
 /**
  * Builds the context a route handler receives for a request that never
@@ -24,12 +27,30 @@ function createRequestContext(url = "http://localhost/") {
     };
 }
 /**
- * Reads a response body as the JSON shape the caller expects.
+ * Schema of what the `list` route answers around a row schema: one page of
+ * rows and where it sits. Fields the row schema does not name pass through.
  *
+ * @param row Schema of one listed row
+ * @returns Schema of one page of rows
+ */
+function listResponseSchema(row) {
+    return zod_1.z.looseObject({
+        results: zod_1.z.array(row),
+        total: zod_1.z.number(),
+        offset: zod_1.z.number(),
+        limit: zod_1.z.number(),
+    });
+}
+/** What the `new` route answers: the created row, with its key. */
+exports.createdRowSchema = zod_1.z.looseObject({ _id: zod_1.z.string() });
+/**
+ * Reads a response body and parses it with the schema the caller expects.
+ *
+ * @param schema Shape the body must have
  * @param response The response whose body is read
  * @returns The parsed body
  */
-async function readJson(response) {
-    return JSON.parse(await response.text());
+async function readJson(schema, response) {
+    return schema.parse(JSON.parse(await response.text()));
 }
 //# sourceMappingURL=http.js.map

package/dist/tests/internal/http.js.map

@@ -1 +1 @@
-{"version":3,"file":"http.js","sourceRoot":"","sources":["../../../src/tests/internal/http.ts"],"names":[],"mappings":";;AAYA,oDAWC;AAgBD,4BAEC;AAzCD,sCAAsC;AACtC,yCAA4D;AAC5D,uCAAkC;AAClC,6DAA4E;AAE5E;;;;;;GAMG;AACH,SAAgB,oBAAoB,CAClC,GAAG,GAAG,mBAAmB;IAEzB,MAAM,UAAU,GAAG,IAAI,2BAAe,CAAC,IAAI,iBAAM,EAAE,CAAC,CAAC;IACrD,OAAO;QACL,UAAU;QACV,WAAW,EAAE,IAAI,0BAAc,CAAC,UAAU,CAAC;QAC3C,GAAG,EAAE,IAAI,GAAG,CAAC,GAAG,CAAC;QACjB,eAAe,EAAE,EAAE;QACnB,QAAQ,EAAE,IAAI,0BAAU,EAAE;KAC3B,CAAC;AACJ,CAAC;AAUD;;;;;GAKG;AACI,KAAK,UAAU,QAAQ,CAAI,QAAkB;IAClD,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;AAC3C,CAAC"}
+{"version":3,"file":"http.js","sourceRoot":"","sources":["../../../src/tests/internal/http.ts"],"names":[],"mappings":";;;AAaA,oDAWC;AASD,gDAOC;AAYD,4BAKC;AAzDD,sCAAsC;AACtC,yCAA4D;AAC5D,uCAAkC;AAClC,6BAAwB;AACxB,6DAA4E;AAE5E;;;;;;GAMG;AACH,SAAgB,oBAAoB,CAClC,GAAG,GAAG,mBAAmB;IAEzB,MAAM,UAAU,GAAG,IAAI,2BAAe,CAAC,IAAI,iBAAM,EAAE,CAAC,CAAC;IACrD,OAAO;QACL,UAAU;QACV,WAAW,EAAE,IAAI,0BAAc,CAAC,UAAU,CAAC;QAC3C,GAAG,EAAE,IAAI,GAAG,CAAC,GAAG,CAAC;QACjB,eAAe,EAAE,EAAE;QACnB,QAAQ,EAAE,IAAI,0BAAU,EAAE;KAC3B,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,kBAAkB,CAAwB,GAAQ;IAChE,OAAO,OAAC,CAAC,WAAW,CAAC;QACnB,OAAO,EAAE,OAAC,CAAC,KAAK,CAAC,GAAG,CAAC;QACrB,KAAK,EAAE,OAAC,CAAC,MAAM,EAAE;QACjB,MAAM,EAAE,OAAC,CAAC,MAAM,EAAE;QAClB,KAAK,EAAE,OAAC,CAAC,MAAM,EAAE;KAClB,CAAC,CAAC;AACL,CAAC;AAED,mEAAmE;AACtD,QAAA,gBAAgB,GAAG,OAAC,CAAC,WAAW,CAAC,EAAE,GAAG,EAAE,OAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;AAEnE;;;;;;GAMG;AACI,KAAK,UAAU,QAAQ,CAC5B,MAAc,EACd,QAAkB;IAElB,OAAO,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;AACzD,CAAC"}

package/dist/tests/internal/shop-schema.d.ts

@@ -63,18 +63,20 @@ declare const CustomerModel_base: {
         readonly table: import("@antelopejs/interface-database").Table<Customer>;
         readonly database: import("@antelopejs/interface-database").SchemaInstance<any>;
         get(id: string): PromiseLike<Customer | undefined>;
-        getBy(index: keyof Customer, ...keys: any[]): PromiseLike<Customer[]>;
+        getBy(index: keyof Customer, ...keys: import("@antelopejs/interface-database-decorators").IndexKey[]): PromiseLike<Customer[]>;
         getAll(): PromiseLike<Customer[]>;
         insert(obj: import("@antelopejs/interface-database-decorators").DeepPartial<Customer> | import("@antelopejs/interface-database-decorators").DeepPartial<Customer>[], options?: import("@antelopejs/interface-database-decorators").ValidateOptions): Promise<string[]>;
         update(id: string, obj: import("@antelopejs/interface-database-decorators").DeepPartial<Customer>, options?: import("@antelopejs/interface-database-decorators").ValidateOptions): Promise<number>;
-        update(obj: import("@antelopejs/interface-database-decorators").DeepPartial<Customer>, options?: import("@antelopejs/interface-database-decorators").ValidateOptions): Promise<number>;
+        update(obj: import("@antelopejs/interface-database-decorators").DeepPartial<Customer> & {
+            _id: string;
+        }, options?: import("@antelopejs/interface-database-decorators").ValidateOptions): Promise<number>;
         delete(id: string): Promise<number>;
     };
-    readonly schemaName: string;
+    readonly schemaName: string | undefined;
     readonly tableClass: import("@antelopejs/interface-database-decorators").Constructible<Customer>;
-    fromPlainData(obj: any): Customer;
+    fromPlainData(obj: Customer | import("@antelopejs/interface-database-decorators").PlainData<Customer>): Customer;
     fromDatabase(obj: any): Customer | undefined;
-    toDatabase(obj: any): Record<string, any>;
+    toDatabase(obj: Customer | import("@antelopejs/interface-database-decorators").PlainData<Customer>): import("@antelopejs/interface-database-decorators").StoredRow<Customer>;
     validate(obj: unknown, options?: import("@antelopejs/interface-database-decorators").ValidateInputOptions): import("@antelopejs/interface-database-decorators").ValidationResult;
 };
 export declare class CustomerModel extends CustomerModel_base {
@@ -84,18 +86,20 @@ declare const ProductModel_base: {
         readonly table: import("@antelopejs/interface-database").Table<Product>;
         readonly database: import("@antelopejs/interface-database").SchemaInstance<any>;
         get(id: string): PromiseLike<Product | undefined>;
-        getBy(index: keyof Product, ...keys: any[]): PromiseLike<Product[]>;
+        getBy(index: keyof Product, ...keys: import("@antelopejs/interface-database-decorators").IndexKey[]): PromiseLike<Product[]>;
         getAll(): PromiseLike<Product[]>;
         insert(obj: import("@antelopejs/interface-database-decorators").DeepPartial<Product> | import("@antelopejs/interface-database-decorators").DeepPartial<Product>[], options?: import("@antelopejs/interface-database-decorators").ValidateOptions): Promise<string[]>;
         update(id: string, obj: import("@antelopejs/interface-database-decorators").DeepPartial<Product>, options?: import("@antelopejs/interface-database-decorators").ValidateOptions): Promise<number>;
-        update(obj: import("@antelopejs/interface-database-decorators").DeepPartial<Product>, options?: import("@antelopejs/interface-database-decorators").ValidateOptions): Promise<number>;
+        update(obj: import("@antelopejs/interface-database-decorators").DeepPartial<Product> & {
+            _id: string;
+        }, options?: import("@antelopejs/interface-database-decorators").ValidateOptions): Promise<number>;
         delete(id: string): Promise<number>;
     };
-    readonly schemaName: string;
+    readonly schemaName: string | undefined;
     readonly tableClass: import("@antelopejs/interface-database-decorators").Constructible<Product>;
-    fromPlainData(obj: any): Product;
+    fromPlainData(obj: Product | import("@antelopejs/interface-database-decorators").PlainData<Product>): Product;
     fromDatabase(obj: any): Product | undefined;
-    toDatabase(obj: any): Record<string, any>;
+    toDatabase(obj: Product | import("@antelopejs/interface-database-decorators").PlainData<Product>): import("@antelopejs/interface-database-decorators").StoredRow<Product>;
     validate(obj: unknown, options?: import("@antelopejs/interface-database-decorators").ValidateInputOptions): import("@antelopejs/interface-database-decorators").ValidationResult;
 };
 export declare class ProductModel extends ProductModel_base {
@@ -105,18 +109,20 @@ declare const OrderModel_base: {
         readonly table: import("@antelopejs/interface-database").Table<Order>;
         readonly database: import("@antelopejs/interface-database").SchemaInstance<any>;
         get(id: string): PromiseLike<Order | undefined>;
-        getBy(index: keyof Order, ...keys: any[]): PromiseLike<Order[]>;
+        getBy(index: keyof Order, ...keys: import("@antelopejs/interface-database-decorators").IndexKey[]): PromiseLike<Order[]>;
         getAll(): PromiseLike<Order[]>;
         insert(obj: import("@antelopejs/interface-database-decorators").DeepPartial<Order> | import("@antelopejs/interface-database-decorators").DeepPartial<Order>[], options?: import("@antelopejs/interface-database-decorators").ValidateOptions): Promise<string[]>;
         update(id: string, obj: import("@antelopejs/interface-database-decorators").DeepPartial<Order>, options?: import("@antelopejs/interface-database-decorators").ValidateOptions): Promise<number>;
-        update(obj: import("@antelopejs/interface-database-decorators").DeepPartial<Order>, options?: import("@antelopejs/interface-database-decorators").ValidateOptions): Promise<number>;
+        update(obj: import("@antelopejs/interface-database-decorators").DeepPartial<Order> & {
+            _id: string;
+        }, options?: import("@antelopejs/interface-database-decorators").ValidateOptions): Promise<number>;
         delete(id: string): Promise<number>;
     };
-    readonly schemaName: string;
+    readonly schemaName: string | undefined;
     readonly tableClass: import("@antelopejs/interface-database-decorators").Constructible<Order>;
-    fromPlainData(obj: any): Order;
+    fromPlainData(obj: Order | import("@antelopejs/interface-database-decorators").PlainData<Order>): Order;
     fromDatabase(obj: any): Order | undefined;
-    toDatabase(obj: any): Record<string, any>;
+    toDatabase(obj: Order | import("@antelopejs/interface-database-decorators").PlainData<Order>): import("@antelopejs/interface-database-decorators").StoredRow<Order>;
     validate(obj: unknown, options?: import("@antelopejs/interface-database-decorators").ValidateInputOptions): import("@antelopejs/interface-database-decorators").ValidationResult;
 };
 export declare class OrderModel extends OrderModel_base {
@@ -126,18 +132,20 @@ declare const OrderItemModel_base: {
         readonly table: import("@antelopejs/interface-database").Table<OrderItem>;
         readonly database: import("@antelopejs/interface-database").SchemaInstance<any>;
         get(id: string): PromiseLike<OrderItem | undefined>;
-        getBy(index: keyof OrderItem, ...keys: any[]): PromiseLike<OrderItem[]>;
+        getBy(index: keyof OrderItem, ...keys: import("@antelopejs/interface-database-decorators").IndexKey[]): PromiseLike<OrderItem[]>;
         getAll(): PromiseLike<OrderItem[]>;
         insert(obj: import("@antelopejs/interface-database-decorators").DeepPartial<OrderItem> | import("@antelopejs/interface-database-decorators").DeepPartial<OrderItem>[], options?: import("@antelopejs/interface-database-decorators").ValidateOptions): Promise<string[]>;
         update(id: string, obj: import("@antelopejs/interface-database-decorators").DeepPartial<OrderItem>, options?: import("@antelopejs/interface-database-decorators").ValidateOptions): Promise<number>;
-        update(obj: import("@antelopejs/interface-database-decorators").DeepPartial<OrderItem>, options?: import("@antelopejs/interface-database-decorators").ValidateOptions): Promise<number>;
+        update(obj: import("@antelopejs/interface-database-decorators").DeepPartial<OrderItem> & {
+            _id: string;
+        }, options?: import("@antelopejs/interface-database-decorators").ValidateOptions): Promise<number>;
         delete(id: string): Promise<number>;
     };
-    readonly schemaName: string;
+    readonly schemaName: string | undefined;
     readonly tableClass: import("@antelopejs/interface-database-decorators").Constructible<OrderItem>;
-    fromPlainData(obj: any): OrderItem;
+    fromPlainData(obj: OrderItem | import("@antelopejs/interface-database-decorators").PlainData<OrderItem>): OrderItem;
     fromDatabase(obj: any): OrderItem | undefined;
-    toDatabase(obj: any): Record<string, any>;
+    toDatabase(obj: OrderItem | import("@antelopejs/interface-database-decorators").PlainData<OrderItem>): import("@antelopejs/interface-database-decorators").StoredRow<OrderItem>;
     validate(obj: unknown, options?: import("@antelopejs/interface-database-decorators").ValidateInputOptions): import("@antelopejs/interface-database-decorators").ValidationResult;
 };
 export declare class OrderItemModel extends OrderItemModel_base {

package/dist/tests/utils.d.ts

@@ -1,4 +1,4 @@
-import type { FieldValue, FieldValues } from "../metadata";
+import type { FieldValue } from "../metadata";
 /**
  * Returns the name of the test function that called it.
  *
@@ -13,12 +13,10 @@ export declare function getRequest(functionName: string, queryParams?: Record<st
 export declare function listRequest(functionName: string, queryParams?: Record<string, string>): Promise<Response>;
 export declare function editRequest(functionName: string, payload: FieldValue, queryParams?: Record<string, string>): Promise<Response>;
 export declare function deleteRequest(functionName: string, queryParams?: Record<string, string>): Promise<Response>;
-export declare function validateObject<T>(object: T, expectedObject: Partial<T>, fieldsToCheck: (keyof T)[]): Promise<void>;
+export declare function validateObject<T, E>(object: T, expectedObject: Partial<E>, fieldsToCheck: (keyof T & keyof E)[]): Promise<void>;
 export declare function getSchemaInstance(schemaName: string): import("@antelopejs/interface-database").SchemaInstance<any>;
 export declare function validateObjectList<T extends {
     _id: string;
-}>(objectList: T[], expectedObjectList: Partial<T>[], fieldsToCheck: (keyof T)[]): Promise<void>;
-/** What the `new` route answers: the created row, with its key. */
-export interface CreatedRow extends FieldValues {
-    _id: string;
-}
+}, E extends {
+    _id?: unknown;
+}>(objectList: T[], expectedObjectList: Partial<E>[], fieldsToCheck: (keyof T & keyof E)[]): Promise<void>;

package/dist/tests/utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../src/tests/utils.ts"],"names":[],"mappings":";;;;;AA+DA,0CAGC;AAED,0BAiBC;AAED,gCAMC;AAED,gCAKC;AAED,kCAKC;AAED,kCAMC;AAED,sCAWC;AAED,wCAQC;AAED,8CAIC;AAED,gDAcC;AAhKD,0DAA6B;AAC7B,+BAA8B;AAC9B,uEAAwD;AAIxD,2CAAuC;AAEvC,MAAM,qBAAqB,GAAG,SAAS,CAAC;AACxC,MAAM,mBAAmB,GAAG,mBAAmB,CAAC;AAChD,MAAM,mBAAmB,GAAG,GAAG,SAAS,GAAG,mBAAI,CAAC,GAAG,EAAE,CAAC;AAEtD,SAAS,aAAa,CACpB,MAAa,EACb,SAA4B;IAE5B,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,SAAS,cAAc,CAAC,KAAc;IACpC,OAAO,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAC9B,CAAC;AAED,SAAS,oBAAoB,CAC3B,QAAgB,EAChB,UAA0C;IAE1C,IAAI,CAAC,UAAU,EAAE,CAAC;QAChB,OAAO,CAAC,cAAc,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;QACxC,OAAO;IACT,CAAC;IACD,MAAM,CAAC,cAAc,CAAC,KAAK,EAAE,QAAQ,EAAE,UAAU,CAAC,CAAC;AACrD,CAAC;AAED,SAAS,gBAAgB;IACvB,MAAM,EAAE,eAAe,EAAE,GAAG,KAAK,CAAC;IAClC,MAAM,iBAAiB,GAAG,MAAM,CAAC,wBAAwB,CACvD,KAAK,EACL,mBAAmB,CACpB,CAAC;IACF,KAAK,CAAC,eAAe,GAAG,QAAQ,CAAC;IACjC,KAAK,CAAC,iBAAiB,GAAG,aAAa,CAAC;IACxC,IAAI,CAAC;QACH,MAAM,KAAK,GAAY,IAAI,KAAK,EAAE,CAAC,KAAK,CAAC;QACzC,OAAO,cAAc,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;IAC5C,CAAC;YAAS,CAAC;QACT,oBAAoB,CAAC,mBAAmB,EAAE,iBAAiB,CAAC,CAAC;QAC7D,KAAK,CAAC,eAAe,GAAG,eAAe,CAAC;IAC1C,CAAC;AACH,CAAC;AAED,SAAS,cAAc,CAAC,QAAyB;IAC/C,MAAM,QAAQ,GAAG,QAAQ,CAAC,WAAW,EAAE,CAAC;IACxC,OAAO,QAAQ,KAAK,UAAU,IAAI,CAAC,CAAC,QAAQ,EAAE,UAAU,CAAC,mBAAmB,CAAC,CAAC;AAChF,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,eAAe;IAC7B,MAAM,MAAM,GAAG,gBAAgB,EAAE,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;IACvD,OAAO,MAAM,EAAE,eAAe,EAAE,IAAI,qBAAqB,CAAC;AAC5D,CAAC;AAEM,KAAK,UAAU,OAAO,CAC3B,YAAoB,EACpB,GAAW,EACX,MAAc,EACd,OAAoB,EACpB,WAAyD;IAEzD,OAAO,MAAM,KAAK,CAChB,GAAG,oBAAQ,IAAI,YAAY,IAAI,GAAG,IAAI,IAAI,eAAe,CAAC,WAAW,CAAC,CAAC,QAAQ,EAAE,EAAE,EACnF;QACE,MAAM;QACN,OAAO,EAAE;YACP,cAAc,EAAE,kBAAkB;SACnC;QACD,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,SAAS;KACpD,CACF,CAAC;AACJ,CAAC;AAEM,KAAK,UAAU,UAAU,CAC9B,YAAoB,EACpB,OAAmB,EACnB,WAAoC;IAEpC,OAAO,MAAM,OAAO,CAAC,YAAY,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,CAAC,CAAC;AAC1E,CAAC;AAEM,KAAK,UAAU,UAAU,CAC9B,YAAoB,EACpB,WAAoC;IAEpC,OAAO,MAAM,OAAO,CAAC,YAAY,EAAE,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,WAAW,CAAC,CAAC;AAC3E,CAAC;AAEM,KAAK,UAAU,WAAW,CAC/B,YAAoB,EACpB,WAAoC;IAEpC,OAAO,MAAM,OAAO,CAAC,YAAY,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,WAAW,CAAC,CAAC;AAC5E,CAAC;AAEM,KAAK,UAAU,WAAW,CAC/B,YAAoB,EACpB,OAAmB,EACnB,WAAoC;IAEpC,OAAO,MAAM,OAAO,CAAC,YAAY,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,WAAW,CAAC,CAAC;AAC1E,CAAC;AAEM,KAAK,UAAU,aAAa,CACjC,YAAoB,EACpB,WAAoC;IAEpC,OAAO,MAAM,OAAO,CAClB,YAAY,EACZ,QAAQ,EACR,QAAQ,EACR,SAAS,EACT,WAAW,CACZ,CAAC;AACJ,CAAC;AAEM,KAAK,UAAU,cAAc,CAClC,MAAS,EACT,cAA0B,EAC1B,aAA0B;IAE1B,KAAK,MAAM,KAAK,IAAI,aAAa,EAAE,CAAC;QAClC,IAAA,aAAM,EAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC,CAAC;IAC7D,CAAC;AACH,CAAC;AAED,SAAgB,iBAAiB,CAAC,UAAkB;IAClD,MAAM,MAAM,GAAG,2BAAM,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;IACtC,IAAI,CAAC,MAAM;QAAE,MAAM,IAAI,KAAK,CAAC,WAAW,UAAU,aAAa,CAAC,CAAC;IACjE,OAAO,MAAM,CAAC,QAAQ,EAAE,CAAC;AAC3B,CAAC;AAEM,KAAK,UAAU,kBAAkB,CACtC,UAAe,EACf,kBAAgC,EAChC,aAA0B;IAE1B,KAAK,MAAM,MAAM,IAAI,UAAU,EAAE,CAAC;QAChC,MAAM,EAAE,GAAG,MAAM,CAAC,GAAG,CAAC;QACtB,MAAM,cAAc,GAAG,kBAAkB,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,KAAK,EAAE,CAAC,CAAC;QAC1E,IAAI,CAAC,cAAc,EAAE,CAAC;YACpB,IAAA,aAAM,EAAC,KAAK,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,IAAI,EAAE,qCAAqC,EAAE,EAAE,CAAC,CAAC;QAC1E,CAAC;aAAM,CAAC;YACN,MAAM,cAAc,CAAC,MAAM,EAAE,cAAc,EAAE,aAAa,CAAC,CAAC;QAC9D,CAAC;IACH,CAAC;AACH,CAAC"}
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../src/tests/utils.ts"],"names":[],"mappings":"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"}

package/docs/1.introduction.md

@@ -1,21 +1,27 @@
-# Expose database records through an API
+---
+title: Expose database records through an API
+description: Build a first data controller that serves CRUD routes for a users table, then check which fields it reads and writes.
+mode: tutorial
+---
 
 ## Overview
 
-Use `@antelopejs/interface-data-api` to expose a table through named CRUD routes and an explicit field policy. A data controller connects the table model to HTTP handlers; its metadata decides which fields clients may read, write, list, and filter.
+In this tutorial, we expose a `users` table through five CRUD routes with `@antelopejs/interface-data-api`. A data controller connects the table model to HTTP handlers. Its metadata decides which fields clients can read, write, list and filter.
 
 ## Build one resource first
 
-1. **Prepare the database.** Define a table and register its schema with database-decorators. Your AntelopeJS module needs a database provider and an API provider.
-2. **Choose the routes.** Start with the [route set](./3.routes.md) your clients need, rather than exposing every write operation by default.
-3. **Set the field policy.** Add [access rights](./4.access-rights.md), [validators](./5.validators.md), and [list fields](./6.listable.md). Field permissions are not user authentication or row-level authorization.
-4. **Check one read and one rejected write.** Confirm the response excludes private fields and that invalid input cannot reach storage. Then add [relationships](./7.foreign-keys.md) and [filters](./8.filters.md).
+We build one resource in four steps.
 
-## Quick Start
+1. **Prepare the database.** Define a table and register its schema with database-decorators. The AntelopeJS project needs a database module and an API module.
+2. **Choose the routes.** Start with the [route set](./3.routes.md) your clients need, instead of exposing every write route by default.
+3. **Set the field policy.** Add [access rights](./4.access-rights.md), [validators](./5.validators.md) and [list fields](./6.listable.md). Field permissions do not authenticate users and do not authorize access to rows.
+4. **Check one read and one rejected write.** Confirm that the response leaves out private fields and that invalid input never reaches storage. Then add [relationships](./7.foreign-keys.md) and [filters](./8.filters.md).
 
-The following example declares all five CRUD routes for a `users` table. It assumes a configured provider and an existing `my-database` instance. Import the table declaration before calling `await RegisterSchema("myapp")` in the declaring module's initialization; await that setup before serving requests.
+## Quick start
 
-This is a field-policy example, not a production account system: write-only prevents a password from appearing in responses, but does not hash it or authenticate requests. Add an appropriate [database modifier](./9.modifiers.md) and your authentication policy before accepting real credentials.
+The example declares all five CRUD routes for a `users` table. It assumes a configured database module and an existing `my-database` instance. Import the table declaration, then `await RegisterSchema("myapp")` when the declaring module initializes. Wait for that setup to finish before the module serves requests.
+
+This example sets a field policy. It is not a production account system. `AccessMode.WriteOnly` keeps the password out of responses, but it does not hash the password or authenticate requests. Add a [database modifier](./9.modifiers.md) and your authentication policy before you accept real credentials.
 
 ```ts docs-check
 import { Controller } from "@antelopejs/interface-api";
@@ -40,7 +46,6 @@ import {
   Table,
 } from "@antelopejs/interface-database-decorators";
 
-// Define the database table
 @RegisterTable("users", "myapp")
 class User extends Table {
   @Field("string")
@@ -57,10 +62,8 @@ class User extends Table {
   declare password: string;
 }
 
-// Create the database model
 class UserModel extends BasicDataModel(User, "users") {}
 
-// Create the data controller
 @RegisterDataController()
 class UserAPI extends DataController(
   User,
@@ -91,38 +94,38 @@ class UserAPI extends DataController(
 }
 ```
 
-This generates the following REST endpoints:
+The controller serves these REST endpoints.
 
-| Method | Endpoint                | Description                |
-| ------ | ----------------------- | -------------------------- |
-| GET    | `/users/get?id=<id>`    | Retrieve a single user     |
-| GET    | `/users/list?limit=10`  | List users with pagination |
-| POST   | `/users/new`            | Create a new user          |
-| PUT    | `/users/edit?id=<id>`   | Update an existing user    |
-| DELETE | `/users/delete?id=<id>` | Delete a user              |
+| Method | Endpoint                | Description          |
+| ------ | ----------------------- | -------------------- |
+| GET    | `/users/get?id=<id>`    | Read one user        |
+| GET    | `/users/list?limit=10`  | List users, one page |
+| POST   | `/users/new`            | Create a user        |
+| PUT    | `/users/edit?id=<id>`   | Update a user        |
+| DELETE | `/users/delete?id=<id>` | Delete a user        |
 
 ### Check the field policy
 
-Use disposable data and your configured API base URL. Create a user with `name`, `email`, and a dummy `password`; the response is an array of inserted IDs. Use the first ID for the following checks:
+Use disposable data and the base URL of your API module. First, create a user with `POST /users/new` and a body that holds `name`, `email` and a dummy `password`. The response is the created user, with its `_id` and without `password`. Use that `_id` in the next checks.
 
-1. `GET /users/get?id=<id>` returns the readable fields, never `password`.
-2. `GET /users/list?limit=10` includes `_id`, `name`, and `email` in `results`.
-3. `PUT /users/edit?id=<id>` with `{ "name": "Updated" }` preserves the omitted email. With `{ "email": "" }`, it returns `400` because email is mandatory on edit.
+1. `GET /users/get?id=<id>` returns the readable fields. You see `_id`, `email` and `name`, and never `password`.
+2. `GET /users/list?limit=10` returns `_id`, `name` and `email` for each entry of `results`.
+3. `PUT /users/edit?id=<id>` with `{ "name": "Updated" }` keeps the email you did not send. With `{ "email": "" }`, the route answers `400`, because `email` is mandatory on `edit`.
 
-`@Mandatory` does not check email syntax or password strength. Add [validators](./5.validators.md) before accepting untrusted input.
+`@Mandatory` does not check the email syntax or the password strength. Add [validators](./5.validators.md) before you accept untrusted input.
 
 ## Core guides
 
-- [Data Controllers](./2.data-controllers.md) - Create and configure data controllers
-- [Routes](./3.routes.md) - Default routes, custom routes, and route options
-- [Access Rights](./4.access-rights.md) - Control field read/write permissions
-- [Validators](./5.validators.md) - Field-level validation and mandatory fields
-- [Listable Fields](./6.listable.md) - Pagination, pluck modes, and sorting
+- [Data controllers](./2.data-controllers.md). Create and configure data controllers.
+- [Routes](./3.routes.md). Default routes, custom routes and route options.
+- [Access rights](./4.access-rights.md). Which fields each action reads and writes.
+- [Validators](./5.validators.md). Field validation and mandatory fields.
+- [Listable fields](./6.listable.md). Pagination, pluck modes and sorting.
 
 ## Relationships and advanced queries
 
-- [Foreign Keys](./7.foreign-keys.md) - Establish relationships between tables
-- [Filters](./8.filters.md) - Add filtering capabilities to list endpoints
-- [Modifiers](./9.modifiers.md) - Automatic data transformation with database-decorators
-- [Joined Fields](./10.joined.md) - Flatten a remote field onto rows for native sort/filter
-- [Computed Fields](./11.computed.md) - In-database computed values, sortable and pageable natively
+- [Foreign keys](./7.foreign-keys.md). Relations between tables.
+- [Filters](./8.filters.md). Filters on list endpoints.
+- [Modifiers](./9.modifiers.md). Data transformation with database-decorators modifiers.
+- [Joined fields](./10.joined.md). A remote field flattened onto each row, sortable and filterable in the database.
+- [Computed fields](./11.computed.md). Values computed in the database, sortable and pageable there.

package/docs/10.joined.md

@@ -1,18 +1,22 @@
-# Joined Fields
+---
+title: Joined fields
+description: Flatten one field of another table onto each row with @Joined, so list requests sort and filter on it in the database.
+mode: reference
+---
 
 ## Overview
 
-The `@Joined` decorator imports a single scalar field from another table and flattens it onto each row at query time. Unlike `@Foreign`, which embeds the full referenced record as a nested object in the response, `@Joined` copies one remote field to the top level of the row before sorting and filtering are applied. This makes the joined field natively sortable, filterable, and searchable in the database.
+The `@Joined` decorator copies one scalar field from another table onto each row at query time. `@Foreign` nests the whole referenced record under the field. `@Joined` puts one remote field at the top level of the row, before the list query sorts and filters. The database can therefore sort, filter, and search on the joined field.
 
-Joined fields are read-only: the value is set by a lookup at query time and is never persisted on the controller's own table. Declaring a field as joined automatically sets its access mode to read-only and forces non-indexed sorting.
+Joined fields are meant to be read-only. A lookup sets the value at query time, and the controller's own table never stores it. `@Joined` sets the field's access mode to read-only when it runs. An `@Access` written above it runs later and replaces that mode, so do not combine the two. `@Joined` also makes the field's sort non-indexed, whatever the decorator order.
 
-## Basic Usage
+## Basic usage
 
-Apply `@Joined` to a field that should be populated from a remote table. The local row must carry a foreign key (`localKey`) that matches the remote table's `remoteIndex`.
+Apply `@Joined` to a field that takes its value from a remote table. The local row must hold a key (`localKey`) that matches the remote table's `remoteIndex`.
 
-Use [foreign keys](./7.foreign-keys.md) when the response needs a nested record instead. The snippets below assume the controller imports and model from the [quick start](./1.introduction.md#quick-start), with `myapp` registered before requests are served.
+Use [foreign keys](./7.foreign-keys.md) when the response needs a nested record instead. The snippets below assume the controller imports and the model from the [quick start](./1.introduction.md#quick-start), with `myapp` registered before the module serves requests.
 
-```typescript
+```typescript fragment
 import { Joined } from "@antelopejs/interface-data-api/metadata";
 import {
   Field,
@@ -84,25 +88,27 @@ A GET request to `/orders/get?id=order-123` returns the joined value at the top
 }
 ```
 
-## Decorator Parameters
+## Decorator parameters
 
-```typescript
+```typescript fragment
 @Joined({ table, localKey, remoteField, remoteIndex?, schema? })
 ```
 
 | Option        | Type                       | Required | Default           | Description                                                                                        |
 | ------------- | -------------------------- | -------- | ----------------- | -------------------------------------------------------------------------------------------------- |
-| `table`       | `Class<Table>` or `string` | Yes      | -                 | The remote table class or registered table name string                                             |
-| `localKey`    | `string`                   | Yes      | -                 | The field on the local row holding the value matched against the remote table                      |
-| `remoteField` | `string`                   | Yes      | -                 | The remote field whose value is flattened onto the row                                             |
+| `table`       | `Class<Table>` or `string` | Yes      | None              | The remote table class or registered table name string                                             |
+| `localKey`    | `string`                   | Yes      | None              | The field on the local row holding the value matched against the remote table                      |
+| `remoteField` | `string`                   | Yes      | None              | The remote field whose value is flattened onto the row                                             |
 | `remoteIndex` | `string`                   | No       | `"_id"`           | The index on the remote table to match `localKey` against                                          |
 | `schema`      | `string`                   | No       | Controller schema | Name of the schema the remote table is registered in, when it differs from the controller's schema |
 
-## Sorting and Filtering
+When a list mode includes a joined field, the mode also selects the field's `localKey`.
 
-Because the join is applied to the underlying query before sorting and filtering, joined fields behave like native columns. Combine `@Joined` with `@Sortable` or `@Filter` to order or filter by the imported value.
+## Sorting and filtering
 
-```typescript
+The list query applies the join before it sorts and filters, so a joined field behaves like a stored column. Combine `@Joined` with `@Sortable` or `@Filter` to sort or filter on the joined value.
+
+```typescript fragment
 @Sortable()
 @Filter()
 @Joined({
@@ -113,30 +119,35 @@ Because the join is applied to the underlying query before sorting and filtering
 declare userName: string;
 ```
 
-Joined fields are always sorted without a database index (`@Sortable` is forced to non-indexed for them), since the value comes from a runtime lookup rather than a stored column.
+A joined field always sorts without a database index, because its value comes from a lookup at query time and not from a stored column. `@Sortable` on a joined field is always non-indexed.
 
-## Deferred Resolution on Lists
+## Deferred resolution on lists
 
-The default list route handles this scheduling for you. Continue with [cross-schema joins](#cross-schema-joins) unless you are building a custom route with `Query.List`.
+The default list route schedules the lookups itself. Skip to [cross-schema joins](#cross-schema-joins) unless you are building a custom route with `Query.List`.
 
-![Joined fields used by filters are resolved before counting; sort fields before paging; display-only fields after paging in the default list route.](./assets/joined-list.svg){width="480"}
+![Joined fields used by filters are resolved before counting; sort fields before paging; display-only fields after paging in the default list route.](./assets/joined-list.svg "illustration"){width="480"}
 
 ### Advanced: composing `Query.List`
 
-`Query.List` only materializes the joined groups that the request's sort or filters reference before the count. The remaining display-only groups are deferred: the returned stream resolves them itself as soon as an operation can observe them, so destructuring `[query, total]` alone always yields rows with every `@Joined` field resolved.
+`Query.List` resolves the joined fields that the request's filters read before it counts the rows. It resolves the joined fields that the sort reads after the count and before the sort. It defers the remaining display-only joined fields. The returned stream resolves them as soon as an operation can read rows, so destructuring `[query, total]` alone always gives rows with every `@Joined` field resolved.
 
-- Paging the stream (`slice`, `nth`) appends the lookups after the page boundary, so they only run on the returned rows.
-- A bare `count()` — and any field aggregate (`sum`, `min`, `distinct(field)`, ...) on a non-joined field — skips them entirely (left-join lookups never change the row count nor other fields).
-- `changes()` attaches to the raw stream, since change feeds cannot carry the join lookups.
-- Any other operation (`filter`, `orderBy`, `map`, ...) materializes them first, since it may read the joined values.
+- Paging the stream (`slice`, `nth`) adds the lookups after the page boundary, so they run only on the returned rows.
+- A bare `count()` skips the lookups, and so does a field aggregate such as `sum`, `min`, or `distinct(field)` on a field that is not joined. A left-join lookup never changes the row count or the other fields.
+- `changes()` attaches to the raw stream, because change feeds cannot carry the join lookups.
+- Any other operation, such as `filter`, `orderBy`, or `map`, resolves the lookups first, because it may read the joined values.
 
-The page-only benefit therefore holds as long as paging is the first thing the caller does. An operation applied to the whole stream before paging — a filter, a sort, or the `lookup` that `Query.Foreign` stages for a `@Foreign` field — materializes the joined groups over the whole matched set instead. The lookups still stay out of the count pipeline, but a caller that wants them strictly on the page must pass `{ exposeDeferredJoined: true }` to `Query.List` and resolve them itself after the slice: the raw stream is then returned unchanged and the third tuple element names the joined fields left to resolve with `Query.Joined`. This is what the default list route does, which also lets it limit the page lookups to the plucked fields.
+The lookups therefore run on the page only when paging is the first operation the caller applies. An operation on the whole stream before paging resolves the joined fields over the whole matched set. Such operations include a filter, a sort, and the `lookup` that `Query.Foreign` adds for a `@Foreign` field. The lookups still stay out of the count. A caller that wants them on the page only must pass `{ exposeDeferredJoined: true }` to `Query.List` and resolve them after the slice. `Query.List` then returns the raw stream unchanged, and the third tuple element names the joined fields to resolve with `Query.Joined`. The default list route works this way, which also lets it limit the page lookups to the plucked fields.
 
 ### Reading a page: `Query.ListPage`
 
-A custom list route over `Query.List` reads its page with `Query.ListPage` rather than chaining the steps itself. It slices the stream, then resolves on the page only, in this order: the deferred joined groups, the `@Computed` fields the filters and the sort did not already merge, the `@Foreign` relations (last, since a computed expression may read a relation's key), and the pluck.
+A custom list route over `Query.List` reads its page with `Query.ListPage` instead of chaining the steps itself. `Query.ListPage` slices the stream, then resolves these on the page only, in this order:
+
+1. The deferred joined fields.
+2. The `@Computed` fields that the filters and the sort did not already merge.
+3. The `@Foreign` relations. They come last because a computed expression may read a relation's key.
+4. The pluck.
 
-```typescript
+```typescript fragment
 const [query, total, deferredJoined] = Query.List(
   this,
   meta,
@@ -158,11 +169,11 @@ const rows = await Query.ListPage(model.database, meta, query, {
 });
 ```
 
-## Cross-Schema Joins
+## Cross-schema joins
 
-By default, the remote table is resolved in the same schema as the controller's table. Use the `schema` option to join against a table registered in a different schema; the join is resolved through the remote table's class, against the default instance of the schema `RegisterSchema` bound it to. The remote class must be registered with `@RegisterTable` before the field is declared; a string table name with no registered class in that schema throws at declaration.
+By default, the Data API looks for the remote table in the schema of the controller's table. The `schema` option joins a table registered in a different schema. The join goes through the remote table's class, against the default instance of the schema that `RegisterSchema` bound it to. Register the remote class with `@RegisterTable` before you declare the field. A string table name with no registered class in that schema throws at declaration.
 
-```typescript
+```typescript fragment
 @Joined({
   table: "users",
   localKey: "userId",
@@ -172,17 +183,17 @@ By default, the remote table is resolved in the same schema as the controller's
 declare userName: string;
 ```
 
-When a table class is passed, its schema is inferred from its `@RegisterTable` metadata. If both the class metadata and the explicit `schema` option specify a schema and they disagree, an error is thrown.
+When you pass a table class, the Data API reads its schema from its `@RegisterTable` metadata. If the class metadata and the `schema` option name different schemas, the declaration throws.
 
-## Joined vs. Foreign
+## `@Joined` compared with `@Foreign`
 
-| Aspect              | `@Joined`                                    | `@Foreign`                                                            |
-| ------------------- | -------------------------------------------- | --------------------------------------------------------------------- |
-| Result shape        | A single scalar value flattened onto the row | The full referenced record (or plucked subset) nested under the field |
-| Access              | Read-only (enforced)                         | Configurable via `@Access`                                            |
-| Sort / filter       | Native (join applied before sort/filter)     | Not natively sortable/filterable on remote fields                     |
-| Multiple references | One remote field per decorator               | Single or array (`multi`) references                                  |
+| Aspect              | `@Joined`                                       | `@Foreign`                                                                |
+| ------------------- | ----------------------------------------------- | ------------------------------------------------------------------------- |
+| Result shape        | A single scalar value flattened onto the row    | The full referenced record, or its plucked fields, nested under the field |
+| Access              | Read-only, unless a later `@Access` replaces it | Set with `@Access`                                                        |
+| Sort and filter     | In the database, join applied before both       | No sort or filter on remote fields                                        |
+| Multiple references | One remote field per decorator                  | Single or array (`multi`) references                                      |
 
-## Next Steps
+## Next steps
 
-See the [computed fields documentation](./11.computed.md) to generalize this merge mechanism to arbitrary in-database expressions, or the [modifiers documentation](./9.modifiers.md) to learn how automatic data transformation integrates with the Data API.
+To merge any in-database expression onto rows, see [Computed fields](./11.computed.md). To see how modifiers transform data in the Data API, see [Modifiers](./9.modifiers.md).