cloesce 0.0.5-unstable.4 → 0.0.5-unstable.5

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 { CloesceApp } from "../router/router.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.
  *
@@ -94,6 +158,9 @@ export const WranglerEnv = () => { };
  * ```
  */
 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.
@@ -119,100 +186,12 @@ export const PATCH = () => { };
  * 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 function OneToMany(_selector) {
+    return () => { };
+}
+export function OneToOne(_selector) {
+    return () => { };
+}
 export const ForeignKey = (_Model) => () => { };
 /**
  * Marks a method parameter for dependency injection.
@@ -232,271 +211,18 @@ 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]);
-    }
+/**  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.4",
+  "version": "0.0.5-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",
   "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"
       ]
     }
   },

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";