cloesce 0.0.4-unstable.1 → 0.0.4-unstable.10

package/dist/ui/backend.js

@@ -1,27 +1,264 @@
-import { left, right } from "../common.js";
+import { Either } from "../common.js";
 import { RuntimeContainer } from "../router/router.js";
-import { WasmResource, fromSql, invokeOrmWasm } from "../router/wasm.js";
-export { cloesce } from "../router/router.js";
-export { CloesceApp } from "../common.js";
-// Compiler hints
+import { WasmResource, mapSql, invokeOrmWasm } from "../router/wasm.js";
+export { CloesceApp } from "../router/router.js";
+export { HttpResult, Either } from "../common.js";
+/**
+ * Marks a class as a D1-backed SQL model.
+ *
+ * Classes annotated with `@D1` are compiled into:
+ *  - a D1 table definition (via `cloesce migrate`)
+ *  - backend API endpoints (Workers)
+ *  - a frontend client API
+ *  - Cloudflare Wrangler configurations
+ *
+ * Each `@D1` class must define exactly one `@PrimaryKey`.
+ *
+ * Example:
+ *```ts
+ *  ＠D1
+ *  export class Horse {
+ *    ＠PrimaryKey id: number;
+ *    name: string;
+ *  }
+ * ```
+ */
 export const D1 = () => { };
+/**
+ * Marks a class as a plain serializable object.
+ *
+ * `@PlainOldObject` types represent data that can be safely
+ * returned from a model method or API endpoint without being
+ * treated as a database model.
+ *
+ * Example:
+ * ```ts
+ * ＠PlainOldObject
+ * export class CatStuff {
+ *   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 = () => { };
+/**
+ * Declares a Wrangler environment definition.
+ *
+ * A `@WranglerEnv` class describes environment bindings
+ * available to your Cloudflare Worker at runtime.
+ *
+ * The environment instance is automatically injected into
+ * decorated methods using `@Inject`.
+ *
+ * Example:
+ * ```ts
+ * ＠WranglerEnv
+ * export class Env {
+ *   db: D1Database;
+ *   motd: string;
+ * }
+ *
+ * // in a method...
+ * foo(＠Inject env: WranglerEnv) {...}
+ * ```
+ */
 export const WranglerEnv = () => { };
+/**
+ * Marks a property as the SQL primary key for a model.
+ *
+ * Every `@D1` class must define exactly one primary key.
+ *
+ * Cannot be null.
+ *
+ * Example:
+ * ```ts
+ * ＠D1
+ * export class User {
+ *   ＠PrimaryKey id: number;
+ *   name: string;
+ * }
+ * ```
+ */
 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 = () => { };
+/**
+ * Exposes a class method as an HTTP POST endpoint.
+ * The method will appear in both backend and generated client APIs.
+ */
 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 = () => { };
+/**
+ * Exposes a class method as an HTTP PATCH endpoint.
+ * The method will appear in both backend and generated client APIs.
+ */
 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 = () => { };
+/**
+ * Declares a static property as a data source.
+ *
+ * Data sources describe SQL left joins related to each
+ * models navigation properties.
+ *
+ * Example:
+ * ```ts
+ * ＠D1
+ * export class Dog {
+ *   ＠PrimaryKey
+ *   id: number;
+ *
+ *   name: string;
+ * }
+ *
+ * ＠D1
+ * export class Person {
+ *   ＠PrimaryKey
+ *   id: number;
+ *
+ *   @ForeignKey(Dog)
+ *   dogId: number;
+ *
+ *   @OneToOne("dogId")
+ *   dog: Dog | undefined;
+ *
+ *   ＠DataSource
+ *   static readonly default: IncludeTree<Person> = {
+ *     dog: {}, // join Dog table when querying Person with `default` data source
+ *   };
+ * }
+ *
+ * // When queried via the ORM or client API:
+ * const orm = Orm.fromD1(env.db);
+ * const people = await orm.list(Person, Person.default);
+ *
+ * // => Person { id: 1, dogId: 2, dog: { id: 2, name: "Fido" } }[]
+ * ```
+ */
 export const DataSource = () => { };
-export const OneToMany = (_) => () => { };
-export const OneToOne = (_) => () => { };
-export const ManyToMany = (_) => () => { };
-export const ForeignKey = (_) => () => { };
+/**
+ * Declares a one-to-many relationship between models.
+ *
+ * The argument is the foreign key property name on the
+ * related model.
+ *
+ * Example:
+ * ```ts
+ * ＠OneToMany("personId")
+ * dogs: Dog[];
+ * ```
+ */
+export const OneToMany = (_foreignKeyColumn) => () => { };
+/**
+ * Declares a one-to-one relationship between models.
+ *
+ * The argument is the foreign key property name that links
+ * the two tables.
+ *
+ * Example:
+ * ```ts
+ * ＠OneToOne("dogId")
+ * dog: Dog | undefined;
+ * ```
+ */
+export const OneToOne = (_foreignKeyColumn) => () => { };
+/**
+ * Declares a many-to-many relationship between models.
+ *
+ * The argument is a unique identifier for the generated
+ * junction table used to connect the two entities.
+ *
+ * Example:
+ * ```ts
+ * ＠ManyToMany("StudentsCourses")
+ * courses: Course[];
+ * ```
+ */
+export const ManyToMany = (_uniqueId) => () => { };
+/**
+ * Declares a foreign key relationship between models.
+ * Directly translates to a SQLite foreign key.
+ *
+ * The argument must reference either a model class or the
+ * name of a model class as a string. The property type must
+ * match the target model’s primary key type.
+ *
+ * Example:
+ * ```ts
+ * ＠ForeignKey(Dog)
+ * dogId: number;
+ * ```
+ */
+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
+ * async neigh(＠Inject env: WranglerEnv) {
+ *   return `i am ${this.name}`;
+ * }
+ * ```
+ */
 export const Inject = () => { };
+/**
+ * Enables automatic CRUD method generation for a model.
+ *
+ * The argument is a list of CRUD operation kinds
+ * (e.g. `"SAVE"`, `"GET"`, `"LIST"`) to generate for the model.
+ *
+ * Cloesce will emit corresponding backend methods and frontend
+ * client bindings automatically, removing the need to manually
+ * define common API operations.
+ *
+ * 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`.
+ *
+ * The generated methods are static, exposed through both the backend
+ * and the frontend client API.
+ *
+ * Example:
+ * ```ts
+ * ＠CRUD(["SAVE", "GET", "LIST"])
+ * ＠D1
+ * export class CrudHaver {
+ *   ＠PrimaryKey id: number;
+ *   name: string;
+ * }
+ * ```
+ */
 export const CRUD = (_kinds) => () => { };
 /**
- * ORM functions which use metadata to translate arguments to valid SQL queries.
+ * Exposes the ORM primitives Cloesce uses to interact with D1 databases.
  */
 export class Orm {
     db;
@@ -42,41 +279,20 @@ export class Orm {
      * @param ctor The model constructor
      * @param records D1 Result records
      * @param includeTree Include tree to define the relationships to join.
-     * @returns
-     */
-    static fromSql(ctor, records, includeTree) {
-        return fromSql(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) {
-        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);
+    static mapSql(ctor, records, includeTree = null) {
+        return mapSql(ctor, records, includeTree);
     }
     /**
      * 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
@@ -110,92 +326,177 @@ export class Orm {
      * @param includeTree An include tree describing which foreign keys to join.
      * @returns An error string, or the primary key of the inserted model.
      */
-    async upsert(ctor, newModel, includeTree) {
-        let upsertQueryRes = Orm.upsertQuery(ctor, newModel, includeTree);
-        if (!upsertQueryRes.ok) {
+    async upsert(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),
+        ];
+        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) {
-        if (includeTree) {
-            return `SELECT * FROM [${ctor.name}.${includeTree.toString()}]`;
+    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),
+        ];
+        const res = invokeOrmWasm(wasm.list_models, args, wasm);
+        if (res.isLeft()) {
+            throw new Error(`Error invoking the Cloesce WASM Binary: ${res.value}`);
         }
-        return `SELECT * FROM [${ctor.name}]`;
+        return res.unwrap();
     }
     /**
-     * Returns a query of the form `SELECT * FROM [Model.DataSource] WHERE [Model.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) {
         const { ast } = RuntimeContainer.get();
-        if (includeTree) {
-            return `${this.listQuery(ctor, includeTree)} WHERE [${ctor.name}.${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 })} 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) {
-        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 sql = Orm.listQuery(ctor, opts);
+        const stmt = this.db.prepare(sql);
+        const records = await stmt.all();
+        if (!records.success) {
+            return Either.left(records.error ?? "D1 query failed, but no error was returned.");
         }
-        const { ast } = RuntimeContainer.get();
-        const includeTree = includeTreeKey === null
-            ? null
-            : ast.models[ctor.name].data_sources[includeTreeKey.toString()].tree;
-        const fromSqlRes = fromSql(ctor, res.results, includeTree);
-        if (!fromSqlRes.ok) {
-            return fromSqlRes;
+        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) {
-        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 sql = Orm.getQuery(ctor, includeTree);
+        const record = await this.db.prepare(sql).bind(id).run();
+        if (!record.success) {
+            return Either.left(record.error ?? "D1 query failed, but no error was returned.");
         }
-        const { ast } = RuntimeContainer.get();
-        const includeTree = includeTreeKey === null
-            ? null
-            : ast.models[ctor.name].data_sources[includeTreeKey.toString()].tree;
-        const fromSqlRes = fromSql(ctor, res.results, includeTree);
-        if (!fromSqlRes.ok) {
-            return fromSqlRes;
+        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/dist/ui/client.d.ts

@@ -1,4 +1,5 @@
-export type { HttpResult, Either, DeepPartial } from "../common.js";
+export type { DeepPartial } from "../common.js";
+export { HttpResult, Either } from "../common.js";
 export declare function instantiateObjectArray<T extends object>(data: any, ctor: {
     new (): T;
 }): T[];

package/dist/ui/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/ui/client.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,UAAU,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAGpE,wBAAgB,sBAAsB,CAAC,CAAC,SAAS,MAAM,EACrD,IAAI,EAAE,GAAG,EACT,IAAI,EAAE;IAAE,QAAQ,CAAC,CAAA;CAAE,GAClB,CAAC,EAAE,CAKL"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/ui/client.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAGlD,wBAAgB,sBAAsB,CAAC,CAAC,SAAS,MAAM,EACrD,IAAI,EAAE,GAAG,EACT,IAAI,EAAE;IAAE,QAAQ,CAAC,CAAA;CAAE,GAClB,CAAC,EAAE,CAKL"}

package/dist/ui/client.js

@@ -1,3 +1,4 @@
+export { HttpResult, Either } from "../common.js";
 // Helpers
 export function instantiateObjectArray(data, ctor) {
     if (Array.isArray(data)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cloesce",
-  "version": "0.0.4-unstable.1",
+  "version": "0.0.4-unstable.10",
   "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",