cloesce 0.0.4-unstable.5 → 0.0.4-unstable.7

package/dist/ui/backend.js

@@ -1,4 +1,4 @@
-import { left, right, } from "../common.js";
+import { Either } from "../common.js";
 import { RuntimeContainer } from "../router/router.js";
 import { WasmResource, mapSql as mapSql, invokeOrmWasm, } from "../router/wasm.js";
 export { cloesce } from "../router/router.js";
@@ -23,7 +23,7 @@ export { CloesceApp } from "../common.js";
  *  }
  * ```
  */
-export const D1 = () => { };
+export const D1 = (_) => { };
 /**
  * Marks a class as a plain serializable object.
  *
@@ -31,8 +31,6 @@ export const D1 = () => { };
  * returned from a model method or API endpoint without being
  * treated as a database model.
  *
- * These are often used for DTOs or view models.
- *
  * Example:
  * ```ts
  * ＠PlainOldObject
@@ -40,9 +38,19 @@ export const D1 = () => { };
  *   catFacts: string[];
  *   catNames: string[];
  * }
+ *
+ * // in a method...
+ * foo(): CatStuff {
+ *   return {
+ *    catFacts: ["cats sleep 16 hours a day"],
+ *   catNames: ["Whiskers", "Fluffy"]
+ *  };
+ *
+ * // which generates an API like:
+ * async function foo(): Promise<HttpResult<CatStuff>> { ... }
  * ```
  */
-export const PlainOldObject = () => { };
+export const PlainOldObject = (_) => { };
 /**
  * Declares a Wrangler environment definition.
  *
@@ -64,7 +72,7 @@ export const PlainOldObject = () => { };
  * foo(＠Inject env: WranglerEnv) {...}
  * ```
  */
-export const WranglerEnv = () => { };
+export const WranglerEnv = (_) => { };
 /**
  * Marks a property as the SQL primary key for a model.
  *
@@ -81,40 +89,37 @@ export const WranglerEnv = () => { };
  * }
  * ```
  */
-export const PrimaryKey = () => { };
+export const PrimaryKey = (_) => { };
 /**
  * Exposes a class method as an HTTP GET endpoint.
  * The method will appear in both backend and generated client APIs.
  */
-export const GET = () => { };
+export const GET = (_) => { };
 /**
  * Exposes a class method as an HTTP POST endpoint.
  * The method will appear in both backend and generated client APIs.
  */
-export const POST = () => { };
+export const POST = (_) => { };
 /**
  * Exposes a class method as an HTTP PUT endpoint.
  * The method will appear in both backend and generated client APIs.
  */
-export const PUT = () => { };
+export const PUT = (_) => { };
 /**
  * Exposes a class method as an HTTP PATCH endpoint.
  * The method will appear in both backend and generated client APIs.
  */
-export const PATCH = () => { };
+export const PATCH = (_) => { };
 /**
  * Exposes a class method as an HTTP DEL endpoint.
  * The method will appear in both backend and generated client APIs.
  */
-export const DELETE = () => { };
+export const DELETE = (_) => { };
 /**
  * Declares a static property as a data source.
  *
- * Data sources describe SQL view definitions (joins) for
- * model relationships. They define which related models
- * are automatically included when querying. Data sources
- * can only reference navigation properties, not scalar
- * attributes.
+ * Data sources describe SQL left joins related to each
+ * models navigation properties.
  *
  * Example:
  * ```ts
@@ -137,30 +142,20 @@ export const DELETE = () => { };
  *   @OneToOne("dogId")
  *   dog: Dog | undefined;
  *
- *   // 👇 Defines a data source that joins the related Dog record
  *   ＠DataSource
  *   static readonly default: IncludeTree<Person> = {
- *     dog: {},
+ *     dog: {}, // join Dog table when querying Person with `default` data source
  *   };
  * }
  *
- * // The above will generate an SQL view similar to:
- * // CREATE VIEW "Person.default" AS
- * // SELECT
- * //   "Person"."id" AS "id",
- * //   "Person"."dogId" AS "dogId",
- * //   "Dog"."id" AS "dog.id",
- * //   "Dog"."name" AS "dog.name"
- * // FROM "Person"
- * // LEFT JOIN "Dog" ON "Person"."dogId" = "Dog"."id";
- *
  * // When queried via the ORM or client API:
  * const orm = Orm.fromD1(env.db);
- * const people = (await orm.list(Person, "default")).value;
- * // Each Person instance will now include a populated .dog property.
+ * const people = await orm.list(Person, Person.default);
+ *
+ * // => Person { id: 1, dogId: 2, dog: { id: 2, name: "Fido" } }[]
  * ```
  */
-export const DataSource = () => { };
+export const DataSource = (_) => { };
 /**
  * Declares a one-to-many relationship between models.
  *
@@ -173,7 +168,7 @@ export const DataSource = () => { };
  * dogs: Dog[];
  * ```
  */
-export const OneToMany = (_) => () => { };
+export const OneToMany = (_foreignKeyColumn) => () => { };
 /**
  * Declares a one-to-one relationship between models.
  *
@@ -186,7 +181,7 @@ export const OneToMany = (_) => () => { };
  * dog: Dog | undefined;
  * ```
  */
-export const OneToOne = (_) => () => { };
+export const OneToOne = (_foreignKeyColumn) => () => { };
 /**
  * Declares a many-to-many relationship between models.
  *
@@ -199,7 +194,7 @@ export const OneToOne = (_) => () => { };
  * courses: Course[];
  * ```
  */
-export const ManyToMany = (_) => () => { };
+export const ManyToMany = (_uniqueId) => () => { };
 /**
  * Declares a foreign key relationship between models.
  * Directly translates to a SQLite foreign key.
@@ -214,13 +209,16 @@ export const ManyToMany = (_) => () => { };
  * dogId: number;
  * ```
  */
-export const ForeignKey = (_) => () => { };
+export const ForeignKey = (_model) => () => { };
 /**
  * Marks a method parameter for dependency injection.
  *
  * Injected parameters can receive environment bindings,
  * middleware-provided objects, or other registered values.
  *
+ * Note that injected parameters will not appear in the client
+ * API.
+ *
  * Example:
  * ```ts
  * ＠POST
@@ -240,14 +238,13 @@ export const Inject = () => { };
  * client bindings automatically, removing the need to manually
  * define common API operations.
  *
- * Supported kinds:
- * - **"SAVE"** — Performs an *upsert* (insert or update) for a model instance.
+ * CRUD Operations:
+ * - **"SAVE"** — Performs an *upsert* (insert, update, or both) for a model instance.
  * - **"GET"** — Retrieves a single record by its primary key, optionally using a `DataSource`.
  * - **"LIST"** — Retrieves all records for the model, using the specified `DataSource`.
- * - **(future)** `"DELETE"` — Will remove a record by primary key once implemented.
  *
  * The generated methods are static, exposed through both the backend
- * (Worker endpoints) and the frontend client API.
+ * and the frontend client API.
  *
  * Example:
  * ```ts
@@ -257,31 +254,11 @@ export const Inject = () => { };
  *   ＠PrimaryKey id: number;
  *   name: string;
  * }
- *
- * // Generated methods (conceptually):
- * // static async save(item: CrudHaver): Promise<HttpResult<CrudHaver>>
- * // static async get(id: number, dataSource?: string): Promise<HttpResult<CrudHaver>>
- * // static async list(dataSource?: string): Promise<HttpResult<CrudHaver[]>>
  * ```
  */
 export const CRUD = (_kinds) => () => { };
 /**
- * Provides helper methods for performing ORM operations against a D1 database.
- *
- * The `Orm` class uses the Cloesce metadata system to generate, execute,
- * and map SQL queries for model classes decorated with `＠D1`.
- *
- * Typical operations include:
- * - `fromD1(db)` — create an ORM instance bound to a `D1Database`
- * - `upsert()` — insert or update a model
- * - `list()` — fetch all instances of a model
- * - `get()` — fetch one instance by primary key
- *
- * Example:
- * ```ts
- * const orm = Orm.fromD1(env.db);
- * const horses = (await orm.list(Horse, "default")).value;
- * ```
+ * Exposes the ORM primitives Cloesce uses to interact with D1 databases.
  */
 export class Orm {
     db;
@@ -306,36 +283,16 @@ export class Orm {
     static mapSql(ctor, records, includeTree = null) {
         return mapSql(ctor, records, includeTree);
     }
-    /**
-     * Returns a SQL query to insert a model into the database. Uses an IncludeTree as a guide for
-     * foreign key relationships, only inserting the explicitly stated pattern in the tree.
-     *
-     * TODO: We should be able to leave primary keys and foreign keys undefined, with
-     * primary keys being auto incremented and foreign keys being assumed by navigation property
-     * context.
-     *
-     * @param ctor A model constructor.
-     * @param newModel The new model to insert.
-     * @param includeTree An include tree describing which foreign keys to join.
-     * @returns Either an error string, or the insert query string.
-     */
-    static upsertQuery(ctor, newModel, includeTree = null) {
-        const { wasm } = RuntimeContainer.get();
-        const args = [
-            WasmResource.fromString(ctor.name, wasm),
-            WasmResource.fromString(JSON.stringify(newModel), wasm),
-            WasmResource.fromString(JSON.stringify(includeTree), wasm),
-        ];
-        return invokeOrmWasm(wasm.upsert_model, args, wasm);
-    }
     /**
      * Executes an "upsert" query, adding or augmenting a model in the database.
+     *
      * If a model's primary key is not defined in `newModel`, the query is assumed to be an insert.
+     *
      * If a model's primary key _is_ defined, but some attributes are missing, the query is assumed to be an update.
+     *
      * Finally, if the primary key is defined, but all attributes are included, a SQLite upsert will be performed.
      *
-     * Capable of inferring foreign keys from the surrounding context of the model. A missing primary key is allowed
-     * only if the primary key is an integer, in which case it will be auto incremented and assigned.
+     * In any other case, an error string will be returned.
      *
      * ### Inserting a new Model
      * ```ts
@@ -370,91 +327,180 @@ export class Orm {
      * @returns An error string, or the primary key of the inserted model.
      */
     async upsert(ctor, newModel, includeTree = null) {
-        let upsertQueryRes = Orm.upsertQuery(ctor, newModel, includeTree);
-        if (!upsertQueryRes.ok) {
+        const { wasm } = RuntimeContainer.get();
+        const args = [
+            WasmResource.fromString(ctor.name, wasm),
+            WasmResource.fromString(JSON.stringify(newModel), wasm),
+            WasmResource.fromString(JSON.stringify(includeTree), wasm),
+        ];
+        const upsertQueryRes = invokeOrmWasm(wasm.upsert_model, args, wasm);
+        if (upsertQueryRes.isLeft()) {
             return upsertQueryRes;
         }
-        // Split the query into individual statements.
-        const statements = upsertQueryRes.value
-            .split(";")
-            .map((s) => s.trim())
-            .filter((s) => s.length > 0);
+        const statements = JSON.parse(upsertQueryRes.unwrap());
         // One of these statements is a "SELECT", which is the root model id stmt.
         let selectIndex;
         for (let i = statements.length - 1; i >= 0; i--) {
-            if (/^SELECT/i.test(statements[i])) {
+            if (/^SELECT/i.test(statements[i].query)) {
                 selectIndex = i;
                 break;
             }
         }
         // Execute all statements in a batch.
-        const batchRes = await this.db.batch(statements.map((s) => this.db.prepare(s)));
+        const batchRes = await this.db.batch(statements.map((s) => this.db.prepare(s.query).bind(...s.values)));
         if (!batchRes.every((r) => r.success)) {
             const failed = batchRes.find((r) => !r.success);
-            return left(failed?.error ?? "D1 batch failed, but no error was returned.");
+            return Either.left(failed?.error ?? "D1 batch failed, but no error was returned.");
         }
         // Return the result of the SELECT statement
         const selectResult = batchRes[selectIndex].results[0];
-        return right(selectResult.id);
+        return Either.right(selectResult.id);
     }
     /**
-     * Returns a query of the form `SELECT * FROM [Model.DataSource]`
+     * Returns a select query, creating a CTE view for the model using the provided include tree.
+     *
+     * @param ctor The model constructor.
+     * @param includeTree An include tree describing which related models to join.
+     * @param from An optional custom `FROM` clause to use instead of the base table.
+     * @param tagCte An optional CTE name to tag the query with. Defaults to "Model.view".
+     *
+     * ### Example:
+     * ```ts
+     * // Using a data source
+     * const query = Orm.listQuery(Person, "default");
+     *
+     * // Using a custom from statement
+     * const query = Orm.listQuery(Person, null, "SELECT * FROM Person WHERE age > 18");
+     * ```
+     *
+     * ### Example SQL output:
+     * ```sql
+     * WITH Person_view AS (
+     * SELECT
+     * "Person"."id" AS "id",
+     * ...
+     * FROM "Person"
+     * LEFT JOIN ...
+     * )
+     * SELECT * FROM Person_view
+     * ```
      */
-    static listQuery(ctor, includeTree = null) {
-        if (includeTree) {
-            return `SELECT * FROM [${ctor.name}.${includeTree.toString()}]`;
-        }
-        return `SELECT * FROM [${ctor.name}]`;
+    static listQuery(ctor, opts) {
+        const { wasm } = RuntimeContainer.get();
+        const args = [
+            WasmResource.fromString(ctor.name, wasm),
+            WasmResource.fromString(JSON.stringify(opts.includeTree ?? null), wasm),
+            WasmResource.fromString(JSON.stringify(opts.tagCte ?? null), wasm),
+            WasmResource.fromString(JSON.stringify(opts.from ?? null), wasm),
+        ];
+        return invokeOrmWasm(wasm.list_models, args, wasm);
     }
     /**
-     * Returns a query of the form `SELECT * FROM [Model.DataSource] WHERE [PrimaryKey] = ?`.
-     * Requires the id parameter to be bound (use db.prepare().bind)
+     * Returns a select query for a single model by primary key, creating a CTE view using the provided include tree.
+     *
+     * @param ctor The model constructor.
+     * @param includeTree An include tree describing which related models to join.
+     *
+     * ### Example:
+     * ```ts
+     * // Using a data source
+     * const query = Orm.getQuery(Person, "default");
+     * ```
+     *
+     * ### Example SQL output:
+     *
+     * ```sql
+     * WITH Person_view AS (
+     * SELECT
+     * "Person"."id" AS "id",
+     * ...
+     * FROM "Person"
+     * LEFT JOIN ...
+     * )
+     * SELECT * FROM Person_view WHERE [Person].[id] = ?
+     * ```
      */
-    static getQuery(ctor, includeTree = null) {
+    static getQuery(ctor, includeTree) {
         const { ast } = RuntimeContainer.get();
-        if (includeTree) {
-            return `${this.listQuery(ctor, includeTree)} WHERE [${ast.models[ctor.name].primary_key.name}] = ?`;
-        }
-        return `${this.listQuery(ctor, includeTree)} WHERE [${ast.models[ctor.name].primary_key.name}] = ?`;
+        return this.listQuery(ctor, {
+            includeTree,
+        }).map((inner) => `${inner} WHERE [${ast.models[ctor.name].primary_key.name}] = ?`);
     }
     /**
-     * Executes a query of the form `SELECT * FROM [Model.DataSource]`, returning all results
-     * as instantiated models.
+     * Retrieves all instances of a model from the database.
+     * @param ctor The model constructor.
+     * @param includeTree An include tree describing which related models to join.
+     * @param from An optional custom `FROM` clause to use instead of the base table.
+     * @returns Either an error string, or an array of model instances.
+     *
+     * ### Example:
+     * ```ts
+     * const orm = Orm.fromD1(env.db);
+     * const horses = await orm.list(Horse, Horse.default);
+     * ```
+     *
+     * ### Example with custom from:
+     * ```ts
+     * const orm = Orm.fromD1(env.db);
+     * const adultHorses = await orm.list(Horse, Horse.default, "SELECT * FROM Horse ORDER BY age DESC LIMIT 10");
+     * ```
+     *
+     * =>
+     *
+     * ```sql
+     * SELECT
+     *  "Horse"."id" AS "id",
+     * ...
+     * FROM (SELECT * FROM Horse ORDER BY age DESC LIMIT 10)
+     * LEFT JOIN ...
+     * ```
+     *
      */
-    async list(ctor, includeTreeKey = null) {
-        const q = Orm.listQuery(ctor, includeTreeKey);
-        const res = await this.db.prepare(q).run();
-        if (!res.success) {
-            return left(res.error ?? "D1 failed but no error was returned.");
+    async list(ctor, opts) {
+        const queryRes = Orm.listQuery(ctor, opts);
+        if (queryRes.isLeft()) {
+            return Either.left(queryRes.value);
         }
-        const { ast } = RuntimeContainer.get();
-        const includeTree = includeTreeKey === null
-            ? null
-            : ast.models[ctor.name].data_sources[includeTreeKey.toString()].tree;
-        const fromSqlRes = mapSql(ctor, res.results, includeTree);
-        if (!fromSqlRes.ok) {
-            return fromSqlRes;
+        const stmt = this.db.prepare(queryRes.value);
+        const records = await stmt.all();
+        if (!records.success) {
+            return Either.left(records.error ?? "D1 query failed, but no error was returned.");
+        }
+        const mapRes = Orm.mapSql(ctor, records.results, opts.includeTree ?? null);
+        if (mapRes.isLeft()) {
+            return Either.left(mapRes.value);
         }
-        return right(fromSqlRes.value);
+        return Either.right(mapRes.value);
     }
     /**
-     * Executes a query of the form `SELECT * FROM [Model.DataSource] WHERE [Model.PrimaryKey] = ?`
-     * returning all results as instantiated models.
+     * Retrieves a single model by primary key.
+     * @param ctor The model constructor.
+     * @param id The primary key value.
+     * @param includeTree An include tree describing which related models to join.
+     * @returns Either an error string, or the model instance (null if not found).
+     *
+     * ### Example:
+     * ```ts
+     * const orm = Orm.fromD1(env.db);
+     * const horse = await orm.get(Horse, 1, Horse.default);
+     * ```
      */
-    async get(ctor, id, includeTreeKey = null) {
-        const q = Orm.getQuery(ctor, includeTreeKey);
-        const res = await this.db.prepare(q).bind(id).run();
-        if (!res.success) {
-            return left(res.error ?? "D1 failed but no error was returned.");
+    async get(ctor, id, includeTree) {
+        const queryRes = Orm.getQuery(ctor, includeTree);
+        if (queryRes.isLeft()) {
+            return Either.left(queryRes.value);
         }
-        const { ast } = RuntimeContainer.get();
-        const includeTree = includeTreeKey === null
-            ? null
-            : ast.models[ctor.name].data_sources[includeTreeKey.toString()].tree;
-        const fromSqlRes = mapSql(ctor, res.results, includeTree);
-        if (!fromSqlRes.ok) {
-            return fromSqlRes;
+        const record = await this.db.prepare(queryRes.value).bind(id).run();
+        if (!record.success) {
+            return Either.left(record.error ?? "D1 query failed, but no error was returned.");
+        }
+        if (record.results.length === 0) {
+            return Either.right(null);
+        }
+        const mapRes = Orm.mapSql(ctor, record.results, includeTree);
+        if (mapRes.isLeft()) {
+            return Either.left(mapRes.value);
         }
-        return right(fromSqlRes.value[0]);
+        return Either.right(mapRes.value[0]);
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cloesce",
-  "version": "0.0.4-unstable.5",
+  "version": "0.0.4-unstable.7",
   "description": "A tool to extract and compile TypeScript code into something wrangler can consume and deploy for D1 Databases and Cloudflare Workers",
   "type": "module",
   "license": "Apache-2.0",