@infaris/data 0.0.0-stage → 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,349 @@
+/** Common base of the SDK-specific errors. Existing error names and constructors remain supported. */
+declare class InfarisError extends Error {
+    static [Symbol.hasInstance](value: unknown): boolean;
+    readonly code: string;
+    readonly status: number | null | undefined;
+    constructor(message: string, code?: string, status?: number | null | undefined);
+}
+
+/** `fetch`, or anything with its shape (tests, a fetch with retries). */
+type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
+/** A failed request: PostgREST's error (`code`, `message`, `details`, `hint`) or the gateway's (`invalid_key`, ...). */
+declare class DataApiError extends InfarisError {
+    readonly code: string;
+    readonly details: string | null;
+    readonly hint: string | null;
+    readonly status: number | null;
+    constructor(input: {
+        code: string;
+        message: string;
+        details?: string | null;
+        hint?: string | null;
+        status?: number;
+    });
+}
+/** What every query resolves to: data or an error, never both; never throws (except `throwOnError`). */
+type DataApiResponse<T> = {
+    data: T;
+    error: null;
+    count: number | null;
+    status: number;
+    statusText: string;
+} | {
+    data: null;
+    error: DataApiError;
+    count: number | null;
+    status: number;
+    statusText: string;
+};
+/** The shape `infaris-guard hosting db types` generates. */
+interface GenericTable {
+    Row: Record<string, unknown>;
+    Insert: Record<string, unknown>;
+    Update: Record<string, unknown>;
+}
+interface GenericView {
+    Row: Record<string, unknown>;
+}
+interface GenericFunction {
+    Args: Record<string, unknown>;
+    Returns: unknown;
+}
+interface GenericSchema {
+    Tables: Record<string, GenericTable>;
+    Views: Record<string, GenericView>;
+    Functions: Record<string, GenericFunction>;
+}
+/** Without generated types every table is a loose record. */
+type AnyDatabase = Record<string, GenericSchema>;
+type TableName<S extends GenericSchema> = (keyof S['Tables'] & string) | (keyof S['Views'] & string);
+type RowOf<S extends GenericSchema, T extends string> = T extends keyof S['Tables'] ? S['Tables'][T]['Row'] : T extends keyof S['Views'] ? S['Views'][T]['Row'] : Record<string, unknown>;
+interface ClientOptions {
+    /** The signed-in user's access token from Infaris Auth (role `authenticated`); null for anonymous calls. */
+    accessToken?: () => Promise<string | null> | string | null;
+    /** The schema `from()` uses by default (the first exposed one, normally `public`). */
+    schema?: string;
+    headers?: Record<string, string>;
+    fetch?: FetchLike;
+}
+
+/**
+ * The result type of a PostgREST `select` string, computed at compile time from the generated `Database` type:
+ *
+ *  - `*` and plain columns: `select('id, title')` is `{ id: number; title: string }`;
+ *  - aliases and casts: `name:title`, `price::text` (`string`), `total:amount::int` (`number`);
+ *  - JSON paths: `meta->theme` (`unknown`), `meta->>theme` (`string | null`), named after the last key;
+ *  - embedded relations over foreign keys: `author:users(name)` is one object (or `null`) for a many-to-one and
+ *    `orders(id, total)` an array for a one-to-many; `!inner` drops the `null`, `!hint` picks a foreign key;
+ *  - spreads `...users(name)` lift the embedded columns into the row;
+ *  - aggregates (with `aggregates` on): `count()`, `amount.sum()`, `amount.avg()`, `created_at.max()`.
+ *
+ * A column that does not exist becomes a string type that says so, which shows up where the value is used. Without
+ * generated types every row stays `Record<string, unknown>`.
+ */
+type SelectResult<S extends GenericSchema, N extends string, Q extends string> = string extends Q ? RowFor<S, N> : string extends keyof RowFor<S, N> ? Record<string, unknown> : Simplify<Fields<S, N, SplitTop<StripWs<Q>>>>;
+type RowFor<S extends GenericSchema, N extends string> = N extends keyof S['Tables'] ? S['Tables'][N]['Row'] : N extends keyof S['Views'] ? S['Views'][N]['Row'] : Record<string, unknown>;
+/** Readable object type in hovers. */
+type Simplify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+type Ws = ' ' | '\n' | '\t' | '\r';
+/** Whitespace out, like the client does before sending (quoted names are rare in a select). */
+type StripWs<S extends string, Out extends string = ''> = S extends `${infer C}${infer Rest}` ? StripWs<Rest, C extends Ws ? Out : `${Out}${C}`> : Out;
+/** Splits on commas outside parentheses. */
+type SplitTop<S extends string, Depth extends unknown[] = [], Cur extends string = '', Out extends string[] = []> = S extends `${infer C}${infer Rest}` ? C extends ',' ? Depth extends [] ? SplitTop<Rest, Depth, '', [...Out, Cur]> : SplitTop<Rest, Depth, `${Cur}${C}`, Out> : C extends '(' ? SplitTop<Rest, [...Depth, 0], `${Cur}${C}`, Out> : C extends ')' ? SplitTop<Rest, Depth extends [unknown, ...infer D] ? D : [], `${Cur}${C}`, Out> : SplitTop<Rest, Depth, `${Cur}${C}`, Out> : Cur extends '' ? Out : [...Out, Cur];
+type UnionToIntersection<U> = (U extends unknown ? (x: U) => void : never) extends (x: infer I) => void ? I : never;
+type Fields<S extends GenericSchema, N extends string, F extends string[]> = F extends [] ? Record<string, never> : UnionToIntersection<{
+    [I in keyof F]: F[I] extends string ? Field<S, N, F[I]> : never;
+}[number]>;
+/** One entry of the select list. */
+type Field<S extends GenericSchema, N extends string, F extends string> = F extends '*' ? RowFor<S, N> : F extends `...${infer Embed}` ? Spread<S, N, Embed> : F extends `${infer Alias}:${infer Rest}` ? Rest extends `:${string}` ? Unaliased<S, N, F> : Alias extends `${string}(${string}` ? Unaliased<S, N, F> : {
+    [K in Alias]: ValueOf<S, N, Rest>;
+} : Unaliased<S, N, F>;
+type Unaliased<S extends GenericSchema, N extends string, F extends string> = {
+    [K in NameOf<F>]: ValueOf<S, N, F>;
+};
+type Aggregate = 'sum' | 'avg' | 'min' | 'max' | 'count';
+/** `[column, function]` of an aggregate entry (`count()`, `amount.sum()`), never for an embed that holds one. */
+type AggregateOf<F extends string> = F extends `count()${string}` ? ['', 'count'] : F extends `${infer Col}.${infer Fn extends Aggregate}()${string}` ? Col extends `${string}(${string}` ? never : [Col, Fn] : never;
+/** The key PostgREST gives an entry without an alias. */
+type NameOf<F extends string> = [AggregateOf<F>] extends [never] ? PlainName<F> : AggregateOf<F>[1];
+type PlainName<F extends string> = F extends `${infer Base}::${string}` ? NameOf<Base> : F extends `${infer Rel}(${string}` ? Rel extends `${infer Name}!${string}` ? Name : Rel : F extends `${string}->${infer Path}` ? LastKey<Path> : F;
+type LastKey<P extends string> = P extends `>${infer Rest}` ? LastKey<Rest> : P extends `${string}->${infer Rest}` ? LastKey<Rest> : P;
+type Cast<T extends string> = T extends 'text' | 'varchar' | 'uuid' | 'date' | 'timestamp' | 'timestamptz' ? string : T extends 'int' | 'int2' | 'int4' | 'int8' | 'integer' | 'bigint' | 'smallint' | 'numeric' | 'float4' | 'float8' | 'real' ? number : T extends 'bool' | 'boolean' ? boolean : T extends 'json' | 'jsonb' ? unknown : unknown;
+/** The value of an entry: column, cast, JSON path, aggregate or embedded relation. */
+type ValueOf<S extends GenericSchema, N extends string, F extends string> = [AggregateOf<F>] extends [never] ? PlainValue<S, N, F> : AggregateOf<F>[1] extends 'count' | 'sum' | 'avg' ? number : ColumnValue<S, N, AggregateOf<F>[0]>;
+type PlainValue<S extends GenericSchema, N extends string, F extends string> = F extends `${infer Rel}(${infer Inner})` ? Embedded<S, N, Rel, Inner> : F extends `${infer Base}::${infer T}` ? Base extends keyof RowFor<S, N> | `${string}->${string}` ? Cast<T> | (null extends RowFor<S, N>[Base & keyof RowFor<S, N>] ? null : never) : Missing<N, Base> : F extends `${infer Col}->${infer Path}` ? Col extends keyof RowFor<S, N> ? Path extends `${string}->>${string}` | `>${string}` ? string | null : unknown : Missing<N, Col> : ColumnValue<S, N, F>;
+type ColumnValue<S extends GenericSchema, N extends string, C extends string> = C extends keyof RowFor<S, N> ? RowFor<S, N>[C] : Missing<N, C>;
+/** Shows up as the value's type wherever it is used: a compile-time hint instead of a runtime surprise. */
+type Missing<N extends string, C extends string> = `column '${C}' does not exist on '${N}'`;
+type RelationName<R extends string> = R extends `${infer Name}!${string}` ? Name : R;
+type RelationshipsOf<S extends GenericSchema, N extends string> = N extends keyof S['Tables'] ? S['Tables'][N] extends {
+    Relationships: infer R;
+} ? R : [] : N extends keyof S['Views'] ? S['Views'][N] extends {
+    Relationships: infer R;
+} ? R : [] : [];
+/** This relation holds the foreign key to the other: many-to-one, so one object. */
+type ManyToOne<S extends GenericSchema, N extends string, Other extends string> = RelationshipsOf<S, N> extends readonly (infer E)[] ? ([Extract<E, {
+    referencedRelation: Other;
+}>] extends [never] ? false : true) : false;
+type Embedded<S extends GenericSchema, N extends string, Rel extends string, Inner extends string> = RelationName<Rel> extends infer Other extends string ? Other extends keyof S['Tables'] | keyof S['Views'] ? ManyToOne<S, N, Other> extends true ? SelectResult<S, Other, Inner extends '' ? '*' : Inner> | (Rel extends `${string}!inner${string}` ? never : null) : SelectResult<S, Other, Inner extends '' ? '*' : Inner>[] : `relation '${Other}' does not exist` : never;
+type Spread<S extends GenericSchema, N extends string, E extends string> = E extends `${infer Rel}(${infer Inner})` ? RelationName<Rel> extends infer Other extends string ? Other extends keyof S['Tables'] | keyof S['Views'] ? SelectResult<S, Other, Inner extends '' ? '*' : Inner> : Record<string, never> : never : Record<string, never>;
+
+/** What a request needs from its client: where, with which headers, and how. */
+interface RequestContext {
+    restUrl: string;
+    /** Builds apikey, Authorization and profile headers for one request. */
+    headers: (method: string, schema: string | null) => Promise<Record<string, string>>;
+    fetch: FetchLike;
+    schema: string | null;
+}
+type Count = 'exact' | 'planned' | 'estimated';
+/**
+ * Quotes a value for PostgREST's list syntax (`in.(...)`, `cs.{...}`): reserved characters and spaces in double
+ * quotes, with `"` and `\` escaped.
+ */
+declare function quoteValue(value: unknown): string;
+/** Columns of a relation; without generated types any name. */
+type ColumnName<S extends GenericSchema, N extends string> = string extends keyof RowFor<S, N> ? string : keyof RowFor<S, N> & string;
+/** A column, a column of an embedded table (`orders.status`) or a JSON path (`meta->>theme`). */
+type FilterColumn<S extends GenericSchema, N extends string> = string extends ColumnName<S, N> ? string : ColumnName<S, N> | `${string}.${string}` | `${string}->${string}`;
+/** What a filter on a column compares with: its own type (an element for an array column), anything for a path. */
+type FilterValue<S extends GenericSchema, N extends string, K> = K extends keyof RowFor<S, N> ? NonNullable<RowFor<S, N>[K]> extends infer V ? V extends readonly (infer E)[] ? V | E : V : never : unknown;
+type InsertOf<S extends GenericSchema, N extends string> = N extends keyof S['Tables'] ? S['Tables'][N]['Insert'] : Partial<RowFor<S, N>>;
+type UpdateOf<S extends GenericSchema, N extends string> = N extends keyof S['Tables'] ? S['Tables'][N]['Update'] : Partial<RowFor<S, N>>;
+type One<R> = R extends readonly (infer E)[] ? E : R;
+/**
+ * One request to the Data API, built step by step and run when awaited: `from('todos').select('*').eq('done', false)`.
+ * Filters and modifiers map one to one onto PostgREST's query syntax; nothing runs before `await` (or `.then`). With
+ * generated types (`createClient<Database>()`), columns, filter values, inserts and the result of `select` are typed.
+ */
+declare class QueryBuilder<S extends GenericSchema = GenericSchema, N extends string = string, Result = RowFor<S, N>[]> implements PromiseLike<DataApiResponse<Result>> {
+    private readonly ctx;
+    private readonly path;
+    private method;
+    private readonly params;
+    private readonly prefer;
+    private body;
+    private accept;
+    private maybe;
+    private signal;
+    constructor(ctx: RequestContext, path: string);
+    private retype;
+    /** Overrides the result type when you know better (a view without types, a computed column). */
+    returns<R>(): QueryBuilder<S, N, R>;
+    /** Read rows (`GET`), or with a mutation before it, return the changed rows. `head: true` only counts. */
+    select<Q extends string = '*'>(columns?: Q, options?: {
+        count?: Count;
+        head?: boolean;
+    }): QueryBuilder<S, N, SelectResult<S, N, Q>[]>;
+    insert(values: InsertOf<S, N> | InsertOf<S, N>[], options?: {
+        count?: Count;
+        defaultToNull?: boolean;
+    }): QueryBuilder<S, N, null>;
+    /** Insert or, on a conflict with `onConflict` (default the primary key), update (or skip with `ignoreDuplicates`). */
+    upsert(values: InsertOf<S, N> | InsertOf<S, N>[], options?: {
+        onConflict?: string;
+        ignoreDuplicates?: boolean;
+        count?: Count;
+        defaultToNull?: boolean;
+    }): QueryBuilder<S, N, null>;
+    update(values: UpdateOf<S, N>, options?: {
+        count?: Count;
+    }): QueryBuilder<S, N, null>;
+    delete(options?: {
+        count?: Count;
+    }): QueryBuilder<S, N, null>;
+    /** `columns` for a bulk insert, so rows that leave a column out get its default instead of null. */
+    private columns;
+    /** Any PostgREST filter: `filter('age', 'gte', 18)`, `filter('tags', 'cs', '{a,b}')`. */
+    filter(column: FilterColumn<S, N>, operator: string, value: unknown): this;
+    eq<K extends FilterColumn<S, N>>(column: K, value: FilterValue<S, N, K>): this;
+    neq<K extends FilterColumn<S, N>>(column: K, value: FilterValue<S, N, K>): this;
+    gt<K extends FilterColumn<S, N>>(column: K, value: FilterValue<S, N, K>): this;
+    gte<K extends FilterColumn<S, N>>(column: K, value: FilterValue<S, N, K>): this;
+    lt<K extends FilterColumn<S, N>>(column: K, value: FilterValue<S, N, K>): this;
+    lte<K extends FilterColumn<S, N>>(column: K, value: FilterValue<S, N, K>): this;
+    like(column: FilterColumn<S, N>, pattern: string): this;
+    ilike(column: FilterColumn<S, N>, pattern: string): this;
+    /** `IS NULL`, `IS TRUE`, `IS FALSE`. */
+    is(column: FilterColumn<S, N>, value: null | boolean): this;
+    in<K extends FilterColumn<S, N>>(column: K, values: readonly FilterValue<S, N, K>[]): this;
+    contains(column: FilterColumn<S, N>, value: unknown): this;
+    containedBy(column: FilterColumn<S, N>, value: unknown): this;
+    overlaps(column: FilterColumn<S, N>, value: unknown): this;
+    /**
+     * Full-text search on a tsvector column (`infaris-guard hosting db search add` makes one):
+     * `textSearch('fts', 'fiets bel', { type: 'websearch', config: 'dutch' })`.
+     */
+    textSearch(column: FilterColumn<S, N>, query: string, options?: {
+        type?: 'plain' | 'phrase' | 'websearch';
+        config?: string;
+    }): this;
+    /** Several equalities at once. */
+    match(query: {
+        [K in ColumnName<S, N>]?: FilterValue<S, N, K>;
+    }): this;
+    /** Negate a filter: `not('status', 'eq', 'done')`. */
+    not(column: FilterColumn<S, N>, operator: string, value: unknown): this;
+    /** Raw PostgREST `or`: `or('status.eq.open,priority.gt.3')`; `referencedTable` filters an embedded table. */
+    or(filters: string, options?: {
+        referencedTable?: string;
+    }): this;
+    /** Sorting; on an embedded table pass `referencedTable` and that table's column. */
+    order(column: FilterColumn<S, N>, options?: {
+        ascending?: boolean;
+        nullsFirst?: boolean;
+    }): this;
+    order(column: string, options: {
+        ascending?: boolean;
+        nullsFirst?: boolean;
+        referencedTable: string;
+    }): this;
+    limit(count: number, options?: {
+        referencedTable?: string;
+    }): this;
+    /** Rows `from` to `to`, both included, counting from 0. */
+    range(from: number, to: number, options?: {
+        referencedTable?: string;
+    }): this;
+    /** Exactly one row, else an error (PostgREST `PGRST116`). */
+    single(): QueryBuilder<S, N, One<Result>>;
+    /** One row or null; more than one is an error. */
+    maybeSingle(): QueryBuilder<S, N, One<Result> | null>;
+    abortSignal(signal: AbortSignal): this;
+    /** The url this query will call (for logging and tests; holds filter values). */
+    toUrl(): string;
+    then<A = DataApiResponse<Result>, B = never>(onfulfilled?: ((value: DataApiResponse<Result>) => A | PromiseLike<A>) | null, onrejected?: ((reason: unknown) => B | PromiseLike<B>) | null): PromiseLike<A | B>;
+    /** Throws the error instead of returning it: `const rows = await db.from('todos').select().throwOnError()`. */
+    throwOnError(): Promise<Result>;
+    private execute;
+}
+
+/**
+ * GraphQL over the same Data API (`<url>/graphql/v1`): the same key, the same user token, so the same role, grants and
+ * row level security as REST. Typed with the documents of graphql-codegen (`client` preset, `documentMode: 'string'`):
+ * the result and the variables come from the document.
+ */
+/** What graphql-codegen's client preset produces (`TypedDocumentString`), and what a plain string is too. */
+interface TypedDocument<Result = unknown, Variables = Record<string, unknown>> {
+    /** Phantom fields: only for the types. */
+    readonly __apiType?: (variables: Variables) => Result;
+    /** `persistedDocuments: true` adds the sha256 of the document. */
+    readonly __meta__?: {
+        readonly hash?: string;
+        readonly [key: string]: unknown;
+    };
+    toString(): string;
+}
+type ResultOf<D> = D extends TypedDocument<infer R, any> ? R : unknown;
+type VariablesOf<D> = D extends TypedDocument<any, infer V> ? V : Record<string, unknown>;
+interface GraphqlError {
+    message: string;
+    path?: (string | number)[];
+    /** `code`: GRAPHQL_VALIDATION_FAILED, max_depth, max_complexity, page_too_large, introspection_disabled, a Postgres code (42501) … */
+    extensions?: {
+        code?: string;
+        [key: string]: unknown;
+    };
+}
+interface GraphqlResponse<T> {
+    data: T | null;
+    errors: GraphqlError[] | null;
+    status: number;
+}
+interface GraphqlOptions {
+    operationName?: string;
+    /** Send only the hash (`documentId`) of a persisted document; the owner registered it with `hosting db graphql persist`. */
+    persisted?: boolean;
+    /** The exposed schema to query (default: the first one). */
+    schema?: string;
+}
+
+/** Requests in one schema: `db.schema('api').from('orders')`. */
+declare class SchemaClient<S extends GenericSchema> {
+    private readonly base;
+    private readonly schemaName;
+    constructor(base: Omit<RequestContext, 'schema'>, schemaName: string | null);
+    /** A table or view: `select`, `insert`, `upsert`, `update`, `delete` with filters. */
+    from<T extends TableName<S>>(relation: T): QueryBuilder<S, T, RowOf<S, T>[]>;
+    from(relation: string): QueryBuilder<GenericSchema, string, Record<string, unknown>[]>;
+    /** A function under `/rpc`: `POST` with the arguments as JSON (or `get: true` for a read-only `GET`). */
+    rpc<F extends keyof S['Functions'] & string>(fn: F, args?: S['Functions'][F]['Args'], options?: {
+        get?: boolean;
+        head?: boolean;
+        count?: 'exact' | 'planned' | 'estimated';
+    }): Promise<DataApiResponse<S['Functions'][F]['Returns']>>;
+}
+/** The client of one Data API: `createClient(url, key)`. */
+declare class DataClient<Database = AnyDatabase, SchemaName extends string & keyof Database = 'public' & keyof Database> extends SchemaClient<Database[SchemaName] extends GenericSchema ? Database[SchemaName] : GenericSchema> {
+    readonly url: string;
+    private readonly context;
+    constructor(url: string, key: string, options?: ClientOptions);
+    /**
+     * A GraphQL query or mutation (`<url>/graphql/v1`), with the same key and token as REST. Pass a document of
+     * graphql-codegen for typed data and variables: `const { data } = await db.graphql(TodosDocument, { first: 10 })`.
+     */
+    graphql<D extends TypedDocument<any, any> | string>(document: D, variables?: VariablesOf<D>, options?: GraphqlOptions): Promise<GraphqlResponse<ResultOf<D>>>;
+    /** Requests in another exposed schema. */
+    schema<S extends string & keyof Database>(name: S): SchemaClient<Database[S] extends GenericSchema ? Database[S] : GenericSchema>;
+}
+/**
+ * The client of a Data API of Hosting by Infaris. In the browser use the publishable key and, for a signed-in user,
+ * their access token from Infaris Auth; on a server the secret key (it bypasses RLS).
+ *
+ * ```ts
+ * const db = createClient<Database>(process.env.NEXT_PUBLIC_INFARIS_DATA_URL!, process.env.NEXT_PUBLIC_INFARIS_AUTH_KEY!, {
+ *   accessToken: () => auth.getAccessToken(),
+ * });
+ * const { data, error } = await db.from('todos').select('id, title').eq('done', false).order('id');
+ * ```
+ */
+declare function createClient<Database = AnyDatabase, SchemaName extends string & keyof Database = 'public' & keyof Database>(options: ClientOptions & {
+    url: string;
+    key: string;
+}): DataClient<Database, SchemaName>;
+/** @deprecated Use createClient({ url, key, ...options }). */
+declare function createClient<Database = AnyDatabase, SchemaName extends string & keyof Database = 'public' & keyof Database>(url: string, key: string, options?: ClientOptions): DataClient<Database, SchemaName>;
+
+export { type AnyDatabase, type ClientOptions, type ColumnName, DataApiError, type DataApiResponse, DataClient, type FetchLike, type FilterColumn, type FilterValue, type GenericSchema, type GenericTable, type GraphqlError, type GraphqlOptions, type GraphqlResponse, InfarisError, QueryBuilder, type ResultOf, type RowFor, type RowOf, SchemaClient, type SelectResult, type TableName, type TypedDocument, type VariablesOf, createClient, quoteValue };