lemma-sdk 0.2.30 → 0.2.32

package/dist/react/useRecords.js

@@ -1,27 +1,11 @@
 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);
-    }
-}
+import { normalizeError, resolvePodClient, stringifyComparable } from "./utils.js";
 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 [isLoadingMore, setIsLoadingMore] = useState(false);
     const [error, setError] = useState(null);
     const trimmedTableName = tableName.trim();
     const isEnabled = enabled && trimmedTableName.length > 0;
@@ -31,7 +15,7 @@ export function useRecords({ client, podId, tableName, filters, sort, limit = 20
     const stableFilters = useMemo(() => filters, [filtersKey]);
     const stableSort = useMemo(() => sort, [sortKey]);
     const stableParams = useMemo(() => params, [paramsKey]);
-    const refresh = useCallback(async (overrides = {}) => {
+    const refresh = useCallback(async (overrides = {}, signal) => {
         if (!isEnabled) {
             setRecords([]);
             setTotal(0);
@@ -54,6 +38,8 @@ export function useRecords({ client, podId, tableName, filters, sort, limit = 20
                 order: overrides.order ?? order,
                 params: overrides.params ?? stableParams,
             });
+            if (signal?.aborted)
+                return [];
             const nextRecords = (response.items ?? []);
             setRecords(nextRecords);
             setTotal(response.total ?? nextRecords.length);
@@ -61,12 +47,15 @@ export function useRecords({ client, podId, tableName, filters, sort, limit = 20
             return nextRecords;
         }
         catch (refreshError) {
+            if (signal?.aborted)
+                return [];
             const normalized = normalizeError(refreshError, "Failed to load records.");
             setError(normalized);
             return [];
         }
         finally {
-            setIsLoading(false);
+            if (!signal?.aborted)
+                setIsLoading(false);
         }
     }, [
         client,
@@ -82,6 +71,39 @@ export function useRecords({ client, podId, tableName, filters, sort, limit = 20
         stableSort,
         trimmedTableName,
     ]);
+    const loadMore = useCallback(async (overrides = {}) => {
+        if (!isEnabled || !nextPageToken || isLoading || isLoadingMore) {
+            return [];
+        }
+        setIsLoadingMore(true);
+        setError(null);
+        try {
+            const scopedClient = resolvePodClient(client, podId);
+            const response = await scopedClient.records.list(trimmedTableName, {
+                filters: stableFilters,
+                sort: stableSort,
+                limit: overrides.limit ?? limit,
+                pageToken: nextPageToken,
+                offset: overrides.offset,
+                sortBy: overrides.sortBy ?? sortBy,
+                order: overrides.order ?? order,
+                params: overrides.params ?? stableParams,
+            });
+            const moreRecords = (response.items ?? []);
+            setRecords((previous) => [...previous, ...moreRecords]);
+            setTotal(response.total ?? records.length + moreRecords.length);
+            setNextPageToken(response.next_page_token ?? null);
+            return moreRecords;
+        }
+        catch (loadError) {
+            const normalized = normalizeError(loadError, "Failed to load more records.");
+            setError(normalized);
+            return [];
+        }
+        finally {
+            setIsLoadingMore(false);
+        }
+    }, [client, isEnabled, isLoading, isLoadingMore, limit, nextPageToken, offset, order, podId, records.length, sortBy, stableFilters, stableParams, stableSort, trimmedTableName]);
     useEffect(() => {
         if (!isEnabled) {
             setRecords([]);
@@ -89,18 +111,36 @@ export function useRecords({ client, podId, tableName, filters, sort, limit = 20
             setNextPageToken(null);
             setError(null);
             setIsLoading(false);
+            setIsLoadingMore(false);
             return;
         }
         if (!autoLoad)
             return;
-        void refresh();
+        const controller = new AbortController();
+        let cancelled = false;
+        (async () => {
+            try {
+                await refresh({}, controller.signal);
+            }
+            catch {
+                if (!cancelled) {
+                    setError(normalizeError(new Error("Failed to load records."), "Failed to load records."));
+                }
+            }
+        })();
+        return () => {
+            cancelled = true;
+            controller.abort();
+        };
     }, [autoLoad, isEnabled, refresh]);
     return useMemo(() => ({
         records,
         total,
         nextPageToken,
         isLoading,
+        isLoadingMore,
         error,
         refresh,
-    }), [error, isLoading, nextPageToken, records, refresh, total]);
+        loadMore,
+    }), [error, isLoading, isLoadingMore, loadMore, nextPageToken, records, refresh, total]);
 }

package/dist/react/useReferencingRecords.d.ts

@@ -0,0 +1,66 @@
+import type { LemmaClient } from "../client.js";
+import type { Table } from "../types.js";
+/**
+ * React hook for fetching records from a referencing table that point back
+ * to a specific record via a foreign key.
+ *
+ * Unlike `useReverseRelatedRecords` which starts from a parent table and
+ * discovers what references it, this hook starts from the child table and
+ * says "give me all rows in this table where this FK column equals this ID."
+ *
+ * @example Fetch all comments for an issue
+ * ```tsx
+ * const { records, isLoading } = useReferencingRecords({
+ *   client,
+ *   table: "comments",
+ *   foreignKey: "issue_id",
+ *   recordId: "issue_123",
+ * });
+ * ```
+ *
+ * @example Fetch history entries
+ * ```tsx
+ * const { records, columns, isLoading } = useReferencingRecords({
+ *   client,
+ *   table: "issue_history",
+ *   foreignKey: "issue_id",
+ *   recordId: selectedIssueId,
+ *   sortBy: "created_at",
+ *   order: "desc",
+ * });
+ * ```
+ */
+export interface ReferencingRecordsColumn {
+    key: string;
+    field: string;
+    label: string;
+}
+export interface UseReferencingRecordsOptions {
+    client: LemmaClient;
+    podId?: string;
+    /** The referencing (child) table, e.g. "comments". */
+    table: string;
+    /** The foreign-key column in the referencing table, e.g. "issue_id". */
+    foreignKey: string;
+    /** The record ID value to match against the foreign-key column. */
+    recordId?: string | null;
+    /** Fields to select. Auto-resolved from the table schema if omitted. */
+    fields?: string[];
+    limit?: number;
+    offset?: number;
+    sortBy?: string;
+    order?: "asc" | "desc" | string;
+    enabled?: boolean;
+    autoLoad?: boolean;
+}
+export interface UseReferencingRecordsResult<TRow extends Record<string, unknown> = Record<string, unknown>> {
+    referencedTable: Table | null;
+    columns: ReferencingRecordsColumn[];
+    records: TRow[];
+    total: number;
+    nextPageToken: string | null;
+    isLoading: boolean;
+    error: Error | null;
+    refresh: () => Promise<TRow[]>;
+}
+export declare function useReferencingRecords<TRow extends Record<string, unknown> = Record<string, unknown>>({ client, podId, table, foreignKey, recordId, fields, limit, offset, sortBy, order, enabled, autoLoad, }: UseReferencingRecordsOptions): UseReferencingRecordsResult<TRow>;

package/dist/react/useReferencingRecords.js

@@ -0,0 +1,159 @@
+import { useCallback, useEffect, useMemo, useState } from "react";
+import { normalizeError, resolvePodClient, stringifyComparable } from "./utils.js";
+function sentenceCase(value) {
+    return value
+        .replace(/[_\.]/g, " ")
+        .replace(/\s+/g, " ")
+        .trim()
+        .replace(/\b\w/g, (match) => match.toUpperCase());
+}
+function pickDefaultFields(table, foreignKey) {
+    const names = table.columns
+        .map((column) => column.name)
+        .filter((name) => name !== "created_at" && name !== "updated_at");
+    const prioritized = ["id", "name", "title", "label", "status", foreignKey];
+    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, 6);
+}
+export function useReferencingRecords({ client, podId, table, foreignKey, recordId = null, fields, limit = 20, offset, sortBy, order, enabled = true, autoLoad = true, }) {
+    const [referencedTable, setReferencedTable] = useState(null);
+    const [columns, setColumns] = useState([]);
+    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 trimmedTable = table.trim();
+    const trimmedRecordId = typeof recordId === "string" ? recordId.trim() : "";
+    const fieldsKey = stringifyComparable(fields);
+    const stableFields = useMemo(() => fields, [fieldsKey]);
+    const isEnabled = enabled && trimmedTable.length > 0 && trimmedRecordId.length > 0;
+    const refresh = useCallback(async (signal) => {
+        if (!isEnabled) {
+            setReferencedTable(null);
+            setColumns([]);
+            setRecords([]);
+            setTotal(0);
+            setNextPageToken(null);
+            setError(null);
+            setIsLoading(false);
+            return [];
+        }
+        setIsLoading(true);
+        setError(null);
+        try {
+            const scopedClient = resolvePodClient(client, podId);
+            const tableResponse = await scopedClient.tables.get(trimmedTable);
+            if (signal?.aborted)
+                return [];
+            setReferencedTable(tableResponse);
+            const resolvedFields = (stableFields?.length ? stableFields : pickDefaultFields(tableResponse, foreignKey))
+                .filter((field, index, allFields) => field.trim().length > 0 && allFields.indexOf(field) === index);
+            const response = await scopedClient.records.list(trimmedTable, {
+                filters: [{
+                        field: foreignKey,
+                        op: "eq",
+                        value: trimmedRecordId,
+                    }],
+                limit,
+                offset,
+                sortBy,
+                order,
+            });
+            if (signal?.aborted)
+                return [];
+            const nextRecords = (response.items ?? []);
+            setColumns(resolvedFields.map((field) => ({
+                key: field,
+                field,
+                label: sentenceCase(field),
+            })));
+            setRecords(nextRecords);
+            setTotal(response.total ?? nextRecords.length);
+            setNextPageToken(response.next_page_token ?? null);
+            return nextRecords;
+        }
+        catch (refreshError) {
+            if (signal?.aborted)
+                return [];
+            const normalized = normalizeError(refreshError, "Failed to load referencing records.");
+            setError(normalized);
+            return [];
+        }
+        finally {
+            if (!signal?.aborted)
+                setIsLoading(false);
+        }
+    }, [
+        client,
+        foreignKey,
+        isEnabled,
+        limit,
+        offset,
+        order,
+        podId,
+        sortBy,
+        stableFields,
+        trimmedRecordId,
+        trimmedTable,
+    ]);
+    useEffect(() => {
+        if (!isEnabled) {
+            setReferencedTable(null);
+            setColumns([]);
+            setRecords([]);
+            setTotal(0);
+            setNextPageToken(null);
+            setError(null);
+            setIsLoading(false);
+            return;
+        }
+        if (!autoLoad)
+            return;
+        const controller = new AbortController();
+        let cancelled = false;
+        (async () => {
+            try {
+                await refresh(controller.signal);
+            }
+            catch {
+                if (!cancelled) {
+                    setError(normalizeError(new Error("Failed to load referencing records."), "Failed to load referencing records."));
+                }
+            }
+        })();
+        return () => {
+            cancelled = true;
+            controller.abort();
+        };
+    }, [autoLoad, isEnabled, refresh]);
+    return useMemo(() => ({
+        referencedTable,
+        columns,
+        records,
+        total,
+        nextPageToken,
+        isLoading,
+        error,
+        refresh,
+    }), [
+        columns,
+        error,
+        isLoading,
+        nextPageToken,
+        records,
+        refresh,
+        referencedTable,
+        total,
+    ]);
+}

package/dist/react/useRelatedRecords.d.ts

@@ -1,5 +1,22 @@
 import type { LemmaClient } from "../client.js";
 import type { Table } from "../types.js";
+/**
+ * React hook for fetching base-table rows with their FK-related data
+ * joined in a single query. You specify which FK columns to include and
+ * the hook auto-resolves the referenced table and join columns.
+ *
+ * The result has nested objects: `{ id, name, team: { id, name } }`.
+ *
+ * @example Issues with their team
+ * ```tsx
+ * const { records, isLoading } = useRelatedRecords({
+ *   client,
+ *   tableName: "issues",
+ *   include: [{ foreignKey: "team_id" }],
+ * });
+ * // records[0] = { id: "1", title: "Bug", team: { id: "t1", name: "Eng" } }
+ * ```
+ */
 export interface RelatedRecordsInclude {
     foreignKey: string;
     as?: string;

package/dist/react/useRelatedRecords.js

@@ -1,23 +1,6 @@
 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);
-    }
-}
+import { normalizeError, resolvePodClient, stringifyComparable } from "./utils.js";
 function sentenceCase(value) {
     return value
         .replace(/[_\.]/g, " ")
@@ -82,7 +65,7 @@ export function useRelatedRecords({ client, podId, tableName, baseFields, includ
     const stableInclude = useMemo(() => include, [includeKey]);
     const stableBaseFields = useMemo(() => baseFields, [baseFieldsKey]);
     const isEnabled = enabled && trimmedTableName.length > 0 && stableInclude.length > 0;
-    const refresh = useCallback(async () => {
+    const refresh = useCallback(async (signal) => {
         if (!isEnabled) {
             setRecords([]);
             setColumns([]);
@@ -98,6 +81,8 @@ export function useRelatedRecords({ client, podId, tableName, baseFields, includ
         try {
             const scopedClient = resolvePodClient(client, podId);
             const nextBaseTable = await scopedClient.tables.get(trimmedTableName);
+            if (signal?.aborted)
+                return [];
             if (nextBaseTable.enable_rls) {
                 throw new Error(`Related record queries are not supported for RLS-enabled table "${trimmedTableName}". Use table-scoped record APIs instead.`);
             }
@@ -105,6 +90,8 @@ export function useRelatedRecords({ client, podId, tableName, baseFields, includ
             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) => {
+                if (signal?.aborted)
+                    throw new Error("Aborted");
                 const baseColumn = nextBaseTable.columns.find((column) => column.name === entry.foreignKey) ?? null;
                 const reference = baseColumn?.foreign_key?.references
                     ? parseForeignKeyReference(baseColumn.foreign_key.references)
@@ -163,6 +150,8 @@ export function useRelatedRecords({ client, podId, tableName, baseFields, includ
             setSql(nextSql);
             setIncludes(resolvedIncludes.map(({ alias: _alias, ...rest }) => rest));
             const response = await scopedClient.datastore.query(nextSql);
+            if (signal?.aborted)
+                return [];
             const nextColumns = [
                 ...resolvedBaseFields.map((field) => ({
                     key: field,
@@ -196,12 +185,15 @@ export function useRelatedRecords({ client, podId, tableName, baseFields, includ
             return nextRecords;
         }
         catch (refreshError) {
+            if (signal?.aborted)
+                return [];
             const normalized = normalizeError(refreshError, "Failed to load related records.");
             setError(normalized);
             return [];
         }
         finally {
-            setIsLoading(false);
+            if (!signal?.aborted)
+                setIsLoading(false);
         }
     }, [client, isEnabled, limit, offset, podId, stableBaseFields, stableInclude, trimmedTableName]);
     useEffect(() => {
@@ -217,7 +209,22 @@ export function useRelatedRecords({ client, podId, tableName, baseFields, includ
         }
         if (!autoLoad)
             return;
-        void refresh();
+        const controller = new AbortController();
+        let cancelled = false;
+        (async () => {
+            try {
+                await refresh(controller.signal);
+            }
+            catch {
+                if (!cancelled) {
+                    setError(normalizeError(new Error("Failed to load related records."), "Failed to load related records."));
+                }
+            }
+        })();
+        return () => {
+            cancelled = true;
+            controller.abort();
+        };
     }, [autoLoad, isEnabled, refresh]);
     return useMemo(() => ({
         records,

package/dist/react/useReverseRelatedRecords.d.ts

@@ -1,5 +1,26 @@
 import type { LemmaClient } from "../client.js";
 import type { Table } from "../types.js";
+/**
+ * React hook for finding records in *other* tables that reference a given
+ * record. Starts from the parent table, discovers all tables with FK
+ * columns pointing back to it, and fetches the referencing rows.
+ *
+ * For the simpler case where you already know the referencing table and
+ * FK column, prefer `useReferencingRecords` — it has a more intuitive API.
+ *
+ * @example All comments and history entries for an issue
+ * ```tsx
+ * const { relations, records, isLoading } = useReverseRelatedRecords({
+ *   client,
+ *   tableName: "issues",
+ *   recordId: "issue_123",
+ *   relation: { tableName: "comments", foreignKey: "issue_id" },
+ * });
+ * ```
+ *
+ * @see useReferencingRecords — flipped-perspective alias for the common
+ *   "show me all rows in table X where FK = Y" pattern.
+ */
 export interface ReverseRelationSelector {
     tableName: string;
     foreignKey: string;

package/dist/react/useReverseRelatedRecords.js

@@ -1,23 +1,6 @@
 import { useCallback, useEffect, useMemo, useState } from "react";
 import { 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);
-    }
-}
+import { normalizeError, resolvePodClient, stringifyComparable } from "./utils.js";
 function sentenceCase(value) {
     return value
         .replace(/[_\.]/g, " ")
@@ -62,7 +45,7 @@ export function useReverseRelatedRecords({ client, podId, tableName, recordId =
     const stableRelation = useMemo(() => relation, [relationKey]);
     const stableFields = useMemo(() => fields, [fieldsKey]);
     const isEnabled = enabled && trimmedTableName.length > 0 && trimmedRecordId.length > 0;
-    const refresh = useCallback(async () => {
+    const refresh = useCallback(async (signal) => {
         if (!isEnabled) {
             setParentTable(null);
             setRelatedTable(null);
@@ -85,10 +68,14 @@ export function useReverseRelatedRecords({ client, podId, tableName, recordId =
                 scopedClient.tables.list({ limit: tablesLimit }),
                 scopedClient.records.get(trimmedTableName, trimmedRecordId),
             ]);
+            if (signal?.aborted)
+                return [];
             const listedTables = tablesResponse.items ?? [];
             const nextParentTable = listedTables.find((tableEntry) => tableEntry.name === trimmedTableName)
                 ?? await scopedClient.tables.get(trimmedTableName);
             const nextParentRecord = parentRecordResponse.data ?? null;
+            if (signal?.aborted)
+                return [];
             setParentTable(nextParentTable);
             setParentRecord(nextParentRecord);
             const nextRelations = listedTables.flatMap((candidateTable) => candidateTable.columns.flatMap((column) => {
@@ -123,6 +110,8 @@ export function useReverseRelatedRecords({ client, podId, tableName, recordId =
                 ?? await scopedClient.tables.get(nextSelectedRelation.tableName);
             const referenceValue = nextParentRecord?.[nextSelectedRelation.referencedColumn]
                 ?? (nextSelectedRelation.referencedColumn === "id" ? trimmedRecordId : undefined);
+            if (signal?.aborted)
+                return [];
             setRelatedTable(nextRelatedTable);
             if (typeof referenceValue === "undefined" || referenceValue === null) {
                 setColumns([]);
@@ -144,6 +133,8 @@ export function useReverseRelatedRecords({ client, podId, tableName, recordId =
                 sortBy,
                 order,
             });
+            if (signal?.aborted)
+                return [];
             const nextRecords = (response.items ?? []);
             setColumns(resolvedFields.map((field) => ({
                 key: field,
@@ -156,12 +147,15 @@ export function useReverseRelatedRecords({ client, podId, tableName, recordId =
             return nextRecords;
         }
         catch (refreshError) {
+            if (signal?.aborted)
+                return [];
             const normalized = normalizeError(refreshError, "Failed to load reverse-related records.");
             setError(normalized);
             return [];
         }
         finally {
-            setIsLoading(false);
+            if (!signal?.aborted)
+                setIsLoading(false);
         }
     }, [
         client,
@@ -194,7 +188,22 @@ export function useReverseRelatedRecords({ client, podId, tableName, recordId =
         }
         if (!autoLoad)
             return;
-        void refresh();
+        const controller = new AbortController();
+        let cancelled = false;
+        (async () => {
+            try {
+                await refresh(controller.signal);
+            }
+            catch {
+                if (!cancelled) {
+                    setError(normalizeError(new Error("Failed to load reverse-related records."), "Failed to load reverse-related records."));
+                }
+            }
+        })();
+        return () => {
+            cancelled = true;
+            controller.abort();
+        };
     }, [autoLoad, isEnabled, refresh]);
     return useMemo(() => ({
         parentTable,

package/dist/react/useSchemaForm.js

@@ -1,18 +1,6 @@
 import { useCallback, useEffect, useMemo, useState } from "react";
 import { buildSchemaFormFields, buildSchemaFormPayload, buildSchemaFormValues, } from "../schema-form.js";
-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);
-    }
-}
+import { normalizeError, stringifyComparable } from "./utils.js";
 const EMPTY_VALUES = {};
 export function useSchemaForm({ schema = null, uiSchema = null, initialValues = EMPTY_VALUES, enabled = true, onSubmit, onError, }) {
     const [values, setValuesState] = useState({});