@antelopejs/interface-data-api 0.4.0 → 0.6.0

package/dist/metadata.d.ts

@@ -1,25 +1,11 @@
-import type { RequestContext } from "@antelopejs/interface-api";
 import type { ContainerModifier } from "@antelopejs/interface-database-decorators/modifiers/common";
-import type { Query, SchemaInstance, ValueProxy, ValueProxyOrValue } from "@antelopejs/interface-database";
 import { type Table } from "@antelopejs/interface-database-decorators";
-import { type Class, type ParameterDecorator } from "@antelopejs/interface-core/decorators";
-export type DataControllerCallback<O = any> = {
-    args: (ParameterDecorator | ParameterDecorator[])[];
-    method: string;
-    func: (ctx: any, opts: O, ...args: any[]) => any;
-};
-export type DataControllerCallbackWithOptions<O = any> = {
-    endpoint?: string;
-    options?: Partial<O>;
-    callback: DataControllerCallback<O>;
-};
-export type ExtractCallback<T> = T extends DataControllerCallbackWithOptions ? T["callback"]["func"] : T extends DataControllerCallback ? T["func"] : never;
-export type DataControllerDef = {
-    [name: string]: DataControllerCallback | DataControllerCallbackWithOptions;
-};
-export type ExtractDefCallbacks<T extends {}> = {
-    [K in keyof T]: ExtractCallback<T[K]>;
-};
+import { type Class } from "@antelopejs/interface-core/decorators";
+import type { DataControllerCallbackWithOptions, DataControllerInstance } from "./internal/controller-types";
+import type { FieldValidator, FieldData, ComputedExpression, ComputedOptions, FilterFunction, ForeignOptions, ReadableAccessFields, WritableAccessFields } from "./internal/field-types";
+export { FilterValuesOf } from "./internal/filters";
+export type { DataControllerCallback, DataControllerCallbackWithOptions, DataControllerInstance, ExtractCallback, DataControllerDef, ExtractDefCallbacks, } from "./internal/controller-types";
+export type { ForeignJoinedRef, FieldParseSuccess, FieldParseFailure, FieldParseResult, FieldValidationResult, FieldValue, FieldValues, RowFields, ForeignOptions, FieldValidator, FieldData, ComputedExpression, ComputedOptions, ComputedFieldData, FilterValue, FieldFilter, FilterFunction, ReadableAccessFields, WritableAccessFields, } from "./internal/field-types";
 /**
  * Field access mode enum.
  */
@@ -28,126 +14,6 @@ export declare enum AccessMode {
     WriteOnly = 2,
     ReadWrite = 3
 }
-/**
- * A `@Joined` field declared on the target of a relation, captured so the
- * foreign lookup can re-materialize it (joined fields are not physical columns,
- * so a plain pluck of the target table would return them empty).
- */
-export interface ForeignJoinedRef {
-    name: string;
-    table: string;
-    tableClass?: Class<Table>;
-    localKey: string;
-    remoteField: string;
-    remoteIndex: string;
-    schemaName?: string;
-}
-/**
- * DataAPI Metadata field information.
- */
-/** Parse outcome accepting the field value, carrying the value to write. */
-export interface FieldParseSuccess {
-    success: true;
-    data: unknown;
-}
-/** Parse outcome rejecting the field value. */
-export interface FieldParseFailure {
-    success: false;
-}
-/** Parse outcome of a field value, shaped like the result of zod's `safeParse`. */
-export type FieldParseResult = FieldParseSuccess | FieldParseFailure;
-/**
- * Outcome of a field validator: `true`/`false` accepts or rejects the raw
- * value, which is then written as received; a {@link FieldParseResult}
- * accepts or rejects it, and on success its `data` is written instead of the
- * raw value.
- */
-export type FieldValidationResult = boolean | FieldParseResult;
-/** Field value validator, see {@link FieldValidationResult}. */
-export type FieldValidator = (value: unknown) => FieldValidationResult | Promise<FieldValidationResult>;
-export interface FieldData {
-    /**
-     * Field name in-database.
-     */
-    dbName?: string;
-    /**
-     * Field access mode.
-     *
-     * @see {@link AccessMode}
-     */
-    mode?: AccessMode;
-    /**
-     * Field access mode overrides per DataAPI action.
-     */
-    modeOverrides?: Record<string, AccessMode>;
-    /**
-     * DB Fields that should be selected for this field.
-     */
-    listable?: Record<string, string[]>;
-    /**
-     * Set of api methods for which the field must be set.
-     */
-    mandatory?: Set<string>;
-    /**
-     * Whether the DataAPI can be sorted using this field.
-     */
-    sortable?: {
-        indexed?: boolean;
-    };
-    /**
-     * Foreign key reference.
-     *
-     * `schemaName` is set when the target lives in another schema than the
-     * controller's table; runtime resolves the foreign lookup against that
-     * schema's default instance instead of the source instance.
-     */
-    foreign?: [
-        table: string,
-        tableClass?: Class<Table>,
-        index?: string,
-        multi?: true,
-        pluck?: string[],
-        schemaName?: string,
-        targetJoined?: ForeignJoinedRef[]
-    ];
-    /**
-     * Joined-from-other-table reference.
-     *
-     * Imports a single scalar field from another table at query time and
-     * flattens it into the row, enabling sort/search/filter natively in DB.
-     *
-     * `schemaName` is set when the target lives in another schema than the
-     * controller's table; runtime resolves the join against that schema's
-     * default instance instead of the source instance.
-     */
-    joined?: {
-        table: string;
-        tableClass?: Class<Table>;
-        localKey: string;
-        remoteField: string;
-        remoteIndex: string;
-        schemaName?: string;
-    };
-    /**
-     * In-database computed value.
-     *
-     * The expression is merged into each row at query time, enabling sort,
-     * filter, and pagination natively in DB.
-     */
-    computed?: ComputedFieldData;
-    /**
-     * Value validator callback.
-     */
-    validator?: FieldValidator;
-    /**
-     * Field property descriptor.
-     */
-    desc?: PropertyDescriptor;
-    /**
-     * Whether or not an `eq` filter with this field name can use an indexed lookup.
-     */
-    indexable?: boolean;
-}
 /**
  * The access a field has in one data API action (`get`, `list`, `new`,
  * `edit`…): its {@link FieldData.modeOverrides} entry for that action, else
@@ -155,103 +21,35 @@ export interface FieldData {
  * field's own mode.
  */
 export declare function GetEffectiveMode(field: Pick<FieldData, "mode" | "modeOverrides">, action?: string): AccessMode | undefined;
-/**
- * In-database computed field expression.
- *
- * Receives the row proxy and the schema instance of the controller's table.
- * May return a row-local expression (built from `row`) or a per-row subquery
- * (ex: an aggregate over another table).
- */
-export type ComputedExpression = (row: ValueProxy<Record<string, any>>, db: SchemaInstance<any>) => ValueProxyOrValue<unknown> | Query<unknown>;
-/**
- * Computed field options.
- */
-export interface ComputedOptions {
-    /**
-     * Fallback merged over the computed value when the expression yields null
-     * (ex: `0` for an aggregate count over an empty set).
-     */
-    default?: unknown;
-}
-/**
- * Computed field information.
- */
-export interface ComputedFieldData extends ComputedOptions {
-    expr: ComputedExpression;
-}
-type Comparison = "eq" | "ne" | "gt" | "ge" | "lt" | "le";
-export type FilterValue = [value: string, mode: Comparison];
-/**
- * The filters of one field in a list request: one {@link FilterValue}, or
- * several a row must all pass (`?filter_age=ge:18&filter_age=lt:65`).
- */
-export type FieldFilter = FilterValue | FilterValue[];
-/** The filters of one field as a list, whether it holds one or several. */
-export declare function FilterValuesOf(filter: FieldFilter): FilterValue[];
-/**
- * Filter callback.
- */
-export type FilterFunction<T extends Record<string, any>, U extends Record<string, any> = Record<string, any>> = (context: RequestContext & {
-    this: T;
-}, proxy: ValueProxy<any>, key: string, value: FilterValue[0], mode: FilterValue[1], row: ValueProxy<U>) => ValueProxyOrValue<boolean>;
-export interface ReadableAccessFields {
-    getters: [string, FieldData][];
-    props: [string, FieldData][];
-}
-export interface WritableAccessFields {
-    setters: [string, FieldData][];
-    props: [string, FieldData][];
-}
 /**
  * Metadata Class containing the DataAPI information.
  */
 export declare class DataAPIMeta {
-    readonly target: Class;
-    /**
-     * Key symbol.
-     */
+    /** Key symbol. */
     static key: symbol;
-    readonly filters: Record<string, FilterFunction<any>>;
-    /**
-     * Fields information.
-     */
+    readonly filters: Record<string, FilterFunction<any, any>>;
+    /** Fields information. */
     readonly fields: Record<string, FieldData>;
-    /**
-     * Fields to pluck in listing endpoints.
-     */
+    /** Fields to pluck in listing endpoints. */
     readonly pluck: Record<string, Set<string>>;
-    /**
-     * Key of the DataAPI class containing a database table instance.
-     */
+    /** Key of the DataAPI class containing a database table instance. */
     modelKey?: string;
-    /**
-     * Keys of the DataAPI class containing database modifier keys.
-     */
+    /** Keys of the DataAPI class containing database modifier keys. */
     modifierKeys: Map<typeof ContainerModifier<any>, string>;
-    /**
-     * Schema name where the table is registered.
-     */
+    /** Schema name where the table is registered. */
     schemaName: string;
-    /**
-     * Database Schema class.
-     */
+    /** Database Schema class. */
     tableClass: Class;
-    /**
-     * Database Schema table name.
-     */
+    /** Database Schema table name. */
     tableName: string;
-    /**
-     * Readable fields.
-     */
+    /** Readable fields. */
     readonly readable: Record<string, ReadableAccessFields>;
-    /**
-     * Writeable fields.
-     */
+    /** Writeable fields. */
     readonly writable: Record<string, WritableAccessFields>;
-    /**
-     * Registered DataAPI endpoints.
-     */
+    /** Registered DataAPI endpoints. */
     readonly endpoints: Record<string, DataControllerCallbackWithOptions>;
+    /** The controller class. */
+    readonly target: Class<object>;
     constructor(target: Class);
     inherit(parent: DataAPIMeta): void;
     private field;
@@ -285,7 +83,6 @@ export declare class DataAPIMeta {
      * @param name Field name
      * @param active Sortable
      * @param noIndex Ignore database indexes
-     * @returns
      */
     setSortable(name: string, active: boolean, noIndex?: boolean): this;
     /**
@@ -325,8 +122,11 @@ export declare class DataAPIMeta {
      * @param table Other table
      * @param index Other table index
      * @param multi Index is a multi index
+     * @param targetMeta Metadata of the target's data controller. Its `@Joined`
+     *   fields that `pluck` names, or all of them when `pluck` is unset, are
+     *   resolved on the relation unless it is `multi`.
      */
-    setForeign(name: string, table: string | Class<Table>, index?: string, multi?: boolean, pluck?: string[], schema?: string, targetMeta?: DataAPIMeta): this;
+    setForeign(name: string, table: string | Class<Table>, ...[index, multi, pluck, schema, targetMeta]: ForeignOptions): this;
     /**
      * Set the validation function of a field.
      *
@@ -348,7 +148,7 @@ export declare class DataAPIMeta {
      * @param func Filter callback
      * @param index
      */
-    setFilter(name: string, func: FilterFunction<Record<string, any>, Record<string, any>>, useIndex?: boolean): this;
+    setFilter(name: string, func: FilterFunction<any, any>, useIndex?: boolean): this;
     /**
      * Sets the key containing the database table instance.
      *
@@ -463,7 +263,7 @@ export declare const Validator: (validator: FieldValidator) => import("@antelope
  * to true for the default filter and false for custom filters. An indexed
  * equality lookup uses the raw string and bypasses the callback.
  */
-export declare const Filter: <T extends Record<string, any>>(func?: FilterFunction<T, T>, useIndex?: boolean) => (target: T, propertyKey: string | symbol) => void;
+export declare function Filter<T extends Record<string, any>>(func?: FilterFunction<T, T>, useIndex?: boolean): import("@antelopejs/interface-core/decorators").PropertyDecorator;
 /**
  * Sets which field will contain the reference to the database model instance.
  */
@@ -474,5 +274,4 @@ export declare const ModelReference: () => import("@antelopejs/interface-core/de
  * @param modifierClass Modifier
  */
 export declare const ModifierKey: (modifierClass: typeof ContainerModifier<any>) => import("@antelopejs/interface-core/decorators").PropertyDecorator;
-export declare function GetDataControllerMeta(thisObj: any): DataAPIMeta;
-export {};
+export declare function GetDataControllerMeta(thisObj: DataControllerInstance): DataAPIMeta;