@fragno-dev/create 0.1.0 → 0.1.1

package/package.json

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

package/src/integration.test.ts

@@ -76,7 +76,7 @@ function createFragmentTestSuite(buildTool: BuildTool, withDatabase: boolean) {
         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",

package/src/package-json.ts

@@ -1,9 +1,9 @@
 import type { BuildTools } from "./index";
 
-const fragnoCoreVersion = "^0.1.1";
-const fragnoDbVersion = "^0.1.1";
+const fragnoCoreVersion = "^0.1.2";
+const fragnoDbVersion = "^0.1.2";
 const unpluginFragnoVersion = "^0.0.2";
-const fragnoCliVersion = "^0.1.2";
+const fragnoCliVersion = "^0.1.3";
 
 export const basePkg: Record<string, unknown> = {
   dependencies: {

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,79 +26,6 @@ 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
 
-## 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**: Use `.defaultTo(value)` or `.defaultTo$("now")` for timestamps
-
-### 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
-
 ### Fragment Configuration
 
 Database-enabled Fragments require `FragnoPublicConfigWithDatabase`:
@@ -183,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/schema.ts

@@ -6,7 +6,10 @@ export const noteSchema = schema((s) => {
       .addColumn("id", idColumn())
       .addColumn("content", column("string"))
       .addColumn("userId", column("string"))
-      .addColumn("createdAt", column("timestamp").defaultTo$("now"))
+      .addColumn(
+        "createdAt",
+        column("timestamp").defaultTo((b) => b.now()),
+      )
       .createIndex("idx_note_user", ["userId"]);
   });
 });