@rebasepro/sdk-generator 0.2.1 → 0.2.3

package/dist/common/src/data/query_builder.d.ts

@@ -0,0 +1,51 @@
+import { FindResponse, CollectionAccessor, QueryBuilderInterface, FilterOperator } from "@rebasepro/types";
+export declare class QueryBuilder<M extends Record<string, unknown> = Record<string, unknown>> implements QueryBuilderInterface<M> {
+    private collection;
+    private params;
+    constructor(collection: CollectionAccessor<M>);
+    /**
+     * Add a filter condition to your query.
+     * @example
+     * client.collection('users').where('age', '>=', 18).find()
+     */
+    where(column: keyof M & string, operator: FilterOperator, value: unknown): this;
+    /**
+     * Order the results by a specific column.
+     * @example
+     * client.collection('users').orderBy('createdAt', 'desc').find()
+     */
+    orderBy(column: keyof M & string, ascending?: "asc" | "desc"): this;
+    /**
+     * Limit the number of results returned.
+     */
+    limit(count: number): this;
+    /**
+     * Skip the first N results.
+     */
+    offset(count: number): this;
+    /**
+     * Set a free-text search string if supported by the backend.
+     */
+    search(searchString: string): this;
+    /**
+     * Include related entities in the response.
+     * Relations will be populated with full entity data instead of just IDs.
+     *
+     * @param relations - Relation names to include, or "*" for all.
+     * @example
+     * // Include specific relations
+     * client.data.posts.include("tags", "author").find()
+     *
+     * // Include all relations
+     * client.data.posts.include("*").find()
+     */
+    include(...relations: string[]): this;
+    /**
+     * Execute the find query and return the results.
+     */
+    find(): Promise<FindResponse<M>>;
+    /**
+     * Listen to realtime updates matching this query.
+     */
+    listen(onUpdate: (data: FindResponse<M>) => void, onError?: (error: Error) => void): () => void;
+}

package/dist/common/src/index.d.ts

@@ -1,3 +1,4 @@
 export * from "./util";
 export * from "./collections";
 export * from "./data/buildRebaseData";
+export * from "./data/query_builder";

package/dist/types/src/controllers/data.d.ts

@@ -76,6 +76,21 @@ export interface FindResponse<M extends Record<string, unknown> = Record<string,
         hasMore: boolean;
     };
 }
+export type FilterOperator = WhereFilterOpShort;
+/**
+ * Fluent Query Builder Interface supported on both client and server accessors.
+ * @group Data
+ */
+export interface QueryBuilderInterface<M extends Record<string, unknown> = Record<string, unknown>> {
+    where(column: keyof M & string, operator: FilterOperator, value: unknown): this;
+    orderBy(column: keyof M & string, ascending?: "asc" | "desc"): this;
+    limit(count: number): this;
+    offset(count: number): this;
+    search(searchString: string): this;
+    include(...relations: string[]): this;
+    find(): Promise<FindResponse<M>>;
+    listen(onUpdate: (data: FindResponse<M>) => void, onError?: (error: Error) => void): () => void;
+}
 /**
  * A single collection's CRUD accessor.
  *
@@ -124,6 +139,12 @@ export interface CollectionAccessor<M extends Record<string, unknown> = Record<s
      * Count the number of records matching the given filter.
      */
     count?(params?: FindParams): Promise<number>;
+    where(column: keyof M & string, operator: FilterOperator, value: unknown): QueryBuilderInterface<M>;
+    orderBy(column: keyof M & string, ascending?: "asc" | "desc"): QueryBuilderInterface<M>;
+    limit(count: number): QueryBuilderInterface<M>;
+    offset(count: number): QueryBuilderInterface<M>;
+    search(searchString: string): QueryBuilderInterface<M>;
+    include(...relations: string[]): QueryBuilderInterface<M>;
 }
 /**
  * The unified data access object.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rebasepro/sdk-generator",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "Generate a typed JS SDK from Rebase collection definitions",
   "main": "./dist/index.cjs",
   "module": "./dist/index.es.js",
@@ -19,8 +19,8 @@
   "author": "rebase.pro",
   "license": "MIT",
   "peerDependencies": {
-    "@rebasepro/common": "0.2.1",
-    "@rebasepro/types": "0.2.1"
+    "@rebasepro/common": "0.2.3",
+    "@rebasepro/types": "0.2.3"
   },
   "devDependencies": {
     "@jest/globals": "^29.7.0",
@@ -30,8 +30,8 @@
     "ts-jest": "^29.4.10",
     "typescript": "^5.9.3",
     "vite": "^7.3.3",
-    "@rebasepro/common": "0.2.1",
-    "@rebasepro/types": "0.2.1"
+    "@rebasepro/common": "0.2.3",
+    "@rebasepro/types": "0.2.3"
   },
   "exports": {
     ".": {
@@ -42,7 +42,12 @@
   },
   "gitHead": "d935eefa5aa8d1009a2398cfac2c1e4ee9aeb6b6",
   "dependencies": {
-    "@rebasepro/client": "0.2.1"
+    "@rebasepro/client": "0.2.3"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/rebasepro/rebase.git",
+    "directory": "packages/sdk-generator"
   },
   "scripts": {
     "test": "jest --config jest.config.cjs",

package/test/sdk-generator.test.ts

@@ -12,15 +12,9 @@ const authorsCollection = {
     slug: "authors",
     table: "authors",
     properties: {
-        id: { name: "ID",
-type: "number",
-isId: "increment",
-validation: { required: true } },
-        name: { name: "Name",
-type: "string",
-validation: { required: true } },
-        email: { name: "Email",
-type: "string" }
+        id: { name: "ID", type: "number", isId: "increment", validation: { required: true } },
+        name: { name: "Name", type: "string", validation: { required: true } },
+        email: { name: "Email", type: "string" }
     }
 } as unknown as EntityCollection;
 
@@ -30,7 +24,16 @@ describe("Utils", () => {
             expect(toPascalCase("private_notes")).toBe("PrivateNotes");
         });
         it("handles already PascalCase input", () => {
-            expect(toPascalCase("TestEntities")).toBe("Testentities");
+            expect(toPascalCase("TestEntities")).toBe("Testentities"); // Note: toPascalCase implementation lowercases follow-up chars per word split
+        });
+        it("handles kebab-case", () => {
+            expect(toPascalCase("private-notes")).toBe("PrivateNotes");
+        });
+        it("handles space separated strings", () => {
+            expect(toPascalCase("private notes")).toBe("PrivateNotes");
+        });
+        it("handles multiple delimiters and empty chunks", () => {
+            expect(toPascalCase("private--notes__here")).toBe("PrivateNotesHere");
         });
     });
 
@@ -38,51 +41,460 @@ describe("Utils", () => {
         it("converts snake_case to camelCase", () => {
             expect(toCamelCase("private_notes")).toBe("privateNotes");
         });
+        it("converts kebab-case to camelCase", () => {
+            expect(toCamelCase("private-notes")).toBe("privateNotes");
+        });
     });
 
     describe("toSafeIdentifier", () => {
         it("converts slugs to camelCase", () => {
             expect(toSafeIdentifier("private-notes")).toBe("privateNotes");
         });
+        it("strips invalid JS identifier characters and camel cases", () => {
+            expect(toSafeIdentifier("my-special-slug!")).toBe("mySpecialSlug");
+            expect(toSafeIdentifier("some@name#here")).toBe("someNameHere");
+        });
+    });
+
+    describe("indent", () => {
+        it("indents multi-line string by given space count", () => {
+            const block = "line1\nline2\nline3";
+            const expected = "  line1\n  line2\n  line3";
+            expect(indent(block, 2)).toBe(expected);
+        });
+        it("does not indent empty/whitespace lines", () => {
+            const block = "line1\n\n  \nline2";
+            const expected = "  line1\n\n  \n  line2";
+            expect(indent(block, 2)).toBe(expected);
+        });
+    });
+});
+
+describe("propertyToTypeScriptType mapping", () => {
+    it("maps basic types correctly", () => {
+        const col = {
+            slug: "types_collection",
+            properties: {
+                bool: { type: "boolean" },
+                dt: { type: "date" },
+                geo: { type: "geopoint" },
+                ref: { type: "reference" },
+                vec: { type: "vector" },
+                bin: { type: "binary" },
+                unknown: { type: "something-weird" }
+            }
+        } as unknown as EntityCollection;
+
+        const ts = generateTypedefs([col]);
+        expect(ts).toContain("bool?: boolean;");
+        expect(ts).toContain("dt?: string;");
+        expect(ts).toContain("geo?: { latitude: number; longitude: number; };");
+        expect(ts).toContain("ref?: string | number;");
+        expect(ts).toContain("vec?: number[];");
+        expect(ts).toContain("bin?: string;");
+        expect(ts).toContain("unknown?: any;");
+    });
+
+    describe("string enum mapping", () => {
+        it("maps string array enum", () => {
+            const col = {
+                slug: "posts",
+                properties: {
+                    status: {
+                        type: "string",
+                        enum: ["draft", "published"]
+                    }
+                }
+            } as unknown as EntityCollection;
+
+            const ts = generateTypedefs([col]);
+            expect(ts).toContain('status?: "draft" | "published";');
+        });
+
+        it("maps string array of objects enum", () => {
+            const col = {
+                slug: "posts",
+                properties: {
+                    status: {
+                        type: "string",
+                        enum: [
+                            { id: "draft", label: "Draft" },
+                            { id: "published", label: "Published" }
+                        ]
+                    }
+                }
+            } as unknown as EntityCollection;
+
+            const ts = generateTypedefs([col]);
+            expect(ts).toContain('status?: "draft" | "published";');
+        });
+
+        it("maps string record enum using keys", () => {
+            const col = {
+                slug: "posts",
+                properties: {
+                    status: {
+                        type: "string",
+                        enum: {
+                            draft: "Draft",
+                            published: "Published"
+                        }
+                    }
+                }
+            } as unknown as EntityCollection;
+
+            const ts = generateTypedefs([col]);
+            expect(ts).toContain('status?: "draft" | "published";');
+        });
+    });
+
+    describe("number enum mapping", () => {
+        it("maps number array enum", () => {
+            const col = {
+                slug: "posts",
+                properties: {
+                    level: {
+                        type: "number",
+                        enum: [1, 2, 3]
+                    }
+                }
+            } as unknown as EntityCollection;
+
+            const ts = generateTypedefs([col]);
+            expect(ts).toContain("level?: 1 | 2 | 3;");
+        });
+
+        it("maps number array of objects enum", () => {
+            const col = {
+                slug: "posts",
+                properties: {
+                    level: {
+                        type: "number",
+                        enum: [
+                            { id: 10, label: "Low" },
+                            { id: 20, label: "High" }
+                        ]
+                    }
+                }
+            } as unknown as EntityCollection;
+
+            const ts = generateTypedefs([col]);
+            expect(ts).toContain("level?: 10 | 20;");
+        });
+
+        it("maps number record enum using keys", () => {
+            const col = {
+                slug: "posts",
+                properties: {
+                    level: {
+                        type: "number",
+                        enum: {
+                            1: "Low",
+                            2: "High"
+                        }
+                    }
+                }
+            } as unknown as EntityCollection;
+
+            const ts = generateTypedefs([col]);
+            expect(ts).toContain("level?: 1 | 2;");
+        });
+    });
+
+    describe("map property mapping", () => {
+        it("maps nested properties recursively", () => {
+            const col = {
+                slug: "users",
+                properties: {
+                    profile: {
+                        type: "map",
+                        properties: {
+                            age: { type: "number" },
+                            tagline: { type: "string" }
+                        }
+                    }
+                }
+            } as unknown as EntityCollection;
+
+            const ts = generateTypedefs([col]);
+            expect(ts).toContain("profile?: { age: number; tagline: string; };");
+        });
+
+        it("falls back to Record<string, any> if properties is absent", () => {
+            const col = {
+                slug: "users",
+                properties: {
+                    metadata: {
+                        type: "map"
+                    }
+                }
+            } as unknown as EntityCollection;
+
+            const ts = generateTypedefs([col]);
+            expect(ts).toContain("metadata?: Record<string, any>;");
+        });
+    });
+
+    describe("array property mapping", () => {
+        it("maps typed array using the 'of' property", () => {
+            const col = {
+                slug: "articles",
+                properties: {
+                    tags: {
+                        type: "array",
+                        of: { type: "string" }
+                    }
+                }
+            } as unknown as EntityCollection;
+
+            const ts = generateTypedefs([col]);
+            expect(ts).toContain("tags?: Array<string>;");
+        });
+
+        it("falls back to Array<any> if 'of' property is absent", () => {
+            const col = {
+                slug: "articles",
+                properties: {
+                    generic: {
+                        type: "array"
+                    }
+                }
+            } as unknown as EntityCollection;
+
+            const ts = generateTypedefs([col]);
+            expect(ts).toContain("generic?: Array<any>;");
+        });
+    });
+});
+
+describe("generateTypedefs schemas configurations", () => {
+    describe("Insert type requirements", () => {
+        it("makes properties optional in Insert if validation required is false", () => {
+            const col = {
+                slug: "books",
+                properties: {
+                    title: { type: "string" }
+                }
+            } as unknown as EntityCollection;
+
+            const ts = generateTypedefs([col]);
+            expect(ts).toContain("Insert: {");
+            expect(ts).toContain("title?: string;");
+        });
+
+        it("makes properties required in Insert if validation required is true", () => {
+            const col = {
+                slug: "books",
+                properties: {
+                    title: { type: "string", validation: { required: true } }
+                }
+            } as unknown as EntityCollection;
+
+            const ts = generateTypedefs([col]);
+            expect(ts).toContain("Insert: {");
+            expect(ts).toContain("title: string;");
+        });
+
+        it("makes isId: 'increment' key optional in Insert even if validation required is true", () => {
+            const col = {
+                slug: "books",
+                properties: {
+                    id: { type: "number", isId: "increment", validation: { required: true } }
+                }
+            } as unknown as EntityCollection;
+
+            const ts = generateTypedefs([col]);
+            expect(ts).toContain("Insert: {");
+            expect(ts).toContain("id?: number;");
+        });
+
+        it("makes isId: 'uuid' key optional in Insert even if validation required is true", () => {
+            const col = {
+                slug: "books",
+                properties: {
+                    id: { type: "string", isId: "uuid", validation: { required: true } }
+                }
+            } as unknown as EntityCollection;
+
+            const ts = generateTypedefs([col]);
+            expect(ts).toContain("Insert: {");
+            expect(ts).toContain("id?: string;");
+        });
+
+        it("keeps isId: 'manual' key required in Insert if validation required is true", () => {
+            const col = {
+                slug: "books",
+                properties: {
+                    id: { type: "string", isId: "manual", validation: { required: true } }
+                }
+            } as unknown as EntityCollection;
+
+            const ts = generateTypedefs([col]);
+            expect(ts).toContain("Insert: {");
+            expect(ts).toContain("id: string;");
+        });
+
+        it("keeps isId: true key required in Insert if validation required is true", () => {
+            const col = {
+                slug: "books",
+                properties: {
+                    id: { type: "string", isId: true, validation: { required: true } }
+                }
+            } as unknown as EntityCollection;
+
+            const ts = generateTypedefs([col]);
+            expect(ts).toContain("Insert: {");
+            expect(ts).toContain("id: string;");
+        });
+    });
+
+    describe("Update type optionality", () => {
+        it("makes all direct fields optional in Update", () => {
+            const col = {
+                slug: "books",
+                properties: {
+                    id: { type: "number", isId: "increment", validation: { required: true } },
+                    title: { type: "string", validation: { required: true } }
+                }
+            } as unknown as EntityCollection;
+
+            const ts = generateTypedefs([col]);
+            expect(ts).toContain("Update: {");
+            expect(ts).toContain("id?: number;");
+            expect(ts).toContain("title?: string;");
+        });
     });
 });
 
-describe("generateTypedefs", () => {
-    it("generates a typescript interface for a collection", () => {
-        const ts = generateTypedefs([authorsCollection]);
+describe("Collection relations and FK resolutions", () => {
+    it("handles target primary key type resolution for FK columns", () => {
+        const authorsCol = {
+            slug: "authors",
+            driver: "postgres",
+            properties: {
+                id: { type: "number", isId: "increment" }
+            }
+        } as unknown as EntityCollection;
+
+        const postsCol = {
+            slug: "posts",
+            driver: "postgres",
+            properties: {
+                id: { type: "number", isId: "increment" },
+                author: {
+                    type: "relation",
+                    target: () => authorsCol,
+                    cardinality: "one",
+                    direction: "owning",
+                    localKey: "author_id"
+                }
+            }
+        } as unknown as EntityCollection;
+
+        const ts = generateTypedefs([postsCol, authorsCol]);
+
+        // Row should have authorId as number since authors PK (id) is number
+        expect(ts).toContain("posts: {");
+        expect(ts).toContain("Row: {");
+        expect(ts).toContain("authorId?: number;");
+    });
+
+    it("defaults to string | number when target primary key cannot be resolved", () => {
+        const postsCol = {
+            slug: "posts",
+            driver: "postgres",
+            properties: {
+                id: { type: "number", isId: "increment" },
+                author: {
+                    type: "relation",
+                    target: () => ({ name: "no-properties" }),
+                    cardinality: "one",
+                    direction: "owning",
+                    localKey: "author_id"
+                }
+            }
+        } as unknown as EntityCollection;
 
-        expect(ts).toContain("export interface Database {");
-        expect(ts).toContain("authors: {");
+        const ts = generateTypedefs([postsCol]);
 
-        // Row Type
+        expect(ts).toContain("posts: {");
         expect(ts).toContain("Row: {");
-        expect(ts).toContain("id: number;");
-        expect(ts).toContain("name: string;");
-        expect(ts).toContain("email?: string;");
-
-        // Insert Type
-        expect(ts).toContain("Insert: {");
-        expect(ts).toContain("id?: number;");
-        expect(ts).toContain("name: string;");
-        expect(ts).toContain("email?: string;");
-
-        // Update Type
-        expect(ts).toContain("Update: {");
-        expect(ts).toContain("id?: number;");
-        expect(ts).toContain("name?: string;");
-        expect(ts).toContain("email?: string;");
-
-        // Dictionary
-        expect(ts).toContain("export const collectionsDictionary = {");
-        expect(ts).toContain("authors: \"authors\",");
+        expect(ts).toContain("authorId?: string | number;");
+    });
+
+    it("supports relation validation constraints making FK required", () => {
+        const authorsCol = {
+            slug: "authors",
+            driver: "postgres",
+            properties: {
+                id: { type: "string", isId: "uuid" }
+            }
+        } as unknown as EntityCollection;
+
+        const postsCol = {
+            slug: "posts",
+            driver: "postgres",
+            properties: {
+                id: { type: "number", isId: "increment" },
+                author: {
+                    type: "relation",
+                    relationName: "author_rel",
+                    collectionPath: "authors"
+                }
+            },
+            relations: [
+                {
+                    relationName: "author_rel",
+                    target: () => authorsCol,
+                    cardinality: "one",
+                    direction: "owning",
+                    localKey: "author_id",
+                    validation: { required: true }
+                }
+            ]
+        } as unknown as EntityCollection;
+
+        const ts = generateTypedefs([postsCol, authorsCol]);
+
+        expect(ts).toContain("posts: {");
+        expect(ts).toContain("Row: {");
+        expect(ts).toContain("authorId: string;"); // target is string uuid, validation required is true
+    });
+
+    it("generates relation fields mapped correctly to relation type helpers", () => {
+        const tagsCol = {
+            slug: "tags",
+            driver: "postgres",
+            properties: {
+                id: { type: "number", isId: "increment" }
+            }
+        } as unknown as EntityCollection;
+
+        const postsCol = {
+            slug: "posts",
+            driver: "postgres",
+            properties: {
+                id: { type: "number", isId: "increment" },
+                tags: {
+                    type: "relation",
+                    target: () => tagsCol,
+                    cardinality: "many",
+                    direction: "owning"
+                }
+            }
+        } as unknown as EntityCollection;
+
+        const ts = generateTypedefs([postsCol, tagsCol]);
+
+        // Row should have relation helper field
+        expect(ts).toContain("tags?: Array<{ id: string | number; path: string; __type: \"relation\"; data?: any }>;");
     });
 });
 
-describe("generateSDK", () => {
-    it("returns an array of generated files including database.types.ts and README.md", () => {
-        const files = generateSDK([authorsCollection]);
-        expect(files.length).toBe(2);
+describe("generateSDK configurations", () => {
+    it("does not generate README.md if includeReadme is false", () => {
+        const files = generateSDK([authorsCollection], { includeReadme: false });
+        expect(files.length).toBe(1);
         expect(files[0].path).toBe("database.types.ts");
-        expect(files[1].path).toBe("README.md");
     });
 });