@fragno-dev/create 0.0.4 → 0.1.1

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fragno-dev/create",
   "description": "A library for creating Fragno fragments",
-  "version": "0.0.4",
+  "version": "0.1.1",
   "exports": {
     ".": {
       "bun": "./src/index.ts",

package/src/index.ts

@@ -2,7 +2,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { copy, merge } from "./utils.ts";
-import { buildToolPkg } from "./package-json.ts";
+import { basePkg, buildToolPkg, databasePkg } from "./package-json.ts";
 import { z } from "zod";
 
 const templateTypesSchema = z.literal("fragment");
@@ -28,16 +28,22 @@ export const createOptionsSchema = z.object({
   name: z.string(),
   template: templateTypesSchema,
   agentDocs: agentDocsSchema,
+  withDatabase: z.boolean(),
 });
 
 type CreateOptions = z.infer<typeof createOptionsSchema>;
 
 export function create(options: CreateOptions) {
-  let pkgOverride: Record<string, unknown> = { name: options.name };
+  let pkgOverride: Record<string, unknown> = merge(basePkg, { name: options.name });
 
   // Build tool pkg overrides
   pkgOverride = merge(pkgOverride, buildToolPkg[options.buildTool]);
 
+  // Database pkg overrides
+  if (options.withDatabase) {
+    pkgOverride = merge(pkgOverride, databasePkg);
+  }
+
   if (options.template == "fragment") {
     writeFragmentTemplate(options.path, pkgOverride);
   } else {
@@ -77,6 +83,11 @@ export function create(options: CreateOptions) {
     case "none":
       break;
   }
+
+  if (options.withDatabase) {
+    writeOptionalTemplate(options.path, "database/index.ts", "src/index.ts");
+    writeOptionalTemplate(options.path, "database/schema.ts", "src/schema.ts");
+  }
 }
 
 function getTemplateDir(): string {

package/src/integration.test.ts

@@ -19,9 +19,10 @@ async function createTempDir(name: string): Promise<string> {
   return dir;
 }
 
-describe.concurrent.each(["tsdown", "esbuild", "vite", "rollup", "webpack", "rspack"] as const)(
-  "fragment with %s",
-  (buildTool) => {
+type BuildTool = "tsdown" | "esbuild" | "vite" | "rollup" | "webpack" | "rspack";
+
+function createFragmentTestSuite(buildTool: BuildTool, withDatabase: boolean) {
+  return () => {
     let tempDir: string;
     const testConfig = {
       name: "@myorg/test",
@@ -31,16 +32,17 @@ describe.concurrent.each(["tsdown", "esbuild", "vite", "rollup", "webpack", "rsp
     };
 
     beforeAll(async () => {
-      tempDir = await createTempDir(`fragment-test-${buildTool}`);
+      const suffix = withDatabase ? "db" : "no-db";
+      tempDir = await createTempDir(`fragment-test-${buildTool}-${suffix}`);
       console.log("temp", tempDir);
-      create({ ...testConfig, path: tempDir });
+      create({ ...testConfig, path: tempDir, withDatabase });
     });
 
     afterAll(async () => {
       await fs.rm(tempDir, { recursive: true });
     });
 
-    describe.sequential("", () => {
+    describe.sequential(buildTool, () => {
       test("package.json correctly templated", async () => {
         const pkg = path.join(tempDir, "package.json");
         const pkgContent = await fs.readFile(pkg, "utf8");
@@ -74,7 +76,7 @@ describe.concurrent.each(["tsdown", "esbuild", "vite", "rollup", "webpack", "rsp
         but somehow when running through vitest the module resolution mechanism changes causing
         the build to fail.
       */
-      test.skipIf(buildTool == "rollup")("builds", { timeout: 40000 }, async () => {
+      test.skipIf(buildTool === "rollup")("builds", { timeout: 50000 }, async () => {
         const result = await execAsync("bun run build", {
           cwd: tempDir,
           encoding: "utf8",
@@ -99,5 +101,12 @@ describe.concurrent.each(["tsdown", "esbuild", "vite", "rollup", "webpack", "rsp
         }
       });
     });
-  },
+  };
+}
+
+describe.concurrent.each(["tsdown", "esbuild", "vite", "rollup", "webpack", "rspack"] as const)(
+  "fragment with %s (with database)",
+  (buildTool) => createFragmentTestSuite(buildTool, true)(),
 );
+
+describe("fragment with tsdown (without database)", createFragmentTestSuite("tsdown", false));

package/src/package-json.ts

@@ -1,6 +1,33 @@
 import type { BuildTools } from "./index";
 
-const unpluginFragnoVersion = "^0.0.1";
+const fragnoCoreVersion = "^0.1.2";
+const fragnoDbVersion = "^0.1.2";
+const unpluginFragnoVersion = "^0.0.2";
+const fragnoCliVersion = "^0.1.3";
+
+export const basePkg: Record<string, unknown> = {
+  dependencies: {
+    "@fragno-dev/core": fragnoCoreVersion,
+    zod: "^4.0.5",
+  },
+  devDependencies: {
+    "@fragno-dev/cli": fragnoCliVersion,
+    "@types/node": "^22",
+  },
+  peerDependencies: {
+    typescript: "^5",
+    react: ">=18.0.0",
+    svelte: ">=4.0.0",
+    "solid-js": ">=1.0.0",
+    vue: ">=3.0.0",
+  },
+};
+
+export const databasePkg: Record<string, unknown> = {
+  dependencies: {
+    "@fragno-dev/db": fragnoDbVersion,
+  },
+};
 
 export const buildToolPkg: Record<BuildTools, Record<string, unknown>> = {
   none: {},

package/src/utils.ts

@@ -5,7 +5,9 @@ export function mkdirp(dir: string): void {
   try {
     fs.mkdirSync(dir, { recursive: true });
   } catch (e: unknown) {
-    if (e instanceof Error && "code" in e && e.code === "EEXIST") return;
+    if (e instanceof Error && "code" in e && e.code === "EEXIST") {
+      return;
+    }
     throw e;
   }
 }
@@ -54,7 +56,9 @@ export function copy(
   to: string,
   rename: (basename: string) => string = identity,
 ): void {
-  if (!fs.existsSync(from)) return;
+  if (!fs.existsSync(from)) {
+    return;
+  }
 
   const stats = fs.statSync(from);
 

package/templates/fragment/package.template.json

@@ -56,19 +56,5 @@
     "types:check": "tsc --noEmit"
   },
   "type": "module",
-  "dependencies": {
-    "@fragno-dev/core": "^0.0.7",
-    "zod": "^4.0.5"
-  },
-  "devDependencies": {
-    "@types/node": "^20"
-  },
-  "private": true,
-  "peerDependencies": {
-    "typescript": "^5",
-    "react": ">=18.0.0",
-    "svelte": ">=4.0.0",
-    "solid-js": ">=1.0.0",
-    "vue": ">=3.0.0"
-  }
+  "private": true
 }

package/templates/fragment/src/index.ts

@@ -56,12 +56,12 @@ const exampleRoutesFactory = defineRoutes<ExampleConfig, ExampleDeps, ExampleSer
 );
 
 const exampleFragmentDefinition = defineFragment<ExampleConfig>("example-fragment")
-  .withDependencies((config: ExampleConfig) => {
+  .withDependencies(({ config }) => {
     return {
       serverSideData: { value: config.initialData ?? "Hello World! This is a server-side data." },
     };
   })
-  .withServices((_cfg, deps) => {
+  .withServices(({ deps }) => {
     return {
       getData: () => deps.serverSideData.value,
     };

package/templates/optional/agent/AGENTS.md

@@ -14,7 +14,9 @@ provide:
 - Built-in state management with reactive stores (TanStack Query-style:
   `const {data, loading, error} = useData()`)
 
-**Documentation**: Full documentation is available at https://fragno.dev/docs
+**Documentation**: https://fragno.dev/docs
+
+All docs are also available with a `.md` extension: https://fragno.dev/docs.md
 
 ## Architecture
 
@@ -24,6 +26,22 @@ Fragments follow a core pattern:
 2. **Client-side**: Auto-generated type-safe hooks for each route
 3. **Code splitting**: Server-only code (handlers, dependencies) is stripped from client bundles
 
+### Fragment Configuration
+
+Database-enabled Fragments require `FragnoPublicConfigWithDatabase`:
+
+```typescript
+export function createMyFragment(
+  config: MyFragmentConfig = {},
+  options: FragnoPublicConfigWithDatabase, // Enforces databaseAdapter requirement
+) {
+  return createFragment(fragmentDef, config, [], options);
+}
+```
+
+For complete database documentation, see:
+https://fragno.dev/docs/for-library-authors/database-integration/overview.md
+
 ## File Structure & Core Concepts
 
 ### `src/index.ts` - Main Fragment Definition
@@ -94,6 +112,107 @@ points:
 - Production uses built files from `dist/`
 - When adding new framework exports, add corresponding client files in `src/client/`
 
+## Database Integration (Optional)
+
+Some Fragments require persistent storage. Fragno provides an optional database layer via
+`@fragno-dev/db` that integrates with your users' existing databases.
+
+### When to Use Database Integration
+
+Use `defineFragmentWithDatabase()` when your Fragment needs to:
+
+- Store persistent data (comments, likes, user preferences, etc.)
+- Query structured data efficiently
+- Maintain data integrity with indexes and constraints
+- Provide users with full control over their data
+
+### Schema Definition
+
+Database schemas are defined in a separate `schema.ts` file using the Fragno schema builder:
+
+```typescript
+import { column, idColumn, schema } from "@fragno-dev/db/schema";
+
+export const noteSchema = schema((s) => {
+  return s.addTable("note", (t) => {
+    return t
+      .addColumn("id", idColumn()) // Auto-generated ID
+      .addColumn("content", column("string"))
+      .addColumn("userId", column("string"))
+      .addColumn("createdAt", column("timestamp").defaultTo$("now"))
+      .createIndex("idx_note_user", ["userId"]); // Index for efficient queries
+  });
+});
+```
+
+**Key concepts**:
+
+- **Append-only**: Schemas use an append-only log approach. Never modify existing operations -
+  always add new ones
+- **Versioning**: Each schema operation increments the version number
+- **Indexes**: Create indexes on columns you'll frequently query (e.g., foreign keys, user IDs)
+- **Defaults**: `.defaultTo(value)` or `.defaultTo((b) => b.now())` for DB defaults;
+  `.defaultTo$((b) => b.cuid())` for runtime defaults
+
+### Using the ORM
+
+The ORM is available in both `withDependencies()` and `withServices()` via the `orm` parameter:
+
+```typescript
+const fragmentDef = defineFragmentWithDatabase<Config>("my-fragment")
+  .withDatabase(mySchema)
+  .withServices(({ orm }) => {
+    return {
+      createNote: async (note) => {
+        const id = await orm.create("note", note);
+        return { id: id.toJSON(), ...note };
+      },
+      getNotesByUser: (userId: string) => {
+        // Use whereIndex for efficient indexed queries
+        return orm.find("note", (b) =>
+          b.whereIndex("idx_note_user", (eb) => eb("userId", "=", userId)),
+        );
+      },
+    };
+  });
+```
+
+**ORM methods**:
+
+- `orm.create(table, data)` - Insert a row, returns FragnoId
+- `orm.find(table, builder)` - Query rows with filtering
+- `orm.findOne(table, builder)` - Query a single row
+- `orm.update(table, id, data)` - Update a row by ID
+- `orm.delete(table, id)` - Delete a row by ID
+- `.whereIndex(indexName, condition)` - Use indexes for efficient queries
+
+### Transactions (Unit of Work)
+
+Two-phase pattern for atomic operations (optimistic concurrency control):
+
+```typescript
+// Phase 1: Retrieve with version tracking
+const uow = orm
+  .createUnitOfWork()
+  .find("users", (b) => b.whereIndex("primary", (eb) => eb("id", "=", userId)))
+  .find("accounts", (b) => b.whereIndex("idx_user", (eb) => eb("userId", "=", userId)));
+const [users, accounts] = await uow.executeRetrieve();
+
+// Phase 2: Mutate atomically
+uow.update("users", users[0].id, (b) => b.set({ lastLogin: new Date() }).check());
+uow.update("accounts", accounts[0].id, (b) =>
+  b.set({ balance: accounts[0].balance + 100 }).check(),
+);
+
+const { success } = await uow.executeMutations();
+if (!success) {
+  /* Version conflict - retry */
+}
+```
+
+**Notes**: `.check()` enables optimistic concurrency control; requires `FragnoId` objects (not
+string IDs); use `uow.getCreatedIds()` for new record IDs
+
 ## Strategies for Building Fragments
 
 ### OpenAPI/Swagger Spec → Fragno Routes

package/templates/optional/database/index.ts

@@ -0,0 +1,141 @@
+import {
+  defineRoute,
+  defineRoutes,
+  createFragment,
+  type FragnoPublicClientConfig,
+} from "@fragno-dev/core";
+import { createClientBuilder } from "@fragno-dev/core/client";
+import {
+  defineFragmentWithDatabase,
+  type FragnoPublicConfigWithDatabase,
+} from "@fragno-dev/db/fragment";
+import type { AbstractQuery, TableToInsertValues } from "@fragno-dev/db/query";
+import { noteSchema } from "./schema";
+
+// NOTE: We use zod here for defining schemas, but any StandardSchema library can be used!
+//       For a complete list see:
+// https://github.com/standard-schema/standard-schema#what-schema-libraries-implement-the-spec
+import { z } from "zod";
+
+export interface ExampleConfig {
+  // Add any server-side configuration here if needed
+}
+
+type ExampleServices = {
+  createNote: (note: TableToInsertValues<typeof noteSchema.tables.note>) => Promise<{
+    id: string;
+    content: string;
+    userId: string;
+    createdAt: Date;
+  }>;
+  getNotes: () => Promise<
+    Array<{
+      id: string;
+      content: string;
+      userId: string;
+      createdAt: Date;
+    }>
+  >;
+  getNotesByUser: (userId: string) => Promise<
+    Array<{
+      id: string;
+      content: string;
+      userId: string;
+      createdAt: Date;
+    }>
+  >;
+};
+
+type ExampleDeps = {
+  orm: AbstractQuery<typeof noteSchema>;
+};
+
+const exampleRoutesFactory = defineRoutes<ExampleConfig, ExampleDeps, ExampleServices>().create(
+  ({ services }) => {
+    return [
+      defineRoute({
+        method: "GET",
+        path: "/notes",
+        queryParameters: ["userId"],
+        outputSchema: z.array(
+          z.object({
+            id: z.string(),
+            content: z.string(),
+            userId: z.string(),
+            createdAt: z.date(),
+          }),
+        ),
+        handler: async ({ query }, { json }) => {
+          const userId = query.get("userId");
+
+          if (userId) {
+            const notes = await services.getNotesByUser(userId);
+            return json(notes);
+          }
+
+          const notes = await services.getNotes();
+          return json(notes);
+        },
+      }),
+
+      defineRoute({
+        method: "POST",
+        path: "/notes",
+        inputSchema: z.object({ content: z.string(), userId: z.string() }),
+        outputSchema: z.object({
+          id: z.string(),
+          content: z.string(),
+          userId: z.string(),
+          createdAt: z.date(),
+        }),
+        errorCodes: [],
+        handler: async ({ input }, { json }) => {
+          const { content, userId } = await input.valid();
+
+          const note = await services.createNote({ content, userId });
+          return json(note);
+        },
+      }),
+    ];
+  },
+);
+
+const exampleFragmentDefinition = defineFragmentWithDatabase<ExampleConfig>("example-fragment")
+  .withDatabase(noteSchema)
+  .withServices(({ orm }) => {
+    return {
+      createNote: async (note: TableToInsertValues<typeof noteSchema.tables.note>) => {
+        const id = await orm.create("note", note);
+        return {
+          ...note,
+          id: id.toJSON(),
+          createdAt: note.createdAt ?? new Date(),
+        };
+      },
+      getNotes: () => {
+        return orm.find("note", (b) => b);
+      },
+      getNotesByUser: (userId: string) => {
+        return orm.find("note", (b) =>
+          b.whereIndex("idx_note_user", (eb) => eb("userId", "=", userId)),
+        );
+      },
+    };
+  });
+
+export function createExampleFragment(
+  config: ExampleConfig = {},
+  fragnoConfig: FragnoPublicConfigWithDatabase,
+) {
+  return createFragment(exampleFragmentDefinition, config, [exampleRoutesFactory], fragnoConfig);
+}
+
+export function createExampleFragmentClients(fragnoConfig: FragnoPublicClientConfig) {
+  const b = createClientBuilder(exampleFragmentDefinition, fragnoConfig, [exampleRoutesFactory]);
+
+  return {
+    useNotes: b.createHook("/notes"),
+    useCreateNote: b.createMutator("POST", "/notes"),
+  };
+}
+export type { FragnoRouteConfig } from "@fragno-dev/core/api";

package/templates/optional/database/schema.ts

@@ -0,0 +1,15 @@
+import { column, idColumn, schema } from "@fragno-dev/db/schema";
+
+export const noteSchema = schema((s) => {
+  return s.addTable("note", (t) => {
+    return t
+      .addColumn("id", idColumn())
+      .addColumn("content", column("string"))
+      .addColumn("userId", column("string"))
+      .addColumn(
+        "createdAt",
+        column("timestamp").defaultTo((b) => b.now()),
+      )
+      .createIndex("idx_note_user", ["userId"]);
+  });
+});

package/.turbo/turbo-test.log

@@ -1,66 +0,0 @@
-$ vitest run
-
- RUN  v3.2.4 /home/runner/work/fragno/fragno/packages/create
-      Coverage enabled with istanbul
-
- ✓ src/utils.test.ts (1 test) 4ms
-stdout | src/integration.test.ts > fragment with rspack
-temp /tmp/fragment-test-tsdown-1760972394592
-
-stdout | src/integration.test.ts > fragment with tsdown > package.json correctly templated
-temp /tmp/fragment-test-esbuild-1760972394596
-
-stdout | src/integration.test.ts > fragment with esbuild > package.json correctly templated
-temp /tmp/fragment-test-vite-1760972394596
-
-stdout | src/integration.test.ts > fragment with vite > package.json correctly templated
-temp /tmp/fragment-test-rollup-1760972394596
-
-stdout | src/integration.test.ts > fragment with rollup > package.json correctly templated
-temp /tmp/fragment-test-webpack-1760972394597
-
-stdout | src/integration.test.ts > fragment with webpack > package.json correctly templated
-temp /tmp/fragment-test-rspack-1760972394597
-
-stdout | src/integration.test.ts > fragment with webpack > compiles
-
-
-stdout | src/integration.test.ts > fragment with rspack > compiles
-
-
-stdout | src/integration.test.ts > fragment with rollup
-
-
-stdout | src/integration.test.ts
-
-
-stdout | src/integration.test.ts
-
-
-stdout | src/integration.test.ts > fragment with webpack > builds
-
-
- ✓ src/integration.test.ts (30 tests | 1 skipped) 24967ms
-   ✓ fragment with tsdown > installs  2596ms
-   ✓ fragment with tsdown > compiles  7152ms
-   ✓ fragment with tsdown > builds  9413ms
-   ✓ fragment with esbuild > installs  2515ms
-   ✓ fragment with esbuild > compiles  6488ms
-   ✓ fragment with esbuild > builds  1739ms
-   ✓ fragment with vite > installs  2517ms
-   ✓ fragment with vite > compiles  6562ms
-   ✓ fragment with vite > builds  6624ms
-   ✓ fragment with rollup > installs  2570ms
-   ✓ fragment with rollup > compiles  6173ms
-   ✓ fragment with webpack > installs  2607ms
-   ✓ fragment with webpack > compiles  6274ms
-   ✓ fragment with webpack > builds  13005ms
-   ✓ fragment with rspack > installs  3026ms
-   ✓ fragment with rspack > compiles  5303ms
-   ✓ fragment with rspack > builds  3715ms
-
- Test Files  2 passed (2)
-      Tests  30 passed | 1 skipped (31)
-   Start at  14:59:53
-   Duration  25.62s (transform 325ms, setup 0ms, collect 498ms, tests 24.97s, environment 0ms, prepare 179ms)
-

package/.turbo/turbo-types$colon$check.log

@@ -1 +0,0 @@
-$ tsc --noEmit