create-cloesce 0.0.6 → 0.3.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "create-cloesce",
   "description": "Create Cloesce App",
-  "version": "0.0.6",
+  "version": "0.3.0",
   "author": "Ben Schreiber <bpschreiber2003@gmail.com>",
   "repository": {
     "url": "https://github.com/bens-schreiber/create-cloesce-app"

package/templates/default/cloesce.config.ts

@@ -0,0 +1,9 @@
+import { CloesceConfigOptions } from "cloesce";
+
+const config: CloesceConfigOptions = {
+    srcPaths: ["./src/schema"],
+    workersUrl: "http://localhost:5000/api",
+    wranglerConfigFormat: "jsonc",
+};
+
+export default config;

package/templates/default/package.json

@@ -5,14 +5,14 @@
   "main": "index.js",
   "scripts": {
     "build": "cloesce compile && wrangler build",
-    "migrate:cloesce": "cloesce migrate",
+    "migrate:cloesce": "cloesce migrate db",
     "migrate:wrangler": "wrangler d1 migrations apply db",
     "start:dev": "wrangler dev --port 5000",
     "start:web": "vite",
     "test": "vitest"
   },
   "dependencies": {
-    "cloesce": ">=0.1.0",
+    "cloesce": ">=0.3.0",
     "wrangler": "^4.61.1"
   },
   "devDependencies": {

package/templates/default/src/api/main.ts

@@ -0,0 +1,62 @@
+// Here, we import the generated backend code, which includes all the types
+// defined in the `schema.clo` file
+import * as Cloesce from "@cloesce/backend.js";
+import { CfReadableStream } from "@cloesce/backend.js";
+
+// The "cloesce" library provides basic types and utilities for building a Cloesce backend
+import { HttpResult } from "cloesce";
+
+// All API routes defined under a model in `schema.clo` are generated under their
+// respective models namespace.
+//
+// To implement an API route, simply extend the generated Api class.
+// If not implemented, the route will return a 501 Not Implemented error by default.
+export class Weather extends Cloesce.Weather.Api {
+    async uploadPhoto(self: Cloesce.Weather.Self, e: Cloesce.Env, s: CfReadableStream): Promise<void> {
+        // All models have a `KeyFormat` namespace which provides utilities for generating
+        // KV and R2 keys for that model.
+        const key = Cloesce.Weather.KeyFormat.photo(self.id);
+        await e.bucket.put(key, s);
+    }
+
+    // Any method can return an HttpResult, which allows you to specify the 
+    // Response status code, body, and headers.
+    downloadPhoto(self: Cloesce.Weather.Self): HttpResult<CfReadableStream> {
+        if (!self.photo) {
+            return HttpResult.fail(404, "Photo not found");
+        }
+        return HttpResult.ok(200, self.photo.body);
+    }
+}
+
+export default {
+    async fetch(request: Request, env: Cloesce.Env): Promise<Response> {
+        // preflight
+        if (request.method === "OPTIONS") {
+            return HttpResult.ok(200, undefined, {
+                "Access-Control-Allow-Origin": "*",
+                "Access-Control-Allow-Methods": "GET, POST, PUT, DELETE, OPTIONS",
+                "Access-Control-Allow-Headers": "Content-Type, Authorization",
+            }).toResponse();
+        }
+
+        // Run Cloesce app
+        const app = (await Cloesce.cloesce())
+            .register(new Weather());
+
+        const result = await app.run(request, env);
+
+        // attach CORS headers
+        result.headers.set("Access-Control-Allow-Origin", "*");
+        result.headers.set(
+            "Access-Control-Allow-Methods",
+            "GET, POST, PUT, DELETE, OPTIONS"
+        );
+        result.headers.set(
+            "Access-Control-Allow-Headers",
+            "Content-Type, Authorization"
+        );
+
+        return result;
+    }
+};

package/templates/default/src/schema/schema.clo

@@ -0,0 +1,102 @@
+// `env` describes the resources in a wrangler configuration that the API can access.
+// It does not replace the wrangler config, but does result in a generated version.
+env {
+    // The `d1` block describes all D1 database bindings
+    d1 { 
+        db 
+        // db2
+    }
+
+    // The `r2` block describes all R2 bucket bindings
+    r2 { 
+        bucket 
+        // bucket2
+    }
+}
+
+// If a model is to be stored in a D1 database as a table, it must be decorated with `[use <binding>]`
+// The `list`, `get`, and `save` operations are used to generate CRUD operations for the model.
+// Optionally, these tags can be combined, e.g. `[use db, list, get, save]`
+[use db]
+[use list, save, get]
+model WeatherReport {
+    // The `primary` block describes the primary key of the table.
+    // It can be composed of several fields. Any number of primary blocks can be defined,
+    // which all together make up one primary key.
+    primary {
+        id: int
+    }
+
+    // A `nav` block describes a relationship between two models.
+    // In this case, it is a one-to-many relationship between WeatherReport and Weather,
+    // where WeatherReport has many Weathers. 
+    //
+    // This works because the field `weatherReportId` in the Weather model is a foreign key that 
+    // references the `id` field in the WeatherReport model.
+    //
+    // This will resolve to a navigation field named `weatherEntries` in the WeatherReport model, 
+    //which is an array of Weather objects.
+    nav (Weather::weatherReportId) {
+        weatherEntries
+    }
+
+    // All fields that are not apart of a block are just regular fields in the table.
+    title: string
+    description: string
+}
+
+[use db]
+[use get, list, save]
+model Weather {
+    primary {
+        id: int
+    }
+
+    // A `foreign` block describes a one to one relationship between two models.
+    // It translates directly to a foreign key constraint in the database (`weatherReportId` references `id` in WeatherReport).
+    foreign (WeatherReport::id) {
+        weatherReportId
+
+        // A `nav` block inside a `foreign` block generates a navigation field,
+        // meaning the backend and client will have a WeatherReport object named `weatherReport` nested inside the Weather model.
+        nav { weatherReport }
+    }
+    
+    r2 (bucket, "weather/photos/{id}.jpg") {
+        photo
+    }
+
+    dateTime: date
+    location: string
+    temperature: int
+    condition: string
+}
+
+// An `api` block describes what endpoints must be implemented in the backend
+// and generated in the client. Many blocks can be defined, but they all together make up one API.
+//
+// All endpoints in Cloesce are HTTP endpoints.
+api Weather {
+    // If `self` is passed as an argument, it means the endpoint requires an
+    // instantiated Weather object to be hydrated on the backend before the endpoint can be executed.
+    //
+    // In this case, `uploadPhoto` accepts the Wrangler environment (dependency injected),
+    // and a stream (the photo to be uploaded).
+    post uploadPhoto(self, e: env, s: stream) -> void
+
+    // By default, Cloesce will hydrate a `self` instance with all 1:1, KV, R2,
+    // and the near side of 1:M/M:M relationships.
+    //
+    // To avoid overfetching, a `source` tag can be used on `self`, which uses the
+    // specified data source instead. In this case, `downloadPhoto` will only hydrate the `photo` field.
+    // (NOTE: The Weather table is always queried to hydrate columns, regardless of the source.)
+    get downloadPhoto([source R2Only] self) -> stream
+}
+
+// A `source` block describes a data souce that can be used throughout
+// a Cloesce program to hydrate and list models.
+//
+// In this case, the include tree has only the `photo` field of `Weather`.
+source R2Only for Weather {
+    include { photo }
+}

package/templates/default/src/web/index.ts

@@ -1,4 +1,6 @@
-import { Weather, WeatherReport } from '@generated/client';
+// All client code is generated under `@cloesce/client.js`.
+// Be careful to not use any imports under `@cloesce/backend.js` in the client.
+import { Weather, WeatherReport } from '@cloesce/client.js';
 
 declare global {
     interface Window {
@@ -21,7 +23,10 @@ const showResult = (outputId: string, result: any) => {
 };
 
 window.listReports = async () => {
-    const result = await WeatherReport.LIST("withWeatherEntries");
+    const result = await WeatherReport.$list({
+        lastSeen_id: 0,
+        limit: 100
+    })
     showResult('list-output', result);
 };
 
@@ -34,7 +39,7 @@ window.saveReport = async () => {
         return;
     }
 
-    const result = await WeatherReport.SAVE({ title, description });
+    const result = await WeatherReport.$save({ title, description });
     showResult('save-output', result);
 };
 
@@ -46,7 +51,9 @@ window.addWeatherEntry = async () => {
         return;
     }
 
-    const getResult = await WeatherReport.GET(reportId, "withWeatherEntries");
+    const getResult = await WeatherReport.$get({
+        id: reportId
+    });
     if (!getResult.ok) {
         showResult('entry-output', getResult);
         return;
@@ -61,12 +68,12 @@ window.addWeatherEntry = async () => {
         dateTime: getValue('entry-datetime') ? new Date(getValue('entry-datetime')) : new Date()
     };
 
-    const result = await WeatherReport.SAVE({
+    const result = await WeatherReport.$save({
         id: report.id,
         title: report.title,
         description: report.description,
         weatherEntries: [...(report.weatherEntries || []), newEntry]
-    }, "withWeatherEntries");
+    });
 
     showResult('entry-output', result);
 };
@@ -90,7 +97,7 @@ window.uploadPhoto = async () => {
     const weather = new Weather();
     weather.id = id;
 
-    const result = await weather.uploadPhoto(new Uint8Array(buffer), "withPhoto");
+    const result = await weather.uploadPhoto(new Uint8Array(buffer));
     showResult('upload-output', result);
 };
 
@@ -104,7 +111,7 @@ window.downloadPhoto = async () => {
 
     const weather = new Weather();
     weather.id = id;
-    const result = await weather.downloadPhoto("withPhoto");
+    const result = await weather.downloadPhoto();
 
     if (result.ok && result.data) {
         const blob = await result.data.blob();

package/templates/default/test/weather.test.ts

@@ -1,8 +1,8 @@
 import { Miniflare } from "miniflare";
 import { describe, test, expect, beforeAll } from "vitest";
-import { Orm, CloesceApp } from "cloesce/backend";
-import { cidl, constructorRegistry } from "@generated/workers";
-import { Weather, WeatherReport } from "@data/models.cloesce";
+import * as Cloesce from "@cloesce/backend.js";
+import { Weather } from "@api/main.js"
+import { cloesce } from "@cloesce/backend.js";
 
 async function createTestEnv() {
     const mf = new Miniflare({
@@ -19,60 +19,59 @@ async function createTestEnv() {
     // Run any necessary migrations
     // TODO: Does Cloudflare have a way to do this automatically in tests?
     await db.prepare(`
-    CREATE TABLE IF NOT EXISTS "WeatherReport" (
-      "id" integer PRIMARY KEY,
-      "title" text NOT NULL,
-      "description" text NOT NULL
-    );
-    CREATE TABLE IF NOT EXISTS "Weather" (
-      "id" integer PRIMARY KEY,
-      "weatherReportId" integer NOT NULL,
-      "dateTime" text NOT NULL,
-      "location" text NOT NULL,
-      "temperature" real NOT NULL,
-      "condition" text NOT NULL,
-      FOREIGN KEY ("weatherReportId") REFERENCES "WeatherReport" ("id") ON DELETE RESTRICT ON UPDATE CASCADE
-    );
-    CREATE TABLE IF NOT EXISTS "_cloesce_tmp" ("path" text PRIMARY KEY, "id" integer NOT NULL);
+--- New Models
+CREATE TABLE IF NOT EXISTS "WeatherReport" (
+  "id" integer PRIMARY KEY,
+  "title" text NOT NULL,
+  "description" text NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS "Weather" (
+  "id" integer PRIMARY KEY,
+  "weatherReportId" integer NOT NULL,
+  "dateTime" text NOT NULL,
+  "location" text NOT NULL,
+  "temperature" integer NOT NULL,
+  "condition" text NOT NULL,
+  FOREIGN KEY ("weatherReportId") REFERENCES "WeatherReport" ("id") ON DELETE RESTRICT ON UPDATE CASCADE
+);
+
+--- Cloesce Temporary Table
+CREATE TABLE IF NOT EXISTS "_cloesce_tmp" (
+  "path" text PRIMARY KEY,
+  "primary_key" text NOT NULL
+);
   `).run();
 
-    return { env, orm: Orm.fromEnv(env) };
+    return env;
 }
 
-// Cloesce must be initialized before utilizing any ORM features.
-// It takes in the generated Cloesce Interface Definition Language (CIDL)
-// and the generated constructor registry. Both may be imported from
-// "@generated/workers" as shown above.
-beforeAll(() => CloesceApp.init(cidl as any, constructorRegistry));
+beforeAll(() => cloesce());
 
 // Here we will test our Cloesce models against a Miniflare environment.
 // This does not use any client stubs; it interacts directly with the Miniflare instance.
 describe("Miniflare Integration Tests", () => {
     test("Download a thumbnail", async () => {
         // Arrange
-        const { env, orm } = await createTestEnv();
+        const env = await createTestEnv();
         const testData = "test-data";
 
-        const report = await orm.upsert(
-            WeatherReport,
-            {
-                title: "Test Report",
-                description: "This is a test weather report.",
-                weatherEntries: [{
-                    dateTime: new Date(),
-                    location: "Test Location",
-                    temperature: 25,
-                    condition: "Sunny"
-                }]
-            },
-            WeatherReport.withWeatherEntries
-        );
+        const report = (await Cloesce.WeatherReport.save(env, {
+            title: "Test Report",
+            description: "This is a test weather report.",
+            weatherEntries: [{
+                dateTime: new Date(),
+                location: "Test Location",
+                temperature: 25,
+                condition: "Sunny"
+            }]
+        }))!;
 
-        await report!.weatherEntries[0].uploadPhoto(env, testData as any);
+        await new Weather().uploadPhoto(report.weatherEntries[0], env, testData as any);
 
         // Act
-        const weatherEntries = await orm.list(Weather, Weather.withPhoto);
-        const photo = weatherEntries[0].downloadPhoto();
+        const weatherEntries = (await Cloesce.Weather.DataSources.Default.list(env, 0, 100))!;
+        const photo = new Weather().downloadPhoto(weatherEntries[0]);
 
         // Assert
         expect(photo.ok).toBe(true);

package/templates/default/tsconfig.json

@@ -1,9 +1,9 @@
 {
   // Visit https://aka.ms/tsconfig to read more about this file
   "compilerOptions": {
-    "module": "ESNext",
+    "module": "node20",
     "target": "ES2020",
-    "moduleResolution": "node",
+    "moduleResolution": "node16",
     "types": [],
     "skipLibCheck": true,
 
@@ -15,10 +15,10 @@
     "emitDecoratorMetadata": true,
     "allowSyntheticDefaultImports": true,
     "paths": {
-      "@data/*": ["./src/data/*"],
-      "@generated/*": ["./.generated/*"],
+      "@api/*": ["./src/api/*"],
+      "@cloesce/*": ["./.cloesce/*"],
     },
     "outDir": "dist",
   },
-  "include": [".generated/*.ts", "src/**/*.ts", "test/**/*.ts"],
+  "include": [".cloesce/*.ts", "src/**/*.ts", "test/**/*.ts"],
 }

package/templates/default/wrangler.jsonc

@@ -0,0 +1,3 @@
+{
+    "main": "src/api/main.ts"
+}

package/templates/default/cloesce.config.json

@@ -1,7 +0,0 @@
-{
-    "paths": [
-        "./src/data"
-    ],
-    "workersUrl": "http://localhost:5000/api",
-    "migrationsPath": "./migrations"
-}

package/templates/default/src/data/main.cloesce.ts

@@ -1,46 +0,0 @@
-import { WranglerEnv, CloesceApp, HttpResult } from "cloesce/backend";
-import { D1Database, R2Bucket, ExecutionContext } from "@cloudflare/workers-types";
-
-/**
- * Compiles to the Wrangler configuration file, defining bindings
- * for the Cloudflare Worker environment.
- */
-@WranglerEnv
-export class Env {
-    db: D1Database;
-    bucket: R2Bucket;
-    myVariable: string;
-}
-
-// Basic main entry point for a Cloesce App.
-// Does not need to be defined if no customizations are required.
-export default async function main(
-    request: Request,
-    env: Env,
-    app: CloesceApp,
-    _ctx: ExecutionContext): Promise<Response> {
-    // preflight
-    if (request.method === "OPTIONS") {
-        return HttpResult.ok(200, undefined, {
-            "Access-Control-Allow-Origin": "*",
-            "Access-Control-Allow-Methods": "GET, POST, PUT, DELETE, OPTIONS",
-            "Access-Control-Allow-Headers": "Content-Type, Authorization",
-        }).toResponse();
-    }
-
-    // Run Cloesce app
-    const result = await app.run(request, env);
-
-    // attach CORS headers
-    result.headers.set("Access-Control-Allow-Origin", "*");
-    result.headers.set(
-        "Access-Control-Allow-Methods",
-        "GET, POST, PUT, DELETE, OPTIONS"
-    );
-    result.headers.set(
-        "Access-Control-Allow-Headers",
-        "Content-Type, Authorization"
-    );
-
-    return result;
-}

package/templates/default/src/data/models.cloesce.ts

@@ -1,65 +0,0 @@
-import { GET, POST, HttpResult, IncludeTree, Integer, Model, R2, Inject } from "cloesce/backend";
-import { R2ObjectBody, ReadableStream } from "@cloudflare/workers-types";
-import { Env } from "./main.cloesce";
-
-@Model()
-export class Weather {
-    // Cloesce interprets this is a primary key.
-    // Optionally, decorate with @PrimaryKey
-    id: Integer;
-
-    // Foreign key to WeatherReport
-    // Optionally, decorate with @ForeignKey
-    weatherReportId: Integer;
-
-    // Navigation property to weatherReportId
-    // Optionally, decorate with @OneToOne<Weather>(w => w.weatherReportId)
-    weatherReport: WeatherReport | undefined;
-
-    dateTime: Date;
-    location: string;
-    temperature: number;
-    condition: string;
-
-    @R2("weather/photo/{id}", "bucket")
-    photo: R2ObjectBody | undefined;
-
-    // Hydrates the photo when the client calls "withPhoto"
-    static readonly withPhoto: IncludeTree<Weather> = {
-        photo: {}
-    }
-
-    @POST
-    async uploadPhoto(@Inject env: Env, stream: ReadableStream): Promise<HttpResult<void>> {
-        await env.bucket.put(`weather/photo/${this.id}`, stream);
-        return HttpResult.ok(200);
-    }
-
-    @GET
-    downloadPhoto(): HttpResult<ReadableStream> {
-        if (!this.photo) {
-            return HttpResult.fail(404, "Photo not found");
-        }
-        return HttpResult.ok(200, this.photo.body);
-    }
-}
-
-@Model(["GET", "LIST", "SAVE"])
-export class WeatherReport {
-    // Cloesce assumes this is a primary key.
-    // Optionally, decorate with @PrimaryKey
-    id: Integer;
-
-    title: string;
-    description: string;
-
-    // Cloesce assumes this is a foreign key to Weather.weatherReportId
-    // Optionally, or if multiple FKs exist, decorate with
-    // @OneToMany<Weather>(w => w.weatherReportId)
-    weatherEntries: Weather[];
-
-    // Hydrates the weatherEntries when the client calls "withWeatherEntries"
-    static readonly withWeatherEntries: IncludeTree<WeatherReport> = {
-        weatherEntries: {}
-    }
-}

package/templates/default/wrangler.toml

@@ -1 +0,0 @@
-main = ".generated/workers.ts"