lemma-sdk 0.2.28 → 0.2.30

package/dist/react/useRecordForm.js

@@ -0,0 +1,238 @@
+import { useCallback, useEffect, useMemo, useState } from "react";
+import { buildRecordFormValues, buildRecordPayload, } from "../record-form.js";
+import { useRecordSchema, } from "./useRecordSchema.js";
+const EMPTY_VALUES = {};
+function normalizeError(error, fallback) {
+    if (error instanceof Error)
+        return error;
+    return new Error(fallback);
+}
+function resolvePodClient(client, podId) {
+    if (!podId || podId === client.podId)
+        return client;
+    return client.withPod(podId);
+}
+function stringifyComparable(value) {
+    try {
+        return JSON.stringify(value);
+    }
+    catch {
+        return String(value);
+    }
+}
+export function useRecordForm({ client, podId, tableName, recordId = null, initialValues = EMPTY_VALUES, mode = "auto", enabled = true, autoLoad = true, onSubmitSuccess, onError, }) {
+    const schema = useRecordSchema({
+        client,
+        podId,
+        tableName,
+        enabled,
+        autoLoad,
+    });
+    const [record, setRecord] = useState(null);
+    const [values, setValuesState] = useState({});
+    const [baselineValues, setBaselineValues] = useState({});
+    const [fieldErrors, setFieldErrors] = useState({});
+    const [recordError, setRecordError] = useState(null);
+    const [isLoadingRecord, setIsLoadingRecord] = useState(false);
+    const [isSubmitting, setIsSubmitting] = useState(false);
+    const initialValuesKey = stringifyComparable(initialValues);
+    const stableInitialValues = useMemo(() => initialValues, [initialValuesKey]);
+    const schemaTable = schema.table;
+    const refreshSchema = schema.refresh;
+    const hydrateValues = useCallback((source) => {
+        if (!schemaTable)
+            return;
+        const nextValues = buildRecordFormValues(schemaTable, source);
+        setValuesState(nextValues);
+        setBaselineValues(nextValues);
+        setFieldErrors({});
+    }, [schemaTable]);
+    const refreshRecord = useCallback(async () => {
+        if (!enabled || !recordId) {
+            setRecord(null);
+            return null;
+        }
+        setIsLoadingRecord(true);
+        setRecordError(null);
+        try {
+            const scopedClient = resolvePodClient(client, podId);
+            const response = await scopedClient.records.get(tableName, recordId);
+            const nextRecord = response.data ?? null;
+            setRecord(nextRecord);
+            return nextRecord;
+        }
+        catch (refreshError) {
+            const normalized = normalizeError(refreshError, "Failed to load record.");
+            setRecordError(normalized);
+            onError?.(refreshError);
+            return null;
+        }
+        finally {
+            setIsLoadingRecord(false);
+        }
+    }, [client, enabled, onError, podId, recordId, tableName]);
+    useEffect(() => {
+        if (!enabled) {
+            setRecord(null);
+            setValuesState({});
+            setBaselineValues({});
+            setFieldErrors({});
+            setRecordError(null);
+            setIsLoadingRecord(false);
+            setIsSubmitting(false);
+            return;
+        }
+        if (!autoLoad || !recordId)
+            return;
+        void refreshRecord();
+    }, [autoLoad, enabled, recordId, refreshRecord]);
+    const recordKey = stringifyComparable(record);
+    useEffect(() => {
+        if (!schemaTable)
+            return;
+        const source = {
+            ...(record ?? {}),
+            ...stableInitialValues,
+        };
+        hydrateValues(source);
+    }, [hydrateValues, recordKey, schemaTable, stableInitialValues]);
+    const refresh = useCallback(async () => {
+        const nextTable = await refreshSchema();
+        if (recordId) {
+            const nextRecord = await refreshRecord();
+            if (nextTable && nextRecord) {
+                hydrateValues({
+                    ...nextRecord,
+                    ...stableInitialValues,
+                });
+            }
+            return;
+        }
+        if (nextTable) {
+            hydrateValues(stableInitialValues);
+        }
+    }, [hydrateValues, recordId, refreshRecord, refreshSchema, stableInitialValues]);
+    const setValue = useCallback((fieldName, value) => {
+        setValuesState((current) => ({
+            ...current,
+            [fieldName]: value,
+        }));
+        setFieldErrors((current) => {
+            if (!(fieldName in current))
+                return current;
+            const next = { ...current };
+            delete next[fieldName];
+            return next;
+        });
+    }, []);
+    const setValues = useCallback((nextValues) => {
+        setValuesState((current) => ({
+            ...current,
+            ...nextValues,
+        }));
+    }, []);
+    const reset = useCallback((nextValues) => {
+        if (!schemaTable)
+            return;
+        const source = nextValues ?? {
+            ...(record ?? {}),
+            ...stableInitialValues,
+        };
+        hydrateValues(source);
+    }, [hydrateValues, record, schemaTable, stableInitialValues]);
+    const validate = useCallback(() => {
+        if (!schemaTable)
+            return false;
+        const resolvedMode = mode === "auto" ? (recordId ? "update" : "create") : mode;
+        const result = buildRecordPayload(schemaTable, values, { mode: resolvedMode });
+        setFieldErrors(result.errors);
+        return result.isValid;
+    }, [mode, recordId, schemaTable, values]);
+    const submit = useCallback(async (overrides = {}) => {
+        if (!schemaTable) {
+            const error = new Error("Record schema is not loaded.");
+            setRecordError(error);
+            return null;
+        }
+        const resolvedMode = overrides.mode ?? (mode === "auto" ? (recordId ? "update" : "create") : mode);
+        const payload = buildRecordPayload(schemaTable, values, { mode: resolvedMode });
+        setFieldErrors(payload.errors);
+        if (!payload.isValid) {
+            return null;
+        }
+        setIsSubmitting(true);
+        setRecordError(null);
+        try {
+            const scopedClient = resolvePodClient(client, podId);
+            const response = resolvedMode === "update" && recordId
+                ? await scopedClient.records.update(tableName, recordId, payload.data)
+                : await scopedClient.records.create(tableName, payload.data);
+            const nextRecord = response.data ?? null;
+            setRecord(nextRecord);
+            hydrateValues({
+                ...(nextRecord ?? {}),
+                ...stableInitialValues,
+            });
+            onSubmitSuccess?.(nextRecord ?? {}, response);
+            return nextRecord;
+        }
+        catch (submitError) {
+            const normalized = normalizeError(submitError, "Failed to save record.");
+            setRecordError(normalized);
+            onError?.(submitError);
+            return null;
+        }
+        finally {
+            setIsSubmitting(false);
+        }
+    }, [client, hydrateValues, mode, onError, onSubmitSuccess, podId, recordId, schemaTable, stableInitialValues, tableName, values]);
+    const isDirty = useMemo(() => {
+        return stringifyComparable(values) !== stringifyComparable(baselineValues);
+    }, [baselineValues, values]);
+    return useMemo(() => ({
+        table: schema.table,
+        fields: schema.fields,
+        editableFields: schema.editableFields,
+        defaults: schema.defaults,
+        values,
+        baselineValues,
+        record,
+        fieldErrors,
+        isLoadingSchema: schema.isLoading,
+        isLoadingRecord,
+        isSubmitting,
+        isDirty,
+        error: schema.error ?? recordError,
+        refreshSchema: schema.refresh,
+        refreshRecord,
+        refresh,
+        setValue,
+        setValues,
+        reset,
+        validate,
+        submit,
+    }), [
+        baselineValues,
+        fieldErrors,
+        isDirty,
+        isLoadingRecord,
+        isSubmitting,
+        record,
+        recordError,
+        refresh,
+        refreshRecord,
+        reset,
+        schema.defaults,
+        schema.editableFields,
+        schema.error,
+        schema.fields,
+        schema.isLoading,
+        schema.refresh,
+        schema.table,
+        setValue,
+        setValues,
+        submit,
+        validate,
+        values,
+    ]);
+}

package/dist/react/useRecordSchema.d.ts

@@ -0,0 +1,20 @@
+import type { LemmaClient } from "../client.js";
+import { type RecordSchemaField } from "../record-form.js";
+import type { Table } from "../types.js";
+export interface UseRecordSchemaOptions {
+    client: LemmaClient;
+    podId?: string;
+    tableName: string;
+    enabled?: boolean;
+    autoLoad?: boolean;
+}
+export interface UseRecordSchemaResult {
+    table: Table | null;
+    fields: RecordSchemaField[];
+    editableFields: RecordSchemaField[];
+    defaults: Record<string, unknown>;
+    isLoading: boolean;
+    error: Error | null;
+    refresh: () => Promise<Table | null>;
+}
+export declare function useRecordSchema({ client, podId, tableName, enabled, autoLoad, }: UseRecordSchemaOptions): UseRecordSchemaResult;

package/dist/react/useRecordSchema.js

@@ -0,0 +1,24 @@
+import { useMemo } from "react";
+import { buildRecordFormValues, buildRecordSchemaFields, getEditableRecordFields, } from "../record-form.js";
+import { useTable } from "./useTable.js";
+export function useRecordSchema({ client, podId, tableName, enabled = true, autoLoad = true, }) {
+    const tableState = useTable({
+        client,
+        podId,
+        tableName,
+        enabled,
+        autoLoad,
+    });
+    const fields = useMemo(() => (tableState.table ? buildRecordSchemaFields(tableState.table) : []), [tableState.table]);
+    const editableFields = useMemo(() => (tableState.table ? getEditableRecordFields(tableState.table) : []), [tableState.table]);
+    const defaults = useMemo(() => (tableState.table ? buildRecordFormValues(tableState.table) : {}), [tableState.table]);
+    return useMemo(() => ({
+        table: tableState.table,
+        fields,
+        editableFields,
+        defaults,
+        isLoading: tableState.isLoading,
+        error: tableState.error,
+        refresh: tableState.refresh,
+    }), [defaults, editableFields, fields, tableState.error, tableState.isLoading, tableState.refresh, tableState.table]);
+}

package/dist/react/useRecords.d.ts

@@ -0,0 +1,18 @@
+import type { LemmaClient } from "../client.js";
+import type { ListRecordsOptions } from "../types.js";
+export interface UseRecordsOptions extends ListRecordsOptions {
+    client: LemmaClient;
+    podId?: string;
+    tableName: string;
+    enabled?: boolean;
+    autoLoad?: boolean;
+}
+export interface UseRecordsResult<TRecord extends Record<string, unknown> = Record<string, unknown>> {
+    records: TRecord[];
+    total: number;
+    nextPageToken: string | null;
+    isLoading: boolean;
+    error: Error | null;
+    refresh: (overrides?: Partial<ListRecordsOptions>) => Promise<TRecord[]>;
+}
+export declare function useRecords<TRecord extends Record<string, unknown> = Record<string, unknown>>({ client, podId, tableName, filters, sort, limit, pageToken, offset, sortBy, order, params, enabled, autoLoad, }: UseRecordsOptions): UseRecordsResult<TRecord>;

package/dist/react/useRecords.js

@@ -0,0 +1,106 @@
+import { useCallback, useEffect, useMemo, useState } from "react";
+function resolvePodClient(client, podId) {
+    if (!podId || podId === client.podId)
+        return client;
+    return client.withPod(podId);
+}
+function normalizeError(error, fallback) {
+    if (error instanceof Error)
+        return error;
+    return new Error(fallback);
+}
+function stringifyComparable(value) {
+    try {
+        return JSON.stringify(value);
+    }
+    catch {
+        return String(value);
+    }
+}
+export function useRecords({ client, podId, tableName, filters, sort, limit = 20, pageToken, offset, sortBy, order, params, enabled = true, autoLoad = true, }) {
+    const [records, setRecords] = useState([]);
+    const [total, setTotal] = useState(0);
+    const [nextPageToken, setNextPageToken] = useState(null);
+    const [isLoading, setIsLoading] = useState(false);
+    const [error, setError] = useState(null);
+    const trimmedTableName = tableName.trim();
+    const isEnabled = enabled && trimmedTableName.length > 0;
+    const filtersKey = stringifyComparable(filters);
+    const sortKey = stringifyComparable(sort);
+    const paramsKey = stringifyComparable(params);
+    const stableFilters = useMemo(() => filters, [filtersKey]);
+    const stableSort = useMemo(() => sort, [sortKey]);
+    const stableParams = useMemo(() => params, [paramsKey]);
+    const refresh = useCallback(async (overrides = {}) => {
+        if (!isEnabled) {
+            setRecords([]);
+            setTotal(0);
+            setNextPageToken(null);
+            setError(null);
+            setIsLoading(false);
+            return [];
+        }
+        setIsLoading(true);
+        setError(null);
+        try {
+            const scopedClient = resolvePodClient(client, podId);
+            const response = await scopedClient.records.list(trimmedTableName, {
+                filters: overrides.filters ?? stableFilters,
+                sort: overrides.sort ?? stableSort,
+                limit: overrides.limit ?? limit,
+                pageToken: overrides.pageToken ?? pageToken,
+                offset: overrides.offset ?? offset,
+                sortBy: overrides.sortBy ?? sortBy,
+                order: overrides.order ?? order,
+                params: overrides.params ?? stableParams,
+            });
+            const nextRecords = (response.items ?? []);
+            setRecords(nextRecords);
+            setTotal(response.total ?? nextRecords.length);
+            setNextPageToken(response.next_page_token ?? null);
+            return nextRecords;
+        }
+        catch (refreshError) {
+            const normalized = normalizeError(refreshError, "Failed to load records.");
+            setError(normalized);
+            return [];
+        }
+        finally {
+            setIsLoading(false);
+        }
+    }, [
+        client,
+        isEnabled,
+        limit,
+        offset,
+        order,
+        pageToken,
+        podId,
+        sortBy,
+        stableFilters,
+        stableParams,
+        stableSort,
+        trimmedTableName,
+    ]);
+    useEffect(() => {
+        if (!isEnabled) {
+            setRecords([]);
+            setTotal(0);
+            setNextPageToken(null);
+            setError(null);
+            setIsLoading(false);
+            return;
+        }
+        if (!autoLoad)
+            return;
+        void refresh();
+    }, [autoLoad, isEnabled, refresh]);
+    return useMemo(() => ({
+        records,
+        total,
+        nextPageToken,
+        isLoading,
+        error,
+        refresh,
+    }), [error, isLoading, nextPageToken, records, refresh, total]);
+}

package/dist/react/useRelatedRecords.d.ts

@@ -0,0 +1,43 @@
+import type { LemmaClient } from "../client.js";
+import type { Table } from "../types.js";
+export interface RelatedRecordsInclude {
+    foreignKey: string;
+    as?: string;
+    fields?: string[];
+}
+export interface RelatedRecordsResolvedInclude {
+    foreignKey: string;
+    relationKey: string;
+    relatedTable: string;
+    relatedColumn: string;
+    fields: string[];
+}
+export interface RelatedRecordsColumn {
+    key: string;
+    field: string;
+    label: string;
+    source: "base" | "related";
+    relationKey?: string;
+}
+export interface UseRelatedRecordsOptions {
+    client: LemmaClient;
+    podId?: string;
+    tableName: string;
+    baseFields?: string[];
+    include: RelatedRecordsInclude[];
+    limit?: number;
+    offset?: number;
+    enabled?: boolean;
+    autoLoad?: boolean;
+}
+export interface UseRelatedRecordsResult<TRow extends Record<string, unknown> = Record<string, unknown>> {
+    records: TRow[];
+    columns: RelatedRecordsColumn[];
+    sql: string;
+    includes: RelatedRecordsResolvedInclude[];
+    baseTable: Table | null;
+    isLoading: boolean;
+    error: Error | null;
+    refresh: () => Promise<TRow[]>;
+}
+export declare function useRelatedRecords<TRow extends Record<string, unknown> = Record<string, unknown>>({ client, podId, tableName, baseFields, include, limit, offset, enabled, autoLoad, }: UseRelatedRecordsOptions): UseRelatedRecordsResult<TRow>;

package/dist/react/useRelatedRecords.js

@@ -0,0 +1,232 @@
+import { useCallback, useEffect, useMemo, useState } from "react";
+import { buildJoinedRecordsQuery, parseForeignKeyReference } from "../datastore-query.js";
+function resolvePodClient(client, podId) {
+    if (!podId || podId === client.podId)
+        return client;
+    return client.withPod(podId);
+}
+function normalizeError(error, fallback) {
+    if (error instanceof Error)
+        return error;
+    return new Error(fallback);
+}
+function stringifyComparable(value) {
+    try {
+        return JSON.stringify(value);
+    }
+    catch {
+        return String(value);
+    }
+}
+function sentenceCase(value) {
+    return value
+        .replace(/[_\.]/g, " ")
+        .replace(/\s+/g, " ")
+        .trim()
+        .replace(/\b\w/g, (match) => match.toUpperCase());
+}
+function inferRelationKey(foreignKey, relatedTable) {
+    const stripped = foreignKey
+        .replace(/_id$/i, "")
+        .replace(/_uuid$/i, "")
+        .replace(/_fk$/i, "")
+        .trim();
+    return stripped.length > 0 ? stripped : relatedTable;
+}
+function pickDefaultBaseFields(table) {
+    const names = table.columns
+        .map((column) => column.name)
+        .filter((name) => name !== "created_at" && name !== "updated_at");
+    const prioritized = ["id", "name", "title", "label", "status", "type"];
+    const next = [];
+    prioritized.forEach((name) => {
+        if (names.includes(name) && !next.includes(name)) {
+            next.push(name);
+        }
+    });
+    names.forEach((name) => {
+        if (!next.includes(name)) {
+            next.push(name);
+        }
+    });
+    return next.slice(0, 5);
+}
+function pickDefaultRelatedFields(table, relatedColumn) {
+    const names = table.columns.map((column) => column.name);
+    const prioritized = ["id", "name", "title", "label", "email", "slug", relatedColumn];
+    const next = [];
+    prioritized.forEach((name) => {
+        if (names.includes(name) && !next.includes(name)) {
+            next.push(name);
+        }
+    });
+    if (next.length === 0 && names.length > 0) {
+        next.push(names[0]);
+    }
+    return next.slice(0, 3);
+}
+function readAliasedValue(record, prefix, field) {
+    return record[`${prefix}${field}`];
+}
+export function useRelatedRecords({ client, podId, tableName, baseFields, include, limit = 20, offset, enabled = true, autoLoad = true, }) {
+    const [records, setRecords] = useState([]);
+    const [columns, setColumns] = useState([]);
+    const [sql, setSql] = useState("");
+    const [includes, setIncludes] = useState([]);
+    const [baseTable, setBaseTable] = useState(null);
+    const [isLoading, setIsLoading] = useState(false);
+    const [error, setError] = useState(null);
+    const trimmedTableName = tableName.trim();
+    const includeKey = stringifyComparable(include);
+    const baseFieldsKey = stringifyComparable(baseFields);
+    const stableInclude = useMemo(() => include, [includeKey]);
+    const stableBaseFields = useMemo(() => baseFields, [baseFieldsKey]);
+    const isEnabled = enabled && trimmedTableName.length > 0 && stableInclude.length > 0;
+    const refresh = useCallback(async () => {
+        if (!isEnabled) {
+            setRecords([]);
+            setColumns([]);
+            setSql("");
+            setIncludes([]);
+            setBaseTable(null);
+            setError(null);
+            setIsLoading(false);
+            return [];
+        }
+        setIsLoading(true);
+        setError(null);
+        try {
+            const scopedClient = resolvePodClient(client, podId);
+            const nextBaseTable = await scopedClient.tables.get(trimmedTableName);
+            if (nextBaseTable.enable_rls) {
+                throw new Error(`Related record queries are not supported for RLS-enabled table "${trimmedTableName}". Use table-scoped record APIs instead.`);
+            }
+            setBaseTable(nextBaseTable);
+            const resolvedBaseFields = (stableBaseFields?.length ? stableBaseFields : pickDefaultBaseFields(nextBaseTable))
+                .filter((field, index, allFields) => field.trim().length > 0 && allFields.indexOf(field) === index);
+            const resolvedIncludes = await Promise.all(stableInclude.map(async (entry, index) => {
+                const baseColumn = nextBaseTable.columns.find((column) => column.name === entry.foreignKey) ?? null;
+                const reference = baseColumn?.foreign_key?.references
+                    ? parseForeignKeyReference(baseColumn.foreign_key.references)
+                    : null;
+                if (!baseColumn) {
+                    throw new Error(`Column "${entry.foreignKey}" was not found on table "${trimmedTableName}".`);
+                }
+                if (!reference) {
+                    throw new Error(`Column "${entry.foreignKey}" on "${trimmedTableName}" is not a foreign key.`);
+                }
+                const relatedTable = await scopedClient.tables.get(reference.table);
+                if (relatedTable.enable_rls) {
+                    throw new Error(`Related record queries cannot join into RLS-enabled table "${reference.table}". Use table-scoped record APIs instead.`);
+                }
+                const relationKey = entry.as?.trim() || inferRelationKey(entry.foreignKey, reference.table);
+                const relatedFields = (entry.fields?.length ? entry.fields : pickDefaultRelatedFields(relatedTable, reference.column))
+                    .filter((field, fieldIndex, allFields) => field.trim().length > 0 && allFields.indexOf(field) === fieldIndex);
+                if (relatedFields.length === 0) {
+                    throw new Error(`No display fields were resolved for relation "${entry.foreignKey}".`);
+                }
+                return {
+                    foreignKey: entry.foreignKey,
+                    relationKey,
+                    relatedTable: reference.table,
+                    relatedColumn: reference.column,
+                    fields: relatedFields,
+                    alias: `rel_${index}_${relationKey}`,
+                };
+            }));
+            const nextSql = buildJoinedRecordsQuery({
+                from: { table: trimmedTableName, alias: "base" },
+                select: [
+                    ...resolvedBaseFields.map((field) => ({
+                        table: "base",
+                        column: field,
+                        as: `base__${field}`,
+                    })),
+                    ...resolvedIncludes.flatMap((entry) => entry.fields.map((field) => ({
+                        table: entry.alias,
+                        column: field,
+                        as: `${entry.relationKey}__${field}`,
+                    }))),
+                ],
+                joins: resolvedIncludes.map((entry) => ({
+                    table: entry.relatedTable,
+                    alias: entry.alias,
+                    type: "left",
+                    on: {
+                        left: { table: "base", column: entry.foreignKey },
+                        right: { table: entry.alias, column: entry.relatedColumn },
+                    },
+                })),
+                limit,
+                offset,
+            });
+            setSql(nextSql);
+            setIncludes(resolvedIncludes.map(({ alias: _alias, ...rest }) => rest));
+            const response = await scopedClient.datastore.query(nextSql);
+            const nextColumns = [
+                ...resolvedBaseFields.map((field) => ({
+                    key: field,
+                    field,
+                    label: sentenceCase(field),
+                    source: "base",
+                })),
+                ...resolvedIncludes.flatMap((entry) => entry.fields.map((field) => ({
+                    key: `${entry.relationKey}.${field}`,
+                    field,
+                    label: `${sentenceCase(entry.relationKey)} ${sentenceCase(field)}`,
+                    source: "related",
+                    relationKey: entry.relationKey,
+                }))),
+            ];
+            const nextRecords = (response.items ?? []).map((record) => {
+                const nextRecord = {};
+                resolvedBaseFields.forEach((field) => {
+                    nextRecord[field] = readAliasedValue(record, "base__", field);
+                });
+                resolvedIncludes.forEach((entry) => {
+                    nextRecord[entry.relationKey] = entry.fields.reduce((accumulator, field) => {
+                        accumulator[field] = readAliasedValue(record, `${entry.relationKey}__`, field);
+                        return accumulator;
+                    }, {});
+                });
+                return nextRecord;
+            });
+            setColumns(nextColumns);
+            setRecords(nextRecords);
+            return nextRecords;
+        }
+        catch (refreshError) {
+            const normalized = normalizeError(refreshError, "Failed to load related records.");
+            setError(normalized);
+            return [];
+        }
+        finally {
+            setIsLoading(false);
+        }
+    }, [client, isEnabled, limit, offset, podId, stableBaseFields, stableInclude, trimmedTableName]);
+    useEffect(() => {
+        if (!isEnabled) {
+            setRecords([]);
+            setColumns([]);
+            setSql("");
+            setIncludes([]);
+            setBaseTable(null);
+            setError(null);
+            setIsLoading(false);
+            return;
+        }
+        if (!autoLoad)
+            return;
+        void refresh();
+    }, [autoLoad, isEnabled, refresh]);
+    return useMemo(() => ({
+        records,
+        columns,
+        sql,
+        includes,
+        baseTable,
+        isLoading,
+        error,
+        refresh,
+    }), [baseTable, columns, error, includes, isLoading, records, refresh, sql]);
+}