@motherbase/client 2.2.1 → 2.2.4

package/dist/database/facade.js

@@ -0,0 +1,198 @@
+const OPERATORS = new Set([
+    'equals', 'not', 'in', 'gt', 'gte', 'lt', 'lte', 'contains', 'startsWith', 'endsWith',
+]);
+/**
+ * An operator object, as opposed to a bare value. Every key must be an
+ * operator, so a json column compared to `{ theme: 'dark' }` stays a value.
+ */
+function isOperators(condition) {
+    if (typeof condition !== 'object' || condition === null || Array.isArray(condition))
+        return false;
+    const keys = Object.keys(condition);
+    return keys.length > 0 && keys.every(key => OPERATORS.has(key));
+}
+/**
+ * Flatten a `where` into one filter per condition:
+ * `{ published: true, views: { gt: 1, lt: 9 } }` is three filters.
+ *
+ * An `undefined` value means "no filter", as in Prisma, so `{ author_id: maybeId }`
+ * reads naturally. `requireFilters` is what stops that from widening a write.
+ */
+export function filtersOf(where = {}) {
+    const filters = [];
+    for (const [column, condition] of Object.entries(where)) {
+        if (isOperators(condition)) {
+            for (const [operator, value] of Object.entries(condition)) {
+                filters.push({ column, operator: operator, value });
+            }
+        }
+        else {
+            filters.push({ column, operator: 'equals', value: condition });
+        }
+    }
+    return filters.filter(filter => filter.value !== undefined);
+}
+function applyFilter(query, { column, operator, value }) {
+    const v = value;
+    switch (operator) {
+        // SQL's `= NULL` matches nothing: a null comparison has to be `IS NULL`.
+        case 'equals':
+            if (value === null)
+                query.is(column, null);
+            else
+                query.eq(column, v);
+            return;
+        case 'not':
+            if (value === null)
+                query.not(column, 'is', null);
+            else
+                query.neq(column, v);
+            return;
+        case 'in':
+            query.in(column, v);
+            return;
+        case 'gt':
+            query.gt(column, v);
+            return;
+        case 'gte':
+            query.gte(column, v);
+            return;
+        case 'lt':
+            query.lt(column, v);
+            return;
+        case 'lte':
+            query.lte(column, v);
+            return;
+        // `*` is PostgREST's LIKE wildcard.
+        // ponytail: a `*` inside the value is a wildcard too; escape it if literal stars need matching.
+        case 'contains':
+            query.like(column, `*${v}*`);
+            return;
+        case 'startsWith':
+            query.like(column, `${v}*`);
+            return;
+        case 'endsWith':
+            query.like(column, `*${v}`);
+            return;
+    }
+}
+/**
+ * A write with no filter touches every row. Prisma allows it; here it takes
+ * `client.from(table)` written out, so an id that was `undefined` at runtime
+ * cannot turn a targeted delete into a table wipe.
+ */
+function requireFilters(where, method) {
+    const filters = filtersOf(where);
+    if (!filters.length) {
+        throw new Error(`${method}(): where matched no column. Use client.from(table) to target every row.`);
+    }
+    return filters;
+}
+/** `query` narrowed by a `where` that must not be empty. */
+function narrowed(query, where, method) {
+    for (const filter of requireFilters(where, method))
+        applyFilter(query, filter);
+    return query;
+}
+/**
+ * A PATCH or DELETE matching nothing answers 404 here (under compat it
+ * resolves empty instead). Either way it means no row, not a failure.
+ */
+function noRows(error) {
+    if (error.status === 404)
+        return [];
+    throw error;
+}
+/** The read half: `findMany` arguments applied to a fresh builder. Exported for tests. */
+export function applyFindArgs(query, args = {}) {
+    query.select(args.select ? Object.keys(args.select).join(',') : '*');
+    for (const filter of filtersOf(args.where))
+        applyFilter(query, filter);
+    for (const [column, direction] of Object.entries(args.orderBy ?? {})) {
+        query.order(column, { ascending: direction === 'asc' });
+    }
+    if (args.take !== undefined) {
+        const skip = args.skip ?? 0;
+        query.range(skip, skip + args.take - 1);
+    }
+    else if (args.skip !== undefined) {
+        throw new Error('findMany(): skip needs take, the builder only offsets through range().');
+    }
+    return query;
+}
+/**
+ * `data` of a query sent with `throwOnError()`. Such a query only resolves on
+ * success, so `data` is set, whatever the `{ data, error }` envelope type says.
+ */
+async function dataOf(query) {
+    return (await query).data;
+}
+/**
+ * One table's facade. `newQuery` returns a fresh builder for that table on
+ * every call. Every method is `async`, so a refused write rejects like a failed
+ * one instead of throwing synchronously.
+ */
+export function tableFacade(newQuery) {
+    async function createManyAndReturn({ data, skipDuplicates }) {
+        const rows = data;
+        const query = skipDuplicates ? newQuery().upsert(rows, { ignoreDuplicates: true }) : newQuery().insert(rows);
+        return dataOf(query.select().throwOnError());
+    }
+    return {
+        async findMany(args) {
+            return dataOf(applyFindArgs(newQuery(), args).throwOnError());
+        },
+        async findFirst(args) {
+            return dataOf(applyFindArgs(newQuery(), { ...args, take: 1 }).throwOnError().maybeSingle());
+        },
+        async findFirstOrThrow(args) {
+            return dataOf(applyFindArgs(newQuery(), { ...args, take: 1 }).throwOnError().single());
+        },
+        // Two rows are enough to tell a unique match from several, without reading them all.
+        async findUnique(args) {
+            requireFilters(args.where, 'findUnique');
+            return dataOf(applyFindArgs(newQuery(), { ...args, take: 2 }).throwOnError().maybeSingle());
+        },
+        async findUniqueOrThrow(args) {
+            requireFilters(args.where, 'findUniqueOrThrow');
+            return dataOf(applyFindArgs(newQuery(), { ...args, take: 2 }).throwOnError().single());
+        },
+        async count(args) {
+            const query = newQuery().select('*', { count: 'exact', head: true });
+            for (const filter of filtersOf(args?.where))
+                applyFilter(query, filter);
+            return (await query.throwOnError()).count ?? 0;
+        },
+        async create({ data }) {
+            return dataOf(newQuery().insert(data).select().throwOnError().single());
+        },
+        // The server sends no Content-Range on writes, so the count is of the rows sent back.
+        async createMany(args) {
+            return { count: (await createManyAndReturn(args)).length };
+        },
+        createManyAndReturn,
+        async update({ where, data }) {
+            const query = narrowed(newQuery().update(data), where, 'update').maxAffected(1);
+            return dataOf(query.select().throwOnError().single());
+        },
+        async updateMany({ where, data }) {
+            return dataOf(narrowed(newQuery().update(data), where, 'updateMany').select().throwOnError());
+        },
+        async delete({ where }) {
+            const query = narrowed(newQuery().delete(), where, 'delete').maxAffected(1);
+            return dataOf(query.select().throwOnError().single());
+        },
+        async deleteMany({ where }) {
+            return dataOf(narrowed(newQuery().delete(), where, 'deleteMany').select().throwOnError());
+        },
+        // ponytail: update, then insert if nothing matched. A concurrent insert in
+        // between fails on the unique constraint instead of merging; Prisma's own
+        // non-native upsert has the same gap.
+        async upsert({ where, create, update }) {
+            const query = narrowed(newQuery().update(update), where, 'upsert').maxAffected(1);
+            const [updated] = await dataOf(query.select().throwOnError()).catch(noRows);
+            return updated ?? dataOf(newQuery().insert(create).select().throwOnError().single());
+        },
+    };
+}
+//# sourceMappingURL=facade.js.map

package/dist/database/facade.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"facade.js","sourceRoot":"","sources":["../../src/database/facade.ts"],"names":[],"mappings":"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"}

package/dist/database/query.d.ts

@@ -0,0 +1,97 @@
+/**
+ * React Query / SWR glue: cache keys and fetchers for Motherbase queries.
+ *
+ * Every app that reaches for a data-fetching library writes the same two
+ * things, badly: a key convention, and a fetcher that remembers to throw on
+ * `{ error }` instead of caching it as data. The second one is the bug. A
+ * fetcher that returns `{ data: null, error }` resolves successfully as far as
+ * React Query is concerned, so the error is cached, `isError` stays false, and
+ * the UI renders an empty list forever.
+ *
+ * No dependency on React Query here, and none needed: the returned objects are
+ * plain `{ queryKey, queryFn }`, which is what `useQuery` takes. The same
+ * objects work with SWR by passing `queryKey` as the key and `queryFn` as the
+ * fetcher.
+ */
+import type { MotherbaseClient } from '../index.js';
+import type { TypedQuery } from './types.js';
+import type { PostgrestResponse } from '../postgrest/index.js';
+/**
+ * The builder handed to a `build` callback: the same object `client.from()`
+ * returns, narrowed to the row type the helper was called with. Typed rather
+ * than `any`, so `.eq('athor', …)` is a compile error inside the callback and
+ * the editor completes the column names.
+ */
+export type QueryBuilderFor<Row extends object> = TypedQuery<Row, Partial<Row>, Partial<Row>>;
+/**
+ * Any client, whatever `Database` it was created with.
+ *
+ * ponytail: the generic arguments are erased here because `from()`'s relation
+ * names are literal types that differ per `Database`, so no single parameter
+ * type accepts them all. The erasure stops at this boundary: everything the
+ * helpers hand back to the caller is typed through `Row`.
+ */
+type AnyClient = MotherbaseClient<any, any, any>;
+/**
+ * Cache keys, hierarchical so invalidation can be coarse.
+ *
+ * `['motherbase', 'table', 'posts']` is a prefix of every key below it, so
+ * `invalidateQueries({ queryKey: keys.table('posts') })` reaches every list and
+ * every row of that table, which is what you want after a write. Anything
+ * narrower leaves a stale list on screen next to a fresh row.
+ */
+export declare const keys: {
+    all: readonly ["motherbase"];
+    table: (table: string) => readonly ["motherbase", "table", string];
+    list: (table: string, filters?: unknown) => readonly ["motherbase", "table", string, "list"] | readonly ["motherbase", "table", string, "list", {} | null];
+    row: (table: string, id: unknown) => readonly ["motherbase", "table", string, "row", unknown];
+};
+export interface QueryOptions<T> {
+    queryKey: readonly unknown[];
+    queryFn: () => Promise<T>;
+}
+/**
+ * A list query.
+ *
+ * `build` receives the query builder so filters, ordering and column selection
+ * stay in the caller's hands; whatever it returns is awaited and unwrapped.
+ * Pass `filters` to make the key unique per filter set, or two different
+ * filtered lists of the same table will share one cache entry and overwrite
+ * each other.
+ *
+ * ```ts
+ * useQuery(listQuery(client, 'posts', {
+ *   filters: { author },
+ *   build: q => q.select('*').eq('author', author).order('created_at'),
+ * }))
+ * ```
+ */
+export declare function listQuery<Row extends object = Record<string, unknown>>(client: AnyClient, table: string, options?: {
+    filters?: unknown;
+    build?: (query: QueryBuilderFor<Row>) => PromiseLike<PostgrestResponse<Row[]>>;
+}): QueryOptions<Row[]>;
+/**
+ * One row by primary key (or by any unique column, through `column`).
+ *
+ * Resolves `null` rather than throwing when the row is not there: "not found"
+ * is an answer, and a cache library that receives it as an error retries it.
+ */
+export declare function rowQuery<Row extends object = Record<string, unknown>>(client: AnyClient, table: string, id: unknown, options?: {
+    column?: keyof Row & string;
+    columns?: string;
+}): QueryOptions<Row | null>;
+/**
+ * Every row, walked through `stream()` rather than capped at the server's
+ * `api.rest.maxRows`.
+ *
+ * Separate from `listQuery` on purpose: this issues one request per page, so it
+ * belongs to lists that are known to be small enough to hold in memory and
+ * large enough to exceed the cap. Anything unbounded wants real pagination.
+ */
+export declare function allRowsQuery<Row extends object = Record<string, unknown>>(client: AnyClient, table: string, options?: {
+    filters?: unknown;
+    pageSize?: number;
+    build?: (query: QueryBuilderFor<Row>) => QueryBuilderFor<Row>;
+}): QueryOptions<Row[]>;
+export {};
+//# sourceMappingURL=query.d.ts.map

package/dist/database/query.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../../src/database/query.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAE/D;;;;;GAKG;AACH,MAAM,MAAM,eAAe,CAAC,GAAG,SAAS,MAAM,IAAI,UAAU,CAAC,GAAG,EAAE,OAAO,CAAC,GAAG,CAAC,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC;AAE9F;;;;;;;GAOG;AACH,KAAK,SAAS,GAAG,gBAAgB,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC;AAOjD;;;;;;;GAOG;AACH,eAAO,MAAM,IAAI;;mBAEA,MAAM;kBACP,MAAM,YAAY,OAAO;iBAI1B,MAAM,MAAM,OAAO;CACjC,CAAC;AASF,MAAM,WAAW,YAAY,CAAC,CAAC;IAC7B,QAAQ,EAAE,SAAS,OAAO,EAAE,CAAC;IAC7B,OAAO,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,CAAC;CAC3B;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,SAAS,CAAC,GAAG,SAAS,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACpE,MAAM,EAAE,SAAS,EACjB,KAAK,EAAE,MAAM,EACb,OAAO,GAAE;IACP,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,eAAe,CAAC,GAAG,CAAC,KAAK,WAAW,CAAC,iBAAiB,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;CAC3E,GACL,YAAY,CAAC,GAAG,EAAE,CAAC,CASrB;AAED;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,GAAG,SAAS,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACnE,MAAM,EAAE,SAAS,EACjB,KAAK,EAAE,MAAM,EACb,EAAE,EAAE,OAAO,EACX,OAAO,GAAE;IAAE,MAAM,CAAC,EAAE,MAAM,GAAG,GAAG,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAO,GAC9D,YAAY,CAAC,GAAG,GAAG,IAAI,CAAC,CAc1B;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,GAAG,SAAS,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACvE,MAAM,EAAE,SAAS,EACjB,KAAK,EAAE,MAAM,EACb,OAAO,GAAE;IACP,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,eAAe,CAAC,GAAG,CAAC,KAAK,eAAe,CAAC,GAAG,CAAC,CAAC;CAC1D,GACL,YAAY,CAAC,GAAG,EAAE,CAAC,CAYrB"}

package/dist/database/query.js

@@ -0,0 +1,94 @@
+/** `from()` on an erased client, re-typed to the row the caller asked for. */
+function queryFor(client, table) {
+    return client.from(table);
+}
+/**
+ * Cache keys, hierarchical so invalidation can be coarse.
+ *
+ * `['motherbase', 'table', 'posts']` is a prefix of every key below it, so
+ * `invalidateQueries({ queryKey: keys.table('posts') })` reaches every list and
+ * every row of that table, which is what you want after a write. Anything
+ * narrower leaves a stale list on screen next to a fresh row.
+ */
+export const keys = {
+    all: ['motherbase'],
+    table: (table) => ['motherbase', 'table', table],
+    list: (table, filters) => (filters === undefined
+        ? ['motherbase', 'table', table, 'list']
+        : ['motherbase', 'table', table, 'list', filters]),
+    row: (table, id) => ['motherbase', 'table', table, 'row', id],
+};
+/** Unwrap a `{ data, error }` result the way a cache library needs: throw on error. */
+async function unwrap(result) {
+    const { data, error } = await result;
+    if (error)
+        throw Object.assign(new Error(error.message), error);
+    return data;
+}
+/**
+ * A list query.
+ *
+ * `build` receives the query builder so filters, ordering and column selection
+ * stay in the caller's hands; whatever it returns is awaited and unwrapped.
+ * Pass `filters` to make the key unique per filter set, or two different
+ * filtered lists of the same table will share one cache entry and overwrite
+ * each other.
+ *
+ * ```ts
+ * useQuery(listQuery(client, 'posts', {
+ *   filters: { author },
+ *   build: q => q.select('*').eq('author', author).order('created_at'),
+ * }))
+ * ```
+ */
+export function listQuery(client, table, options = {}) {
+    const { filters, build } = options;
+    return {
+        queryKey: keys.list(table, filters),
+        queryFn: () => {
+            const base = queryFor(client, table);
+            return unwrap(build ? build(base) : base.select('*'));
+        },
+    };
+}
+/**
+ * One row by primary key (or by any unique column, through `column`).
+ *
+ * Resolves `null` rather than throwing when the row is not there: "not found"
+ * is an answer, and a cache library that receives it as an error retries it.
+ */
+export function rowQuery(client, table, id, options = {}) {
+    const { column = 'id', columns = '*' } = options;
+    return {
+        queryKey: keys.row(table, id),
+        queryFn: () => unwrap(queryFor(client, table)
+            // `columns` is a runtime string, so it cannot be checked against the
+            // row the way a literal passed to `.select()` is.
+            .select(columns)
+            .eq(column, id)
+            .maybeSingle()),
+    };
+}
+/**
+ * Every row, walked through `stream()` rather than capped at the server's
+ * `api.rest.maxRows`.
+ *
+ * Separate from `listQuery` on purpose: this issues one request per page, so it
+ * belongs to lists that are known to be small enough to hold in memory and
+ * large enough to exceed the cap. Anything unbounded wants real pagination.
+ */
+export function allRowsQuery(client, table, options = {}) {
+    const { filters, pageSize, build } = options;
+    return {
+        queryKey: [...keys.list(table, filters), 'all'],
+        queryFn: async () => {
+            const base = queryFor(client, table);
+            const query = build ? build(base) : base.select('*');
+            const rows = [];
+            for await (const row of query.stream({ pageSize }))
+                rows.push(row);
+            return rows;
+        },
+    };
+}
+//# sourceMappingURL=query.js.map

package/dist/database/query.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"query.js","sourceRoot":"","sources":["../../src/database/query.ts"],"names":[],"mappings":"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"}