@superpanel-sdk/runtime 0.2.3 → 0.7.0

package/dist/core/page/records-query.d.ts

@@ -0,0 +1,234 @@
+/**
+ * What a `db` read means, apart from where its rows are stored (15 §10.4, 18-record-search-index): the
+ * rows a page script and `ctx.api.db` see (`RowOut`, one `SlotOut` per field), what a `where`,
+ * `orderBy`, `after` / `skip` / `take` and `select` do to them, what a read may not say, and which of its
+ * conditions an index answers. The platform's reader (services `slot/page/records.ts`) loads its
+ * candidate rows from the database and applies these; the runtime's page unit tests
+ * (`testing.ts`) load them from the test's data and apply the same functions.
+ */
+import { type TableRelation } from '../slot/compile-schema.js';
+import { type DataType } from '../slot/schema.js';
+import type { CompiledSlotSchema, FieldValue, RuntimeFieldDef, RuntimeTableDef } from '../slot/types.js';
+export declare const RECORDS_LIMITS: {
+    /** Rows one call may reach through its anchor or the index, before any other filter. */
+    readonly rowsPerCall: 500;
+    /** `findMany` without `take`. */
+    readonly defaultTake: 100;
+    /** `skip`: further on, page with `after`. */
+    readonly maxSkip: 1000;
+    /** Values of one `in` / `notIn`. */
+    readonly listValues: 500;
+    /** `count` counts up to this many; more answer this. */
+    readonly countCap: 10000;
+    /** Rows read by one reader (a page run; one `ctx.api.db` call). */
+    readonly rowsPerRun: 5000;
+    /**
+     * Stored row data (its JSON, UTF-8 bytes) one batch of calls may read (one `ctx.api.db` call, one
+     * sandbox slice), and one reader: what keeps a read from filling this process's memory, checked
+     * before the rows are loaded (34 §8).
+     */
+    readonly bytesPerCall: number;
+    readonly bytesPerRun: number;
+    /** One statement of a read, in milliseconds: past it the read fails as `query_timeout` (34 §8). */
+    readonly statementMs: 3000;
+    readonly includeDepth: 3;
+};
+export type SlotState = FieldValue['state'];
+/** One field as a page script sees it (15 §10.4). */
+export type SlotOut = {
+    value: unknown;
+    state: SlotState;
+    reason: string | null;
+    updatedAt: string | null;
+    ref: {
+        table: string;
+        id: string;
+        field: string;
+    };
+    /** The target row, when the lookup was `include`d. */
+    row?: RowOut | null;
+};
+/**
+ * A row: its id and times (ISO 8601; a stored row's, not the session's), one slot per field, and the
+ * rows of each way back `include`d (`relatedName`).
+ */
+export type RowOut = {
+    id: string;
+    createdAt?: string;
+    updatedAt?: string;
+    [field: string]: SlotOut | RowOut[] | string | undefined;
+};
+export type RecordsMethod = 'findUnique' | 'findFirst' | 'findMany' | 'count';
+export type RecordsCall = {
+    table: string;
+    method: RecordsMethod;
+    args: Record<string, unknown>;
+};
+/** Why a read was refused: a read this API does not take, or one past a limit (18-record-search-index §4.10). */
+export type RecordsQueryErrorCode = 'invalid_read' | 'limit_exceeded';
+export declare class RecordsQueryError extends Error {
+    readonly code: RecordsQueryErrorCode;
+    constructor(message: string, code?: RecordsQueryErrorCode);
+}
+export declare function limitExceeded(message: string): RecordsQueryError;
+export type WhereInput = Record<string, unknown>;
+export type FindArgs = {
+    where?: unknown;
+    include?: unknown;
+    select?: unknown;
+    orderBy?: unknown;
+    take?: unknown;
+    skip?: unknown;
+    /** A row as read: the rows strictly after it in this read's order ({@link afterOf}). */
+    after?: unknown;
+    /** Replaced by `after`: refused, saying so. */
+    cursor?: unknown;
+};
+export declare const COMBINATORS: Set<string>;
+/** Prisma's list filters, on a way back (`relatedName`). */
+export declare const WAY_BACK_FILTERS: Set<string>;
+/** What an `include` of a way back may say of its rows. */
+export declare const RELATION_INCLUDE_KEYS: Set<string>;
+/**
+ * Refuses `contains` / `endsWith` as an operator anywhere in a where (under AND / OR / NOT, a `not`, a
+ * relation's filter), saying what to write instead; before anything is read, whatever path the read
+ * takes. A field may be named `contains`: the where's own keys are fields, only a condition's are
+ * operators.
+ */
+export declare function refuseSearch(tableName: string, where: unknown, path?: string): void;
+/** An anchor: `ids` the field is equal to / in. */
+export type Anchor = {
+    field: string;
+    ids: string[];
+};
+/** The fields of a read's conditions and order that are index entries (not row times): their dictionary ids are needed. */
+export declare function indexedFieldsOf(conditions: readonly IndexCondition[], order: IndexOrder | null | undefined): string[];
+/**
+ * The conditions of a where that pin it to some rows (top level and top-level AND): `id` or a ref
+ * field equal to / in some ids (15 §10.6.1).
+ */
+export declare function findAnchors(table: RuntimeTableDef, where: WhereInput): Anchor[];
+export declare function relationFilters(table: RuntimeTableDef, where: WhereInput): Array<{
+    field: string;
+    target: string;
+    sub: unknown[];
+}>;
+/** What a `where` is judged against beyond the row: `is` targets and the rows of each way back, by parent. */
+export type MatchContext = {
+    schema: CompiledSlotSchema;
+    targets: ReadonlyMap<string, RowOut>;
+    /** `relatedKey(table, relatedName)` → parent id → its rows. */
+    related: ReadonlyMap<string, ReadonlyMap<string, RowOut[]>>;
+    relationOf: (tableName: string, name: string) => TableRelation | undefined;
+};
+/** The ways back a `where` filters by (top level and inside AND / OR / NOT), with their sub-wheres. */
+export declare function wayBackFilters(tableName: string, where: WhereInput, relationOf: MatchContext['relationOf']): Array<{
+    relation: TableRelation;
+    sub: unknown[];
+}>;
+export declare function relatedKey(tableName: string, name: string): string;
+export declare function matches(context: MatchContext, tableName: string, row: RowOut, where: unknown): boolean;
+/**
+ * One key of `orderBy`: the field (a field, `id` or a row time), its direction, how its values compare,
+ * and a field's definition (none for `id` or a row time).
+ */
+export type OrderKey = {
+    field: string;
+    sign: 1 | -1;
+    order: (a: unknown, b: unknown) => number;
+    def?: RuntimeFieldDef;
+};
+export declare function orderKeys(table: RuntimeTableDef, orderBy: unknown): OrderKey[];
+/**
+ * A row's place in a read's order: its value of each order key (null or undefined: none), then its
+ * creation (ms) and id, which break ties.
+ */
+export type Place = {
+    values: unknown[];
+    created: number;
+    id: string;
+};
+/** Rows in the read's order; without keys, as they come (creation order). */
+export declare function orderRows(keys: readonly OrderKey[], rows: RowOut[]): RowOut[];
+/**
+ * `orderBy` as the database can order: null without one, the field when it is one indexed field or a
+ * row time; undefined when it cannot (several keys, `id`, a field not indexed).
+ */
+export declare function indexOrder(table: RuntimeTableDef, orderBy: unknown): IndexOrder | null | undefined;
+/** Rows in the read's order, paged: from strictly after `place`, then `skip`, then `take`. */
+export declare function pageRows(keys: readonly OrderKey[], rows: RowOut[], place: Place | undefined, args: FindArgs): RowOut[];
+/**
+ * `after`: the place a page starts after, read off a row as the reader returned it (normally the last
+ * of the page before). Taken by value, never looked up: its id only breaks ties, so a row since deleted,
+ * changed or of another tenant is only a place and discloses nothing. It needs the row's `id` and
+ * `createdAt`, and its value of each order key: `updatedAt`, or the field's slot (`{ value }`, a null
+ * value for none). A field's value must be of its type ({@link fitsField}): one the index cannot hold
+ * would otherwise place as "no value" in SQL and compare as text in memory.
+ */
+export declare function afterOf(tableName: string, keys: readonly OrderKey[], args: FindArgs): Place | undefined;
+export declare function skipOf(value: unknown): number;
+/** Every `in` / `notIn` of a where (and its AND / OR / NOT, way-back and `is` filters) within `listValues`. */
+export declare function checkListSizes(tableName: string, where: unknown): void;
+export declare function optionalCount(value: unknown, name: string): number | undefined;
+export declare function selectFields(tableName: string, table: RuntimeTableDef, row: RowOut, select: unknown): RowOut;
+export declare function toSlot(table: string, id: string, field: string, value: FieldValue): SlotOut;
+export declare function isUuid(value: unknown): value is string;
+export declare function asArray(value: unknown): unknown[];
+export declare function isPlainObject(value: unknown): value is Record<string, unknown>;
+/** A projected field as its schema declares it. */
+export type IndexedField = {
+    dataType: DataType;
+    unique: boolean;
+};
+/** The fields of one table's definition that go to the index. */
+export declare function tableIndexedFields(fields: Record<string, unknown>): Map<string, IndexedField>;
+/** An index entry's typed value columns. */
+export type IndexValue = {
+    valueText: string | null;
+    valueNum: number | null;
+    valueTime: Date | null;
+};
+/** A stored value's index columns; null when it has none to index (empty, or not of its type). */
+export declare function indexValueOf(dataType: DataType, value: unknown): IndexValue | null;
+/**
+ * One condition the database can answer: a field (through the index) or a row time (`row`, a column of
+ * `Record`), its type, and the operators on it.
+ */
+export type IndexCondition = {
+    field: string;
+    dataType: DataType;
+    ops: Record<string, unknown>;
+    insensitive: boolean;
+    row?: true;
+    /** No operators: every row with a value, in its order (a walk along the order, 34 §7). */
+    walk?: true;
+};
+/** The order a read asks for, as the index can order: one field (or a row time) and its direction. */
+export type IndexOrder = {
+    field: string;
+    dataType: DataType;
+    desc: boolean;
+    row?: true;
+};
+/**
+ * The conditions of a where the database can answer (top level and top-level AND): on indexed fields
+ * and row times. And whether they are the whole where (nothing else to check in memory). A condition
+ * on a field that is not indexed, an empty value, `not`, `notIn`, `state`, `OR` and `NOT` are left to
+ * the in-memory filter.
+ */
+export declare function indexConditions(table: RuntimeTableDef, where: WhereInput): {
+    conditions: IndexCondition[];
+    whole: boolean;
+};
+/** The conditions that can start a query; when none can, why. */
+export declare function startableConditions(conditions: readonly IndexCondition[]): {
+    candidates: IndexCondition[];
+    why: string | null;
+};
+/**
+ * Why a `where` with no anchor (`id` or a ref field equal to / in some ids) cannot be read: no condition
+ * on an indexed field or a row time starts it. Null when one does. The platform's reader and the page
+ * unit tests refuse the same reads, with this message.
+ */
+export declare function unstartableWhy(tableName: string, table: RuntimeTableDef, where: WhereInput): string | null;
+//# sourceMappingURL=records-query.d.ts.map