@rebasepro/client 0.7.0 → 0.9.0

package/src/collection.ts

@@ -1,162 +1,31 @@
 import { buildQueryString, FindParams, RebaseApiError, Transport } from "./transport";
 import { RebaseWebSocketClient } from "./websocket";
 import {
-    CollectionAccessor,
-    Entity,
-    FilterOperator,
-    FilterValues,
-    FindResponse,
-    WhereFieldValue,
-    WhereFilterOp,
+    FindResult,
     LogicalCondition,
+    SDKCollectionClient,
+    SDKQueryBuilderInterface,
+    WhereFilterOp,
     WhereValue
 } from "@rebasepro/types";
 
-import { QueryBuilder } from "./query_builder";
-
-function parseWhereFilter(where?: Record<string, WhereFieldValue>): FilterValues<string> | undefined {
-    if (!where) return undefined;
-    const filters: Record<string, any> = {};
-
-    const OP_TO_FILTER: Record<string, WhereFilterOp> = {
-        "eq": "==",
-        "neq": "!=",
-        "gt": ">",
-        "gte": ">=",
-        "lt": "<",
-        "lte": "<=",
-        "==": "==",
-        "!=": "!=",
-        ">": ">",
-        ">=": ">=",
-        "<": "<",
-        "<=": "<=",
-        "in": "in",
-        "nin": "not-in",
-        "not-in": "not-in",
-        "cs": "array-contains",
-        "csa": "array-contains-any",
-        "array-contains": "array-contains",
-        "array-contains-any": "array-contains-any"
-    };
-
-    const parseSingle = (rawValue: any, fieldKey: string): [WhereFilterOp, unknown] => {
-        if (rawValue === null) return ["==", null];
-        if (typeof rawValue === "boolean") return ["==", rawValue];
-        if (typeof rawValue === "number") return ["==", rawValue];
-
-        if (Array.isArray(rawValue) && rawValue.length === 2 && typeof rawValue[0] === "string") {
-            const [rawOp, val] = rawValue;
-            return [OP_TO_FILTER[rawOp] ?? "==", val];
-        }
-
-        const value = String(rawValue);
-        const dotIndex = value.indexOf(".");
-        if (dotIndex > 0) {
-            const opStr = value.substring(0, dotIndex);
-            const valStr = value.substring(dotIndex + 1);
-            let op: WhereFilterOp = "==";
-            let val: string | number | boolean | null | string[] = valStr;
-
-            switch (opStr) {
-                case "eq":
-                    op = "==";
-                    break;
-                case "neq":
-                    op = "!=";
-                    break;
-                case "gt":
-                    op = ">";
-                    break;
-                case "gte":
-                    op = ">=";
-                    break;
-                case "lt":
-                    op = "<";
-                    break;
-                case "lte":
-                    op = "<=";
-                    break;
-                case "in":
-                    op = "in";
-                    val = valStr.startsWith("(") && valStr.endsWith(")")
-                        ? valStr.slice(1, -1).split(",").map(v => v.trim())
-                        : valStr.split(",");
-                    break;
-                case "nin":
-                    op = "not-in";
-                    val = valStr.startsWith("(") && valStr.endsWith(")")
-                        ? valStr.slice(1, -1).split(",").map(v => v.trim())
-                        : valStr.split(",");
-                    break;
-                case "cs":
-                    op = "array-contains";
-                    break;
-                case "csa":
-                    op = "array-contains-any";
-                    val = valStr.startsWith("(") && valStr.endsWith(")")
-                        ? valStr.slice(1, -1).split(",").map(v => v.trim())
-                        : valStr.split(",");
-                    break;
-                default:
-                    op = "==";
-                    val = value;
-            }
-            if (val === "true") val = true;
-            else if (val === "false") val = false;
-            else if (val === "null") val = null;
-            else if (typeof val === "string" && /^[0-9]+(\.[0-9]+)?$/.test(val) && fieldKey !== "id" && !fieldKey.endsWith("_id")) val = Number(val);
-
-            return [op, val];
-        } else {
-            return ["==", value];
-        }
-    };
-
-    for (const [key, rawValue] of Object.entries(where)) {
-        if (Array.isArray(rawValue) && rawValue.length > 0 && Array.isArray(rawValue[0])) {
-            filters[key] = rawValue.map(r => parseSingle(r, key));
-        } else {
-            filters[key] = parseSingle(rawValue, key);
-        }
-    }
-    return filters;
-}
-
-/**
- * Wrap a flat row (returned by the REST API as `{ id, ...fields }`) into
- * a proper `Entity<M>` structure expected by the core framework.
- * The `id` is kept inside `values` as well, since collection properties
- * may define an `isId` field that the form binds to `formex.values`.
- */
-function rowToEntity<M extends Record<string, unknown>>(row: Record<string, unknown>, slug: string): Entity<M> {
-    return {
-        id: row.id as string | number,
-        path: slug,
-        values: row as M
-    };
-}
+import { SDKQueryBuilder } from "./sdk_query_builder";
 
 /**
- * CollectionClient extends `CollectionAccessor` from `@rebasepro/types` so that
- * `client.data` can be passed directly to the core Rebase component.
+ * The concrete, HTTP-backed implementation of the public
+ * {@link SDKCollectionClient} contract — flat rows (no Entity wrapper), plus
+ * fluent query-builder methods (`.where()`, `.orderBy()`, …).
  *
- * Additionally it exposes fluent query builder methods like `.where()`, `.orderBy()`.
+ * This is what `createRebaseClient().data.<collection>` returns. It is not a
+ * separate API from {@link SDKCollectionClient}; it only widens it with
+ * `count()`. Program against {@link SDKCollectionClient} when you want a
+ * transport-agnostic type.
  */
-export interface CollectionClient<M extends Record<string, unknown> = Record<string, unknown>> extends CollectionAccessor<M> {
-    where<K extends keyof M & string>(column: K, operator: FilterOperator, value: WhereValue<M[K]>): QueryBuilder<M>;
-    where(logicalCondition: LogicalCondition): QueryBuilder<M>;
-
-    orderBy(column: keyof M & string, ascending?: "asc" | "desc"): QueryBuilder<M>;
-
-    limit(count: number): QueryBuilder<M>;
-
-    offset(count: number): QueryBuilder<M>;
-
-    search(searchString: string): QueryBuilder<M>;
-
-    include(...relations: string[]): QueryBuilder<M>;
-
+export interface CollectionClient<
+    M extends Record<string, unknown> = Record<string, unknown>,
+    I = Partial<M>,
+    U = Partial<M>
+> extends SDKCollectionClient<M, I, U> {
     count(params?: FindParams): Promise<number>;
 }
 
@@ -164,14 +33,14 @@ export function createCollectionClient<M extends Record<string, unknown> = Recor
     const basePath = `/data/${slug}`;
 
     const client: CollectionClient<M> = {
-        async find(params?: FindParams): Promise<FindResponse<M>> {
+        async find(params?: FindParams): Promise<FindResult<M>> {
             const qs = buildQueryString(params);
             const raw = await transport.request<{
                 data: Record<string, unknown>[];
-                meta: FindResponse<M>["meta"]
+                meta: FindResult<M>["meta"]
             }>(basePath + qs, { method: "GET" });
             return {
-                data: (raw.data || []).map((row: Record<string, unknown>) => rowToEntity<M>(row, slug)),
+                data: (raw.data || []) as M[],
                 meta: raw.meta
             };
         },
@@ -180,7 +49,7 @@ export function createCollectionClient<M extends Record<string, unknown> = Recor
             try {
                 const raw = await transport.request<Record<string, unknown>>(`${basePath}/${encodeURIComponent(String(id))}`, { method: "GET" });
                 if (!raw) return undefined;
-                return rowToEntity<M>(raw, slug);
+                return raw as M;
             } catch (err) {
                 if (err instanceof RebaseApiError && err.status === 404) {
                     return undefined;
@@ -198,7 +67,7 @@ export function createCollectionClient<M extends Record<string, unknown> = Recor
                 method: "POST",
                 body: JSON.stringify(body)
             });
-            return rowToEntity<M>(raw, slug);
+            return raw as M;
         },
 
         async update(id: string | number, data: Partial<M>) {
@@ -206,11 +75,11 @@ export function createCollectionClient<M extends Record<string, unknown> = Recor
                 method: "PUT",
                 body: JSON.stringify(data)
             });
-            return rowToEntity<M>(raw, slug);
+            return raw as M;
         },
 
         async delete(id: string | number) {
-            return transport.request<void>(`${basePath}/${encodeURIComponent(String(id))}`, {
+            await transport.request<void>(`${basePath}/${encodeURIComponent(String(id))}`, {
                 method: "DELETE"
             });
         },
@@ -227,67 +96,117 @@ export function createCollectionClient<M extends Record<string, unknown> = Recor
         },
 
         // Fluent builder instantiation
-        where(columnOrCondition: string | LogicalCondition, operator?: FilterOperator, value?: unknown) {
-            const builder = new QueryBuilder<M>(client as unknown as CollectionAccessor<M>);
+        where(columnOrCondition: string | LogicalCondition, operator?: WhereFilterOp, value?: unknown) {
+            const builder = new SDKQueryBuilder<M>(client);
             if (typeof columnOrCondition === "object") {
                 return builder.where(columnOrCondition);
             }
             return builder.where(columnOrCondition as keyof M & string, operator!, value as WhereValue<M[keyof M & string]>);
         },
-        orderBy(column: keyof M & string, ascending?: "asc" | "desc") {
-            return new QueryBuilder<M>(client).orderBy(column, ascending);
+        orderBy(column: keyof M & string, direction?: "asc" | "desc") {
+            return new SDKQueryBuilder<M>(client).orderBy(column, direction);
         },
         limit(count: number) {
-            return new QueryBuilder<M>(client).limit(count);
+            return new SDKQueryBuilder<M>(client).limit(count);
         },
         offset(count: number) {
-            return new QueryBuilder<M>(client).offset(count);
+            return new SDKQueryBuilder<M>(client).offset(count);
         },
         search(searchString: string) {
-            return new QueryBuilder<M>(client).search(searchString);
+            return new SDKQueryBuilder<M>(client).search(searchString);
         },
         include(...relations: string[]) {
-            return new QueryBuilder<M>(client).include(...relations);
+            return new SDKQueryBuilder<M>(client).include(...relations);
         }
     };
 
     if (ws) {
-        client.listen = (params: FindParams | undefined, onUpdate: (response: FindResponse<M>) => void, onError?: (error: Error) => void) => {
-            return ws.listenCollection(
+        client.listen = (params: FindParams | undefined, onUpdate: (response: FindResult<M>) => void, onError?: (error: Error) => void) => {
+            let active = true;
+            let lastUpdateId = 0;
+            const unsub = ws.listenCollection(
                 {
                     path: slug,
-                    filter: parseWhereFilter(params?.where),
+                    filter: params?.where,
                     limit: params?.limit,
                     startAfter: params?.offset ? String(params.offset) : undefined,
-                    orderBy: params?.orderBy?.split(":")[0],
-                    order: params?.orderBy?.split(":")[1] as "asc" | "desc",
+                    orderBy: params?.orderBy?.[0],
+                    order: params?.orderBy?.[1],
                     searchString: params?.searchString
                 },
-                (entities: Entity[]) => {
+                (incomingRows: Record<string, unknown>[]) => {
+                    const currentUpdateId = ++lastUpdateId;
                     const requestedLimit = params?.limit || 20;
-                    onUpdate({
-                        data: entities as Entity<M>[],
-                        meta: {
-                            total: entities.length,
-                            limit: requestedLimit,
-                            offset: params?.offset || 0,
-                            hasMore: entities.length >= requestedLimit
-                        }
-                    });
+                    const offset = params?.offset || 0;
+
+                    // WS client already delivers flat rows — just cast
+                    const rows = incomingRows as M[];
+
+                    // Heuristic metadata (used as fallback if count call fails)
+                    const heuristicTotal = rows.length;
+                    const heuristicHasMore = rows.length >= requestedLimit;
+
+                    // Try to get authoritative count; fall back to heuristic
+                    if (client.count) {
+                        client.count(params)
+                            .then((total) => {
+                                if (active && currentUpdateId === lastUpdateId) {
+                                    onUpdate({
+                                        data: rows,
+                                        meta: {
+                                            total,
+                                            limit: requestedLimit,
+                                            offset,
+                                            hasMore: offset + rows.length < total
+                                        }
+                                    });
+                                }
+                            })
+                            .catch(() => {
+                                // Count failed — use heuristic meta
+                                if (active && currentUpdateId === lastUpdateId) {
+                                    onUpdate({
+                                        data: rows,
+                                        meta: {
+                                            total: heuristicTotal,
+                                            limit: requestedLimit,
+                                            offset,
+                                            hasMore: heuristicHasMore
+                                        }
+                                    });
+                                }
+                            });
+                    } else {
+                        // No count method — fire immediately with heuristic meta
+                        onUpdate({
+                            data: rows,
+                            meta: {
+                                total: heuristicTotal,
+                                limit: requestedLimit,
+                                offset,
+                                hasMore: heuristicHasMore
+                            }
+                        });
+                    }
                 },
                 onError
             );
+
+            return () => {
+                active = false;
+                unsub();
+            };
         };
 
-        client.listenById = (id: string | number, onUpdate: (data: Entity<M> | undefined) => void, onError?: (error: Error) => void) => {
-            return ws.listenEntity(
+        client.listenById = (id: string | number, onUpdate: (data: M | undefined) => void, onError?: (error: Error) => void) => {
+            return ws.listenOne(
                 {
                     path: slug,
-                    entityId: String(id)
+                    id: String(id)
                 },
-                (entity: Entity | null) => {
-                    if (entity) {
-                        onUpdate(entity as Entity<M>);
+                (row: Record<string, unknown> | null) => {
+                    if (row) {
+                        onUpdate(row as M);
                     } else {
                         onUpdate(undefined);
                     }

package/src/data-proxy.test.ts

@@ -0,0 +1,167 @@
+import { jest } from "@jest/globals";
+import { createRebaseClient, RebaseClientError } from "./index";
+
+// Minimal mock: we only need the proxy behavior, not real HTTP calls.
+// The global fetch mock prevents the transport from making real requests.
+const originalFetch = globalThis.fetch;
+beforeAll(() => {
+    globalThis.fetch = jest.fn<typeof fetch>().mockResolvedValue(new Response("{}")) as typeof fetch;
+});
+afterAll(() => {
+    globalThis.fetch = originalFetch;
+});
+
+const COLLECTIONS = {
+    products: "products",
+    orders: "orders",
+    blogPosts: "blog-posts",
+    companyMembers: "company_members",
+} as const;
+
+describe("client.data proxy — strict mode (collections dictionary provided)", () => {
+    const client = createRebaseClient({
+        baseUrl: "http://localhost:3000",
+        collections: { ...COLLECTIONS },
+    });
+
+    it("resolves a known key to a CollectionClient", () => {
+        const accessor = client.data.collection("products");
+        expect(accessor).toBeDefined();
+        expect(typeof accessor.find).toBe("function");
+        expect(typeof accessor.findById).toBe("function");
+        expect(typeof accessor.create).toBe("function");
+    });
+
+    it("resolves a known camelCase key (blogPosts) via dictionary", () => {
+        // Should not throw — blogPosts is in the dictionary
+        const products = (client.data as Record<string, unknown>)["products"];
+        expect(products).toBeDefined();
+        const blogPosts = (client.data as Record<string, unknown>)["blogPosts"];
+        expect(blogPosts).toBeDefined();
+    });
+
+    it("throws RebaseClientError on unknown key with suggestion", () => {
+        const access = () => (client.data as Record<string, unknown>)["prodcuts"];
+        expect(access).toThrow(RebaseClientError);
+
+        try {
+            access();
+        } catch (e) {
+            expect(e).toBeInstanceOf(RebaseClientError);
+            expect((e as RebaseClientError).message).toContain("prodcuts");
+            expect((e as RebaseClientError).message).toContain("products");
+            expect((e as RebaseClientError).message).toContain("Did you mean");
+            expect((e as RebaseClientError).message).toContain("data.collection");
+        }
+    });
+
+    it("throws RebaseClientError on unknown key without a close match", () => {
+        const access = () => (client.data as Record<string, unknown>)["zzz"];
+        expect(access).toThrow(RebaseClientError);
+
+        try {
+            access();
+        } catch (e) {
+            expect(e).toBeInstanceOf(RebaseClientError);
+            expect((e as RebaseClientError).message).toContain("zzz");
+            expect((e as RebaseClientError).message).not.toContain("Did you mean");
+        }
+    });
+
+    it("lists all known collections in the error message", () => {
+        const access = () => (client.data as Record<string, unknown>)["nonexistent"];
+        try {
+            access();
+        } catch (e) {
+            const msg = (e as RebaseClientError).message;
+            expect(msg).toContain("products");
+            expect(msg).toContain("orders");
+            expect(msg).toContain("blogPosts");
+            expect(msg).toContain("companyMembers");
+        }
+    });
+
+    it("returns undefined for symbol access", () => {
+        expect((client.data as Record<symbol, unknown>)[Symbol.toPrimitive]).toBeUndefined();
+        expect((client.data as Record<symbol, unknown>)[Symbol.iterator]).toBeUndefined();
+    });
+
+    it("returns undefined for 'then' (Promise resolution safe)", () => {
+        expect((client.data as Record<string, unknown>)["then"]).toBeUndefined();
+    });
+
+    it("returns undefined for 'toJSON'", () => {
+        expect((client.data as Record<string, unknown>)["toJSON"]).toBeUndefined();
+    });
+
+    it("returns undefined for '$$typeof' (React introspection safe)", () => {
+        expect((client.data as Record<string, unknown>)["$$typeof"]).toBeUndefined();
+    });
+
+    it("does not throw when awaited in a Promise.resolve context", async () => {
+        // `await obj` checks obj.then — which must return undefined, not throw.
+        const result = await Promise.resolve(client.data as Record<string, unknown>);
+        expect(result).toBeDefined();
+    });
+
+    it("collection('anything') never throws — dynamic escape hatch", () => {
+        expect(() => client.data.collection("nonexistent")).not.toThrow();
+        expect(() => client.data.collection("totally-made-up")).not.toThrow();
+        const col = client.data.collection("dynamic-slug");
+        expect(col).toBeDefined();
+        expect(typeof col.find).toBe("function");
+    });
+});
+
+describe("client.data proxy — untyped mode (no collections dictionary)", () => {
+    const client = createRebaseClient({
+        baseUrl: "http://localhost:3000",
+    });
+
+    it("falls back to snake_case conversion without a dictionary", () => {
+        // Should not throw for any property name
+        expect(() => (client.data as Record<string, unknown>)["blogPosts"]).not.toThrow();
+        expect(() => (client.data as Record<string, unknown>)["anyRandomProp"]).not.toThrow();
+    });
+
+    it("returns a CollectionClient for any camelCase property", () => {
+        const accessor = (client.data as Record<string, unknown>)["blogPosts"];
+        expect(accessor).toBeDefined();
+        expect(typeof (accessor as Record<string, unknown>).find).toBe("function");
+    });
+
+    it("returns undefined for symbols, then, toJSON, $$typeof", () => {
+        expect((client.data as Record<symbol, unknown>)[Symbol.toPrimitive]).toBeUndefined();
+        expect((client.data as Record<string, unknown>)["then"]).toBeUndefined();
+        expect((client.data as Record<string, unknown>)["toJSON"]).toBeUndefined();
+        expect((client.data as Record<string, unknown>)["$$typeof"]).toBeUndefined();
+    });
+
+    it("collection() still works without a dictionary", () => {
+        expect(() => client.data.collection("anything")).not.toThrow();
+    });
+
+    it("emits a one-shot console.warn on first untyped access", () => {
+        const warnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+        try {
+            // Create a fresh client so the warning flag is reset
+            const freshClient = createRebaseClient({
+                baseUrl: "http://localhost:3000",
+            });
+            const readFirst = () => (freshClient.data as Record<string, unknown>)["firstAccess"];
+            readFirst();
+            expect(warnSpy).toHaveBeenCalledTimes(1);
+            expect(warnSpy).toHaveBeenCalledWith(
+                expect.stringContaining("[Rebase] Untyped data access detected")
+            );
+
+            // Second access should NOT warn again
+            warnSpy.mockClear();
+            const readSecond = () => (freshClient.data as Record<string, unknown>)["secondAccess"];
+            readSecond();
+            expect(warnSpy).not.toHaveBeenCalled();
+        } finally {
+            warnSpy.mockRestore();
+        }
+    });
+});

package/src/errors.ts

@@ -0,0 +1,9 @@
+/**
+ * Client-side logic error (e.g. accessing an unknown collection when a typed
+ * dictionary is available). A subclass of {@link RebaseApiError}, so a single
+ * `catch (e) { if (e instanceof RebaseApiError) ... }` covers it too.
+ *
+ * The canonical definition now lives in `@rebasepro/types`; re-exported here to
+ * preserve the historical `import { RebaseClientError } from ".../errors"` path.
+ */
+export { RebaseClientError } from "@rebasepro/types";