cloesce 0.0.4-unstable.3 → 0.0.4-unstable.5

package/dist/ui/backend.js

@@ -1,27 +1,287 @@
-import { left, right } from "../common.js";
+import { left, right, } from "../common.js";
 import { RuntimeContainer } from "../router/router.js";
-import { WasmResource, fromSql, invokeOrmWasm } from "../router/wasm.js";
+import { WasmResource, mapSql as mapSql, invokeOrmWasm, } from "../router/wasm.js";
 export { cloesce } from "../router/router.js";
 export { CloesceApp } from "../common.js";
-// Compiler hints
+/**
+ * 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.
+ *
+ * These are often used for DTOs or view models.
+ *
+ * Example:
+ * ```ts
+ * ＠PlainOldObject
+ * export class CatStuff {
+ *   catFacts: string[];
+ *   catNames: string[];
+ * }
+ * ```
+ */
 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 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.
+ *
+ * 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;
+ *
+ *   // 👇 Defines a data source that joins the related Dog record
+ *   ＠DataSource
+ *   static readonly default: IncludeTree<Person> = {
+ *     dog: {},
+ *   };
+ * }
+ *
+ * // 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.
+ * ```
+ */
 export const DataSource = () => { };
+/**
+ * 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 = (_) => () => { };
+/**
+ * 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 = (_) => () => { };
+/**
+ * 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 = (_) => () => { };
+/**
+ * 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 = (_) => () => { };
+/**
+ * Marks a method parameter for dependency injection.
+ *
+ * Injected parameters can receive environment bindings,
+ * middleware-provided objects, or other registered values.
+ *
+ * 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.
+ *
+ * Supported kinds:
+ * - **"SAVE"** — Performs an *upsert* (insert or update) 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.
+ *
+ * Example:
+ * ```ts
+ * ＠CRUD(["SAVE", "GET", "LIST"])
+ * ＠D1
+ * export class CrudHaver {
+ *   ＠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) => () => { };
 /**
- * ORM functions which use metadata to translate arguments to valid SQL queries.
+ * 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;
+ * ```
  */
 export class Orm {
     db;
@@ -42,10 +302,9 @@ 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);
+    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
@@ -60,7 +319,7 @@ export class Orm {
      * @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) {
+    static upsertQuery(ctor, newModel, includeTree = null) {
         const { wasm } = RuntimeContainer.get();
         const args = [
             WasmResource.fromString(ctor.name, wasm),
@@ -110,7 +369,7 @@ 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) {
+    async upsert(ctor, newModel, includeTree = null) {
         let upsertQueryRes = Orm.upsertQuery(ctor, newModel, includeTree);
         if (!upsertQueryRes.ok) {
             return upsertQueryRes;
@@ -141,17 +400,17 @@ export class Orm {
     /**
      * Returns a query of the form `SELECT * FROM [Model.DataSource]`
      */
-    static listQuery(ctor, includeTree) {
+    static listQuery(ctor, includeTree = null) {
         if (includeTree) {
             return `SELECT * FROM [${ctor.name}.${includeTree.toString()}]`;
         }
         return `SELECT * FROM [${ctor.name}]`;
     }
     /**
-     * Returns a query of the form `SELECT * FROM [Model.DataSource] WHERE [Model.PrimaryKey] = ?`.
+     * Returns a query of the form `SELECT * FROM [Model.DataSource] WHERE [PrimaryKey] = ?`.
      * Requires the id parameter to be bound (use db.prepare().bind)
      */
-    static getQuery(ctor, includeTree) {
+    static getQuery(ctor, includeTree = null) {
         const { ast } = RuntimeContainer.get();
         if (includeTree) {
             return `${this.listQuery(ctor, includeTree)} WHERE [${ast.models[ctor.name].primary_key.name}] = ?`;
@@ -162,7 +421,7 @@ export class Orm {
      * Executes a query of the form `SELECT * FROM [Model.DataSource]`, returning all results
      * as instantiated models.
      */
-    async list(ctor, includeTreeKey) {
+    async list(ctor, includeTreeKey = null) {
         const q = Orm.listQuery(ctor, includeTreeKey);
         const res = await this.db.prepare(q).run();
         if (!res.success) {
@@ -172,7 +431,7 @@ export class Orm {
         const includeTree = includeTreeKey === null
             ? null
             : ast.models[ctor.name].data_sources[includeTreeKey.toString()].tree;
-        const fromSqlRes = fromSql(ctor, res.results, includeTree);
+        const fromSqlRes = mapSql(ctor, res.results, includeTree);
         if (!fromSqlRes.ok) {
             return fromSqlRes;
         }
@@ -182,7 +441,7 @@ export class Orm {
      * Executes a query of the form `SELECT * FROM [Model.DataSource] WHERE [Model.PrimaryKey] = ?`
      * returning all results as instantiated models.
      */
-    async get(ctor, id, includeTreeKey) {
+    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) {
@@ -192,7 +451,7 @@ export class Orm {
         const includeTree = includeTreeKey === null
             ? null
             : ast.models[ctor.name].data_sources[includeTreeKey.toString()].tree;
-        const fromSqlRes = fromSql(ctor, res.results, includeTree);
+        const fromSqlRes = mapSql(ctor, res.results, includeTree);
         if (!fromSqlRes.ok) {
             return fromSqlRes;
         }

package/package.json

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