@svgrid/enterprise 3.1.7 → 3.1.9

package/dist/fields/base-sql.d.ts

@@ -0,0 +1,62 @@
+/**
+ * A base as Postgres SQL: the tables, their columns, foreign keys and
+ * junction tables, and the records, ready to run on Postgres, Supabase or
+ * PGlite.
+ *
+ * Everything SQL has no column type for rides along in comments
+ * (`COMMENT ON ... IS 'svgrid:{...}'`): a select's options and colors, a
+ * number shown as currency, the formula, lookup, rollup and count fields, the
+ * views and the automations. `baseFromDatabase` (and `createBaseEndpoint`)
+ * read them back, so the database opens as the same base, not a generic one.
+ * A database without the comments still opens: they only add to what is
+ * read from the columns.
+ */
+import { type BaseTable } from './base-tables.js';
+type Def = Record<string, any>;
+/** What a table comment holds. */
+export type BaseTableComment = {
+    v: 1;
+    /** The table's name in the base ("Key results"). */
+    name: string;
+    /** Where its tab was. */
+    position?: number;
+    primaryField?: string;
+    /** The fields in their order. */
+    order: string[];
+    /** Fields with no column of their own: computed ones, buttons, links kept elsewhere. */
+    extra: Def[];
+    views?: unknown[];
+    automations?: unknown[];
+};
+/** What a junction table's comment holds: whose link it keeps. */
+export type BaseJunctionComment = {
+    v: 1;
+    junction: {
+        owner: string;
+        field: string;
+        from: string;
+        to: string;
+    };
+};
+export declare const SQL_COMMENT_PREFIX = "svgrid:";
+/** `fixedOn` -> `fixed_on`, `Key results` -> `key_results`. */
+export declare function sqlName(s: string): string;
+export type BaseToSqlOptions = {
+    /** Dates within this many days of `today` are written as `current_date + n`, so seed data stays current (default 400; 0 writes every date as it is). */
+    relativeDays?: number;
+    today?: Date;
+    /** Leave the records out: tables only. */
+    data?: boolean;
+    /** A first line saying what this is. */
+    title?: string;
+};
+/**
+ * The SQL that makes a database holding these tables and records.
+ *
+ * ```ts
+ * const sql = baseToSql(tables)        // run it with psql, the Supabase SQL editor, or PGlite
+ * const again = await baseFromDatabase({ execute })   // the same base, from the database
+ * ```
+ */
+export declare function baseToSql(tables: ReadonlyArray<BaseTable>, options?: BaseToSqlOptions): string;
+export {};

package/dist/fields/base-sql.js

@@ -0,0 +1,251 @@
+/**
+ * A base as Postgres SQL: the tables, their columns, foreign keys and
+ * junction tables, and the records, ready to run on Postgres, Supabase or
+ * PGlite.
+ *
+ * Everything SQL has no column type for rides along in comments
+ * (`COMMENT ON ... IS 'svgrid:{...}'`): a select's options and colors, a
+ * number shown as currency, the formula, lookup, rollup and count fields, the
+ * views and the automations. `baseFromDatabase` (and `createBaseEndpoint`)
+ * read them back, so the database opens as the same base, not a generic one.
+ * A database without the comments still opens: they only add to what is
+ * read from the columns.
+ */
+import { colId, primaryOf, rowIdOf } from './base-tables.js';
+import { fillFieldColumn } from './registry.svelte.js';
+export const SQL_COMMENT_PREFIX = 'svgrid:';
+/** `fixedOn` -> `fixed_on`, `Key results` -> `key_results`. */
+export function sqlName(s) {
+    const out = String(s)
+        .replace(/([a-z0-9])([A-Z])/g, '$1_$2')
+        .replace(/[^A-Za-z0-9]+/g, '_')
+        .replace(/^_+|_+$/g, '')
+        .toLowerCase();
+    return /^[a-z_]/.test(out) ? out : `t_${out}`;
+}
+const COMPUTED = new Set(['formula', 'lookup', 'rollup', 'count', 'button']);
+const quote = (name) => `"${name.replace(/"/g, '""')}"`;
+const str = (s) => `'${s.replace(/'/g, "''")}'`;
+const ids = (v) => (Array.isArray(v) ? v.map(String) : v == null || v === '' ? [] : [String(v)]);
+function sqlType(d) {
+    switch (d.fieldType) {
+        case 'number':
+        case 'currency':
+        case 'percent':
+        case 'rating':
+        case 'duration':
+        case 'autoNumber':
+            return 'double precision';
+        case 'checkbox':
+            return 'boolean';
+        case 'date':
+            return d.fieldProps?.time ? 'timestamptz' : 'date';
+        case 'createdTime':
+        case 'lastModifiedTime':
+            return 'timestamptz';
+        case 'multiSelect':
+            return 'text[]';
+        case 'user':
+        case 'createdBy':
+        case 'lastModifiedBy':
+            return d.fieldProps?.multiple ? 'text[]' : 'text';
+        case 'attachment':
+            return 'jsonb';
+        default:
+            return typeOfData(d);
+    }
+}
+const dataTypes = new WeakMap();
+/**
+ * Any other type (a registered one) by what its filled column holds, as the
+ * built-ins map: a number, a true / false, a date with or without the time.
+ */
+function typeOfData(d) {
+    let t = dataTypes.get(d);
+    if (t === undefined) {
+        const kind = fillFieldColumn(d).cellDataType;
+        t = kind === 'number' ? 'double precision' : kind === 'boolean' ? 'boolean' : kind === 'date' ? 'timestamptz' : kind === 'dateString' ? 'date' : 'text';
+        dataTypes.set(d, t);
+    }
+    return t;
+}
+const DAY = 86400000;
+/**
+ * The SQL that makes a database holding these tables and records.
+ *
+ * ```ts
+ * const sql = baseToSql(tables)        // run it with psql, the Supabase SQL editor, or PGlite
+ * const again = await baseFromDatabase({ execute })   // the same base, from the database
+ * ```
+ */
+export function baseToSql(tables, options = {}) {
+    const today = options.today ?? new Date();
+    const todayUtc = Date.UTC(today.getFullYear(), today.getMonth(), today.getDate());
+    const relative = options.relativeDays ?? 400;
+    const used = new Set();
+    const nameOf = new Map();
+    for (const t of tables) {
+        let n = sqlName(t.name || t.id);
+        while (used.has(n))
+            n = `${n}_2`;
+        used.add(n);
+        nameOf.set(t.id, n);
+    }
+    const tableOf = (id) => tables.find((t) => t.id === id);
+    const fieldOf = (t, id) => t.columns.find((d) => colId(d) === id);
+    /** Who keeps a link: a foreign key on the side that links to one record, else a junction on the first table. */
+    function storage(t, d) {
+        const target = tableOf(String(d.fieldProps?.table ?? ''));
+        const back = d.fieldProps?.inverse && target ? fieldOf(target, String(d.fieldProps.inverse)) : undefined;
+        const many = d.fieldProps?.multiple !== false;
+        if (!back || target === t)
+            return many ? 'junction' : 'fk';
+        const backMany = back.fieldProps?.multiple !== false;
+        if (!many)
+            return 'fk';
+        if (!backMany)
+            return 'derived';
+        return tables.indexOf(t) <= tables.indexOf(target) ? 'junction' : 'derived';
+    }
+    // Rewrite table ids to the SQL names in what a comment keeps.
+    const remap = (value) => JSON.parse(JSON.stringify(value ?? null), (k, v) => (k === 'table' && typeof v === 'string' && nameOf.has(v) ? nameOf.get(v) : v));
+    const plans = [];
+    const junctions = [];
+    for (const t of tables) {
+        const name = nameOf.get(t.id);
+        const columns = [];
+        const extra = [];
+        const taken = new Set(['id']);
+        const column = (base) => {
+            let c = sqlName(base);
+            while (taken.has(c))
+                c = `${c}_2`;
+            taken.add(c);
+            return c;
+        };
+        for (const d of t.columns) {
+            if (d.field == null)
+                continue;
+            const field = String(d.field);
+            if (COMPUTED.has(String(d.fieldType))) {
+                extra.push(d);
+                continue;
+            }
+            if (d.fieldType === 'link') {
+                const how = storage(t, d);
+                const target = tableOf(String(d.fieldProps?.table ?? ''));
+                if (!target)
+                    continue;
+                if (how === 'fk')
+                    columns.push({ def: d, column: column(`${field}_id`), fk: nameOf.get(target.id) });
+                else {
+                    extra.push(d);
+                    if (how === 'junction') {
+                        const from = `${sqlName(name).replace(/s$/, '')}_id`;
+                        let to = `${sqlName(field).replace(/s$/, '')}_id`;
+                        if (to === from)
+                            to = `${to}_2`;
+                        junctions.push({ name: `${name}_${sqlName(field)}`, owner: t, field, from, to, target });
+                    }
+                }
+                continue;
+            }
+            columns.push({ def: d, column: column(field) });
+        }
+        // The database makes the key of a record added later: a Supabase insert
+        // carries no id. The records below bring their own.
+        const lines = [`  "id" text primary key default gen_random_uuid()::text`, ...columns.map((c) => `  ${quote(c.column)} ${c.fk ? 'text' : sqlType(c.def)}`)];
+        plans.push({ table: t, columns, extra, sql: `create table ${quote(name)} (\n${lines.join(',\n')}\n);` });
+    }
+    const out = [];
+    out.push(`-- ${options.title ?? 'A base'}, as Postgres tables. Made by baseToSql (@svgrid/enterprise/base);`);
+    out.push(`-- the svgrid: comments keep what SQL has no type for, so baseFromDatabase opens it as the same base.`);
+    out.push('');
+    for (const p of plans)
+        out.push(p.sql);
+    for (const j of junctions) {
+        out.push(`create table ${quote(j.name)} (\n  "id" serial primary key,\n  ${quote(j.from)} text not null,\n  ${quote(j.to)} text not null\n);`);
+    }
+    out.push('');
+    // Comments: what each field, table and junction is in the base.
+    for (const p of plans) {
+        const name = nameOf.get(p.table.id);
+        for (const c of p.columns) {
+            out.push(`comment on column ${quote(name)}.${quote(c.column)} is ${str(SQL_COMMENT_PREFIX + JSON.stringify(remap(c.def)))};`);
+        }
+        const comment = {
+            v: 1,
+            name: p.table.name,
+            position: plans.indexOf(p),
+            primaryField: primaryOf(p.table),
+            order: p.table.columns.filter((d) => d.field != null).map((d) => String(d.field)),
+            extra: remap(p.extra),
+            ...(p.table.views ? { views: remap(p.table.views) } : {}),
+            ...(p.table.automations?.length ? { automations: remap(p.table.automations) } : {}),
+        };
+        out.push(`comment on table ${quote(name)} is ${str(SQL_COMMENT_PREFIX + JSON.stringify(comment))};`);
+    }
+    for (const j of junctions) {
+        const c = { v: 1, junction: { owner: nameOf.get(j.owner.id), field: j.field, from: j.from, to: j.to } };
+        out.push(`comment on table ${quote(j.name)} is ${str(SQL_COMMENT_PREFIX + JSON.stringify(c))};`);
+    }
+    // The records.
+    if (options.data !== false) {
+        const value = (d, v) => {
+            if (v == null || v === '' || (Array.isArray(v) && v.length === 0 && sqlType(d) !== 'text[]' && sqlType(d) !== 'jsonb'))
+                return 'null';
+            const type = sqlType(d);
+            if (type === 'jsonb') {
+                // A blob: link lives only in the page that made it: leave such files out.
+                const kept = Array.isArray(v) ? v.filter((x) => !(x && typeof x === 'object' && String(x.url ?? '').startsWith('blob:'))) : v;
+                return `${str(JSON.stringify(kept))}::jsonb`;
+            }
+            if (type === 'text[]')
+                return `array[${ids(v).map(str).join(', ')}]::text[]`;
+            if (type === 'boolean')
+                return v ? 'true' : 'false';
+            if (type === 'double precision')
+                return Number.isFinite(Number(v)) ? String(Number(v)) : 'null';
+            if (type === 'date' && typeof v === 'string' && /^\d{4}-\d{2}-\d{2}$/.test(v) && relative > 0) {
+                const n = Math.round((Date.parse(`${v}T00:00:00Z`) - todayUtc) / DAY);
+                if (Math.abs(n) <= relative)
+                    return n === 0 ? 'current_date' : `current_date ${n > 0 ? '+' : '-'} ${Math.abs(n)}`;
+            }
+            return str(String(v));
+        };
+        out.push('');
+        for (const p of plans) {
+            const rows = p.table.data.filter(Boolean);
+            if (!rows.length)
+                continue;
+            const cols = ['id', ...p.columns.map((c) => c.column)];
+            const tuples = rows.map((r) => {
+                const vals = [str(rowIdOf(p.table, r)), ...p.columns.map((c) => (c.fk ? (ids(r[String(c.def.field)])[0] != null ? str(ids(r[String(c.def.field)])[0]) : 'null') : value(c.def, r[String(c.def.field)])))];
+                return `  (${vals.join(', ')})`;
+            });
+            out.push(`insert into ${quote(nameOf.get(p.table.id))} (${cols.map(quote).join(', ')}) values\n${tuples.join(',\n')};`);
+        }
+        for (const j of junctions) {
+            const pairs = [];
+            for (const r of j.owner.data)
+                if (r)
+                    for (const to of ids(r[j.field]))
+                        pairs.push(`  (${str(rowIdOf(j.owner, r))}, ${str(to)})`);
+            if (pairs.length)
+                out.push(`insert into ${quote(j.name)} (${quote(j.from)}, ${quote(j.to)}) values\n${pairs.join(',\n')};`);
+        }
+    }
+    // Foreign keys last, once every record is in: links may point either way.
+    out.push('');
+    for (const p of plans) {
+        const name = nameOf.get(p.table.id);
+        for (const c of p.columns)
+            if (c.fk)
+                out.push(`alter table ${quote(name)} add foreign key (${quote(c.column)}) references ${quote(c.fk)}("id") on delete set null;`);
+    }
+    for (const j of junctions) {
+        out.push(`alter table ${quote(j.name)} add foreign key (${quote(j.from)}) references ${quote(nameOf.get(j.owner.id))}("id") on delete cascade;`);
+        out.push(`alter table ${quote(j.name)} add foreign key (${quote(j.to)}) references ${quote(nameOf.get(j.target.id))}("id") on delete cascade;`);
+    }
+    return out.join('\n') + '\n';
+}

package/dist/fields/base-sync.d.ts

@@ -0,0 +1,142 @@
+/**
+ * A base on a database: each table with a `source` loads its records from
+ * it and writes every change back.
+ *
+ * A base filters, groups, colors and sums in the page, so a table loads in
+ * full (up to `limit` records) and the writer keeps a copy of what the
+ * database holds. After each change it compares the tables with that copy
+ * and sends what differs: an insert for a new record, an update with the
+ * changed fields, a delete. Writes go one at a time, in order, so an update
+ * never overtakes the insert of its record. A write that fails is undone in
+ * the page and reported.
+ *
+ * Link fields: a link to one record is a foreign key column, a link to many
+ * records goes through a junction table, and the field that links back is
+ * worked out in the page from the other side, so it is never stored.
+ *
+ * Record ids: a new record gets an id in the page at once. When the database
+ * gives it another one (a serial key, a default uuid), the writer keeps both
+ * and translates, so the grid never sees a record change its id under an
+ * open editor.
+ */
+import type { ServerDataSource } from '@svgrid/grid';
+import { type BaseTable } from './base-tables.js';
+type Row = Record<string, unknown>;
+/** A link field kept as a foreign key: the column holds the linked record's id. */
+export type ForeignKeyLink = {
+    column: string;
+};
+/** A link field kept in a junction table: one row per pair. */
+export type JunctionLink = {
+    through: ServerDataSource<any>;
+    /** The junction column with this table's record id. */
+    from: string;
+    /** The junction column with the linked record's id. */
+    to: string;
+    /** The junction table's own key (default `id`). */
+    idField?: string;
+};
+/** What a base table reads and writes. `baseSource` makes one from any data source. */
+export type BaseSource = {
+    /** Every record, as the page keeps them (link fields as lists of ids). */
+    load(): Promise<Row[]>;
+    /**
+     * One row as the database has it (a webhook's `record`), as the page keeps
+     * it: a foreign key becomes a link, renamed columns their fields. Links
+     * kept in a junction table are not in such a row.
+     */
+    toPage(row: Row): Row;
+    /** Store a new record; resolves with the record as stored (its id may be the database's). */
+    insert(row: Row): Promise<Row>;
+    update(id: string, patch: Row, before: Row): Promise<void>;
+    remove(id: string, before: Row): Promise<void>;
+    /** Hear of changes made elsewhere (another user, another tab); returns the unsubscribe. */
+    subscribe?(onChange: () => void): () => void;
+    /** The most records `load` reads. */
+    limit: number;
+    /** The link fields it stores, by field. */
+    links: Record<string, ForeignKeyLink | JunctionLink>;
+    /** Fields it does not store, besides computed ones and the fields that link back. */
+    skip: ReadonlySet<string>;
+    /** Turn a linked record's page id into its database id, and back (set by the writer). */
+    ids?: {
+        toServer: (table: string, id: string) => string;
+        toLocal: (table: string, id: string) => string;
+    };
+};
+export type BaseSourceOptions = {
+    /** The most records to load (default 10,000). A base works on all of them in the page. */
+    limit?: number;
+    /** The record's key column (default `id`). */
+    idField?: string;
+    /**
+     * The database makes the key (a serial column, a default uuid): a new
+     * record is inserted without the page's id, and the writer uses the one it
+     * gets back. By default the page's id is the key.
+     */
+    serverIds?: boolean;
+    /** Column names that differ from the field names: `{ dueDate: 'due_date' }`. */
+    columns?: Record<string, string>;
+    /** How link fields are stored: `{ project: { column: 'project_id' } }`, or a junction. */
+    links?: Record<string, ForeignKeyLink | JunctionLink>;
+    /** Fields kept in the page only. */
+    skip?: string[];
+    /**
+     * Changes made elsewhere: call `onChange` when the table changed, and return
+     * a function that stops listening. With Supabase:
+     * `(onChange) => createSupabaseRealtime({ client, table, onChange }).unsubscribe`.
+     */
+    realtime?: (onChange: () => void) => (() => void) | {
+        unsubscribe: () => void;
+    };
+};
+/**
+ * A base table's source from any data source with the grid's contract
+ * (`createSupabaseDataSource`, `createSqlDataSource`, `createRestDataSource`,
+ * `createInMemoryDataSource`, or your own).
+ *
+ * ```ts
+ * source: baseSource(createSupabaseDataSource({ client, table: 'tasks', schema }), {
+ *   links: { project: { column: 'project_id' } },
+ *   realtime: (onChange) => createSupabaseRealtime({ client, table: 'tasks', onChange }).unsubscribe,
+ * })
+ * ```
+ */
+export declare function baseSource(ds: ServerDataSource<any>, options?: BaseSourceOptions): BaseSource;
+export type BaseSyncStatus = {
+    state: 'idle';
+} | {
+    state: 'loading';
+} | {
+    state: 'saving';
+    pending: number;
+} | {
+    state: 'error';
+    message: string;
+    table: string;
+} | {
+    state: 'limited';
+    table: string;
+    limit: number;
+};
+export type BaseSyncOptions = {
+    getTables: () => BaseTable[] | undefined;
+    /** Put tables in the page without writing them (loaded, undone, changed elsewhere). */
+    apply: (tables: BaseTable[]) => void;
+    onStatus?: (status: BaseSyncStatus) => void;
+    onError?: (error: {
+        table: string;
+        action: 'insert' | 'update' | 'delete' | 'load';
+        message: string;
+    }) => void;
+};
+export declare function createBaseSync(options: BaseSyncOptions): {
+    load: () => Promise<void>;
+    push: (list: BaseTable[] | undefined) => void;
+    /** Read a table again now (after a change you know of). */
+    refresh: (tableId: string) => void;
+    /** Resolves when every queued write has finished. */
+    settled: () => Promise<void>;
+    dispose(): void;
+};
+export {};