cloesce 0.0.5-unstable.1 → 0.0.5-unstable.10

package/dist/ui/backend.js

@@ -1,60 +1,124 @@
-import { Either, u8ToB64 } from "./common.js";
-import { RuntimeContainer } from "../router/router.js";
-import { WasmResource, mapSql, invokeOrmWasm } from "../router/wasm.js";
+import { MediaType } from "../ast.js";
+import { u8ToB64 } from "../common.js";
 /**
  * cloesce/backend
  */
 export { CloesceApp } from "../router/router.js";
-export { HttpResult, Either } from "./common.js";
+export { Orm } from "../router/orm.js";
 /**
- * Marks a class as a D1-backed SQL model.
+ * Base class for a Cloudflare KV model or navigation property.
  *
- * 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
+ * Consists of a `key`, `value`, and optional `metadata`.
  *
- * Each `@D1` class must define exactly one `@PrimaryKey`.
+ * @template V The type of the value stored in the KValue. Note that KV is schema-less,
+ * so this type is not enforced at runtime, but serves as the type the client expects.
  *
- * Example:
- *```ts
- *  ＠D1
- *  export class Horse {
- *    ＠PrimaryKey id: number;
- *    name: string;
- *  }
- * ```
+ * @remarks
+ * - The `key` is a string that uniquely identifies the entry in the KV store.
+ * - The `value` is of generic type `V`, allowing flexibility in the type of data stored.
+ * - `V` must be serializable to JSON.
+ * - The `metadata` can hold any additional information associated with the KV entry.
  */
-export const D1 = () => {};
-export const Service = () => {};
+export class KValue {
+    key;
+    raw;
+    metadata;
+    get value() {
+        return this.raw;
+    }
+}
 /**
- * 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 = () => {};
+ * The result of a Workers endpoint.
+ *
+ * @param ok True if `status` < 400
+ * @param status The HTTP Status of a Workers request
+ * @param headers All headers that the result is to be sent with or was received with
+ * @param data JSON data yielded from a request, undefined if the request was not `ok`.
+ * @param message An error text set if the request was not `ok`.
+ *
+ * @remarks If `status` is 204 `data` will always be undefined.
+ *
+ */
+export class HttpResult {
+    ok;
+    status;
+    headers;
+    data;
+    message;
+    mediaType;
+    constructor(ok, status, headers, data, message, mediaType) {
+        this.ok = ok;
+        this.status = status;
+        this.headers = headers;
+        this.data = data;
+        this.message = message;
+        this.mediaType = mediaType;
+    }
+    static ok(status, data, init) {
+        const headers = new Headers(init);
+        return new HttpResult(true, status, headers, data, undefined);
+    }
+    static fail(status, message, init) {
+        const headers = new Headers(init);
+        return new HttpResult(false, status, headers, undefined, message);
+    }
+    toResponse() {
+        let body;
+        switch (this.mediaType) {
+            case MediaType.Json: {
+                this.headers.set("Content-Type", "application/json");
+                body = JSON.stringify(this.data ?? {}, (_, v) => {
+                    // Convert Uint8Arrays to base64 strings
+                    if (v instanceof Uint8Array) {
+                        return u8ToB64(v);
+                    }
+                    // Convert R2Object to Client R2Object representation
+                    if (isR2Object(v)) {
+                        return {
+                            key: v.key,
+                            version: v.version,
+                            size: v.size,
+                            etag: v.etag,
+                            httpEtag: v.httpEtag,
+                            uploaded: v.uploaded.toISOString(),
+                            customMetadata: v.customMetadata,
+                        };
+                    }
+                    if (v instanceof Date) {
+                        return v.toISOString();
+                    }
+                    return v;
+                });
+                break;
+            }
+            case MediaType.Octet: {
+                this.headers.set("Content-Type", "application/octet-stream");
+                // JSON structure isn't needed; assume the first
+                // value is the stream data
+                body = Object.values(this.data ?? {})[0];
+                break;
+            }
+            case undefined: {
+                // Errors are always text.
+                this.headers.set("Content-Type", "text/plain");
+                return new Response(this.message, {
+                    status: this.status,
+                    headers: this.headers,
+                });
+            }
+        }
+        return new Response(body, {
+            status: this.status,
+            headers: this.headers,
+        });
+    }
+    setMediaType(mediaType) {
+        this.mediaType = mediaType;
+        return this;
+    }
+}
+export const Model = (_kinds = []) => () => { };
+export const Service = () => { };
 /**
  * Declares a Wrangler environment definition.
  *
@@ -76,7 +140,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.
  *
@@ -93,127 +157,42 @@ export const WranglerEnv = () => {};
  * }
  * ```
  */
-export const PrimaryKey = () => {};
+export const PrimaryKey = () => { };
+export const KeyParam = () => { };
+export const KV = (_keyFormat, _namespaceBinding) => () => { };
+export const R2 = (_keyFormat, _bucketBinding) => () => { };
 /**
  * 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 = () => {};
-/**
- * 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 = () => {};
-/**
- * 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) => () => {};
+export const DELETE = () => { };
+export function OneToMany(_selector) {
+    return () => { };
+}
+export function OneToOne(_selector) {
+    return () => { };
+}
+export const ForeignKey = (_Model) => () => { };
 /**
  * Marks a method parameter for dependency injection.
  *
@@ -231,285 +210,19 @@ export const ForeignKey = (_Model) => () => {};
  * }
  * ```
  */
-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) => () => {};
-/**
- * Exposes the ORM primitives Cloesce uses to interact with D1 databases.
- */
-export class Orm {
-  db;
-  constructor(db) {
-    this.db = db;
-  }
-  /**
-   * Creates an instance of an `Orm`
-   * @param db The database to use for ORM calls.
-   */
-  static fromD1(db) {
-    return new Orm(db);
-  }
-  /**
-   * Maps SQL records to an instantiated Model. The records must be flat
-   * (e.g., of the form "id, name, address") or derive from a Cloesce data source view
-   * (e.g., of the form "Horse.id, Horse.name, Horse.address")
-   *
-   * Assumes the data is formatted correctly, throwing an error otherwise.
-   *
-   * @param ctor The model constructor
-   * @param records D1 Result records
-   * @param includeTree Include tree to define the relationships to join.
-   */
-  static mapSql(ctor, records, includeTree = null) {
-    return mapSql(ctor, records, includeTree).unwrap();
-  }
-  /**
-   * 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.
-   *
-   * In any other case, an error string will be returned.
-   *
-   * ### Inserting a new Model
-   * ```ts
-   * const model = {name: "julio", lastname: "pumpkin"};
-   * const idRes = await orm.upsert(Person, model, null);
-   * ```
-   *
-   * ### Updating an existing model
-   * ```ts
-   * const model =  {id: 1, name: "timothy"};
-   * const idRes = await orm.upsert(Person, model, null);
-   * // (in db)=> {id: 1, name: "timothy", lastname: "pumpkin"}
-   * ```
-   *
-   * ### Upserting a model
-   * ```ts
-   * // (assume a Person already exists)
-   * const model = {
-   *  id: 1,
-   *  lastname: "burger", // updates last name
-   *  dog: {
-   *    name: "fido" // insert dog relationship
-   *  }
-   * };
-   * const idRes = await orm.upsert(Person, model, null);
-   * // (in db)=> Person: {id: 1, dogId: 1 ...}  ; Dog: {id: 1, name: "fido"}
-   * ```
-   *
-   * @param ctor A model constructor.
-   * @param newModel The new or augmented model.
-   * @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 = null) {
-    const { wasm } = RuntimeContainer.get();
-    const args = [
-      WasmResource.fromString(ctor.name, wasm),
-      WasmResource.fromString(
-        JSON.stringify(newModel, (k, v) =>
-          v instanceof Uint8Array ? u8ToB64(v) : v,
-        ),
-        wasm,
-      ),
-      WasmResource.fromString(JSON.stringify(includeTree), wasm),
-    ];
-    const upsertQueryRes = invokeOrmWasm(wasm.upsert_model, args, wasm);
-    if (upsertQueryRes.isLeft()) {
-      return upsertQueryRes;
-    }
-    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].query)) {
-        selectIndex = i;
-        break;
-      }
-    }
-    // Execute all statements in a batch.
-    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 Either.left(
-        failed?.error ?? "D1 batch failed, but no error was returned.",
-      );
-    }
-    const rootModelId = batchRes[selectIndex].results[0];
-    return Either.right(rootModelId.id);
-  }
-  /**
-   * 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, 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 res.unwrap();
-  }
-  /**
-   * 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();
-    return `${this.listQuery(ctor, { includeTree })} WHERE [${ast.models[ctor.name].primary_key.name}] = ?`;
-  }
-  /**
-   * 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, 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 mapped = Orm.mapSql(ctor, records.results, opts.includeTree ?? null);
-    return Either.right(mapped);
-  }
-  /**
-   * 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, 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.",
-      );
-    }
-    if (record.results.length === 0) {
-      return Either.right(null);
-    }
-    const mapped = Orm.mapSql(ctor, record.results, includeTree);
-    return Either.right(mapped[0]);
-  }
+export const Inject = () => { };
+/**  Hack to detect R2Object at runtime */
+function isR2Object(x) {
+    if (typeof x !== "object" || x === null)
+        return false;
+    const o = x;
+    return (typeof o.key === "string" &&
+        typeof o.version === "string" &&
+        typeof o.size === "number" &&
+        typeof o.etag === "string" &&
+        typeof o.httpEtag === "string" &&
+        typeof o.uploaded === "object" &&
+        typeof o.uploaded?.getTime === "function" &&
+        typeof o.storageClass === "string" &&
+        typeof o.writeHttpMetadata === "function");
 }

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "cloesce",
-  "version": "0.0.5-unstable.1",
+  "version": "0.0.5-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",
   "scripts": {
-    "test": "vitest",
+    "test": "vitest run",
     "format:fix": "prettier --write .",
     "format": "prettier --check .",
     "typecheck": "tsc --noEmit",
@@ -20,6 +20,7 @@
   },
   "devDependencies": {
     "@cloudflare/workers-types": "^4.20250906.0",
+    "miniflare": "^4.20251217.0",
     "oxlint": "^1.32.0",
     "prettier": "^3.6.2",
     "ts-node": "^10.9.2",
@@ -27,10 +28,6 @@
     "vitest": "^3.2.4"
   },
   "exports": {
-    "./client": {
-      "types": "./dist/ui/client.d.ts",
-      "import": "./dist/ui/client.js"
-    },
     "./backend": {
       "types": "./dist/ui/backend.d.ts",
       "import": "./dist/ui/backend.js"
@@ -43,9 +40,6 @@
     "*": {
       "backend": [
         "dist/ui/backend.d.ts"
-      ],
-      "client": [
-        "dist/ui/client.d.ts"
       ]
     }
   },
@@ -68,4 +62,4 @@
     "orm",
     "cli"
   ]
-}
+}

package/dist/ui/client.d.ts

@@ -1,7 +0,0 @@
-/**
- * cloesce/client
- */
-export type { DeepPartial, Stream } from "./common.js";
-export { HttpResult, Either, requestBody, b64ToU8 } from "./common.js";
-export { MediaType } from "../ast.js";
-//# sourceMappingURL=client.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/ui/client.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,YAAY,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACvD,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AACvE,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC"}

package/dist/ui/client.js

@@ -1,2 +0,0 @@
-export { HttpResult, Either, requestBody, b64ToU8 } from "./common.js";
-export { MediaType } from "../ast.js";