@fragno-dev/corpus 0.0.4 → 0.0.5

package/dist/subjects/client-state-management.md

@@ -0,0 +1,305 @@
+# Client-side State Management
+
+Client-side state management in Fragno uses Nanostores under the hood, providing reactive stores
+that integrate with React, Vue, Svelte, and vanilla JavaScript. The `ClientBuilder` class creates
+hooks and mutators for your routes.
+
+```typescript @fragno-imports
+import {
+  defineFragment,
+  defineRoute,
+  defineRoutes,
+  type FragnoPublicClientConfig,
+} from "@fragno-dev/core";
+import { createClientBuilder } from "@fragno-dev/core/client";
+import { computed } from "nanostores";
+import { z } from "zod";
+```
+
+```typescript @fragno-prelude:fragment-setup
+interface TodoConfig {
+  apiUrl: string;
+}
+
+const todoFragment = defineFragment<TodoConfig>("todos");
+
+const routes = defineRoutes<TodoConfig>().create(() => [
+  defineRoute({
+    method: "GET",
+    path: "/todos",
+    outputSchema: z.array(z.object({ id: z.string(), text: z.string(), completed: z.boolean() })),
+    handler: async (_, { json }) => json([]),
+  }),
+  defineRoute({
+    method: "POST",
+    path: "/todos",
+    inputSchema: z.object({ text: z.string() }),
+    outputSchema: z.object({ id: z.string(), text: z.string(), completed: z.boolean() }),
+    handler: async ({ input }, { json }) => {
+      const data = await input.valid();
+      return json({ id: "todo-1", text: data.text, completed: false });
+    },
+  }),
+  defineRoute({
+    method: "PUT",
+    path: "/todos/:id",
+    inputSchema: z.object({ completed: z.boolean() }),
+    outputSchema: z.object({ id: z.string(), text: z.string(), completed: z.boolean() }),
+    handler: async ({ input }, { json }) => {
+      const data = await input.valid();
+      return json({ id: "todo-1", text: "Updated todo", completed: data.completed });
+    },
+  }),
+  defineRoute({
+    method: "DELETE",
+    path: "/todos/:id",
+    outputSchema: z.object({ success: z.boolean() }),
+    handler: async (_, { json }) => json({ success: true }),
+  }),
+  defineRoute({
+    method: "POST",
+    path: "/chat/stream",
+    inputSchema: z.object({
+      messages: z.array(z.object({ role: z.string(), content: z.string() })),
+    }),
+    outputSchema: z.array(z.object({ type: z.string(), delta: z.string().optional() })),
+    handler: async (_, { jsonStream }) =>
+      jsonStream(async (stream) => {
+        stream.write({ type: "response.output_text.delta", delta: "Hello" });
+        stream.write({ type: "response.output_text.delta", delta: " World" });
+      }),
+  }),
+]);
+```
+
+## Basic ClientBuilder Setup
+
+Create a client builder and export hooks for your fragment's routes.
+
+```typescript @fragno-test:basic-client-builder
+// should create a basic client builder
+export function createTodoClient(fragnoConfig: FragnoPublicClientConfig = {}) {
+  const builder = createClientBuilder(todoFragment, fragnoConfig, [routes]);
+
+  return {
+    useTodos: builder.createHook("/todos"),
+  };
+}
+
+const client = createTodoClient();
+expect(client.useTodos).toBeDefined();
+```
+
+## Reading Data with createHook
+
+Create read-only query hooks for GET routes.
+
+```typescript @fragno-test:create-hook
+// should create a hook for GET routes
+export function createTodoClient(fragnoConfig: FragnoPublicClientConfig = {}) {
+  const builder = createClientBuilder(todoFragment, fragnoConfig, [routes]);
+
+  return {
+    useTodos: builder.createHook("/todos"),
+  };
+}
+
+const client = createTodoClient();
+const hook = client.useTodos;
+
+// Hook has store and query methods
+expect(hook.store).toBeDefined();
+expect(hook.query).toBeDefined();
+```
+
+Users call the hook with path and query parameters. The hook returns `data`, `loading`, and `error`
+properties that are reactive.
+
+## Mutating Data with createMutator
+
+Create mutators for POST, PUT, DELETE routes. Returns `data`, `loading`, `error`, and a `mutate`
+function.
+
+```typescript @fragno-test:create-mutator
+// should create mutators for POST/PUT/DELETE routes
+export function createTodoClient(fragnoConfig: FragnoPublicClientConfig = {}) {
+  const builder = createClientBuilder(todoFragment, fragnoConfig, [routes]);
+
+  return {
+    useTodos: builder.createHook("/todos"),
+    useCreateTodo: builder.createMutator("POST", "/todos"),
+    useUpdateTodo: builder.createMutator("PUT", "/todos/:id"),
+    useDeleteTodo: builder.createMutator("DELETE", "/todos/:id"),
+  };
+}
+
+const client = createTodoClient();
+expect(client.useCreateTodo.mutatorStore).toBeDefined();
+expect(client.useUpdateTodo.mutatorStore).toBeDefined();
+expect(client.useDeleteTodo.mutatorStore).toBeDefined();
+```
+
+## Custom Invalidation
+
+By default, mutations invalidate the same route. Use `onInvalidate` to invalidate other routes.
+
+```typescript @fragno-test:custom-invalidation
+// should invalidate other routes on mutation
+export function createTodoClient(fragnoConfig: FragnoPublicClientConfig = {}) {
+  const builder = createClientBuilder(todoFragment, fragnoConfig, [routes]);
+
+  return {
+    useTodos: builder.createHook("/todos"),
+    useCreateTodo: builder.createMutator("POST", "/todos", (invalidate) => {
+      invalidate("GET", "/todos", {});
+    }),
+    useUpdateTodo: builder.createMutator("PUT", "/todos/:id", (invalidate, params) => {
+      invalidate("GET", "/todos", {});
+    }),
+    useDeleteTodo: builder.createMutator("DELETE", "/todos/:id", (invalidate, params) => {
+      invalidate("GET", "/todos", {});
+    }),
+  };
+}
+
+const client = createTodoClient();
+expect(client.useCreateTodo.mutatorStore).toBeDefined();
+```
+
+## Derived Data with Nanostores
+
+Use `computed` to create derived stores. Must wrap with `builder.createStore` for framework
+reactivity.
+
+```typescript @fragno-test:derived-data
+// should create derived stores from mutator data
+export function createChatClient(fragnoConfig: FragnoPublicClientConfig = {}) {
+  const builder = createClientBuilder(todoFragment, fragnoConfig, [routes]);
+
+  const chatStream = builder.createMutator("POST", "/chat/stream");
+
+  const aggregatedMessage = computed(chatStream.mutatorStore, ({ data }) => {
+    return (data ?? [])
+      .filter((item) => item.type === "response.output_text.delta")
+      .map((item) => item.delta)
+      .join("");
+  });
+
+  return {
+    useChatStream: chatStream,
+    useAggregatedMessage: builder.createStore(aggregatedMessage),
+  };
+}
+
+const client = createChatClient();
+expect(client.useAggregatedMessage).toBeDefined();
+```
+
+## Arbitrary Values and Custom Functions
+
+Wrap custom objects with `builder.createStore` to make properties reactive. Functions remain
+unchanged.
+
+```typescript @fragno-test:arbitrary-values
+// should wrap custom objects and functions
+export function createChatClient(fragnoConfig: FragnoPublicClientConfig = {}) {
+  const builder = createClientBuilder(todoFragment, fragnoConfig, [routes]);
+
+  const chatStream = builder.createMutator("POST", "/chat/stream");
+
+  const aggregatedMessage = computed(chatStream.mutatorStore, ({ data }) => {
+    return (data ?? []).map((item) => item.delta).join("");
+  });
+
+  function sendMessage(message: string) {
+    chatStream.mutatorStore.mutate({
+      body: {
+        messages: [{ role: "user", content: message }],
+      },
+    });
+  }
+
+  return {
+    useSendMessage: builder.createStore({
+      response: aggregatedMessage,
+      responseLoading: computed(chatStream.mutatorStore, ({ loading }) => loading),
+      sendMessage,
+    }),
+  };
+}
+
+const client = createChatClient();
+expect(client.useSendMessage).toBeDefined();
+```
+
+Only top-level properties are made reactive. Deeply nested keys are not transformed.
+
+## Custom Fetcher Configuration
+
+Set default fetch options or provide a custom fetch function.
+
+```typescript @fragno-test:custom-fetcher-options
+// should set custom fetch options
+export function createTodoClient(fragnoConfig: FragnoPublicClientConfig = {}) {
+  const builder = createClientBuilder(todoFragment, fragnoConfig, [routes], {
+    type: "options",
+    options: { credentials: "include" },
+  });
+
+  return {
+    useTodos: builder.createHook("/todos"),
+  };
+}
+
+const client = createTodoClient();
+expect(client.useTodos).toBeDefined();
+```
+
+```typescript @fragno-test:custom-fetch-function
+// should provide custom fetch function
+const customFetch = async (url: RequestInfo | URL, init?: RequestInit) => {
+  return fetch(url, { ...init, headers: { ...init?.headers, "X-Custom": "header" } });
+};
+
+export function createTodoClient(fragnoConfig: FragnoPublicClientConfig = {}) {
+  const builder = createClientBuilder(todoFragment, fragnoConfig, [routes], {
+    type: "function",
+    fetcher: customFetch,
+  });
+
+  return {
+    useTodos: builder.createHook("/todos"),
+  };
+}
+
+const client = createTodoClient();
+expect(client.useTodos).toBeDefined();
+```
+
+User configuration takes precedence: custom fetch functions override everything, RequestInit options
+deep merge with user values winning conflicts.
+
+## Custom Backend Calls
+
+Use `buildUrl()` and `getFetcher()` for requests beyond `createHook`/`createMutator`.
+
+```typescript @fragno-test:custom-backend-calls
+// should build URLs and get fetcher for custom calls
+export function createTodoClient(fragnoConfig: FragnoPublicClientConfig = {}) {
+  const builder = createClientBuilder(todoFragment, fragnoConfig, [routes]);
+
+  async function customCall(userId: string) {
+    const { fetcher, defaultOptions } = builder.getFetcher();
+    const url = builder.buildUrl("/todos/:id", { path: { id: userId } });
+    return fetcher(url, { ...defaultOptions, method: "GET" }).then((r) => r.json());
+  }
+
+  return {
+    useTodos: builder.createHook("/todos"),
+    customCall,
+  };
+}
+
+const client = createTodoClient();
+expect(client.customCall).toBeDefined();
+```

package/dist/subjects/database-adapters.md

@@ -0,0 +1,88 @@
+# Database Adapters
+
+Database adapters connect Fragno's database API to your existing ORM (Kysely or Drizzle). They allow
+fragments to work with your application's database without dictating which ORM you use.
+
+```typescript @fragno-imports
+import type { DatabaseAdapter } from "@fragno-dev/db";
+```
+
+## What is a Database Adapter?
+
+A database adapter is a bridge between Fragno's type-safe database API and your underlying ORM. It
+translates Fragno's query operations into ORM-specific syntax.
+
+```typescript @fragno-test:what-is-adapter types-only
+// Adapters implement the DatabaseAdapter interface
+declare const adapter: DatabaseAdapter;
+
+// Fragments receive an adapter through their configuration
+interface FragmentConfig {
+  databaseAdapter: DatabaseAdapter;
+}
+```
+
+When a fragment needs database access, users pass an adapter configured with their ORM instance.
+
+## Supported Providers
+
+Both KyselyAdapter and DrizzleAdapter support three database providers:
+
+- `"postgresql"` - PostgreSQL databases
+- `"mysql"` - MySQL and MariaDB databases
+- `"sqlite"` - SQLite databases
+
+Choose the provider that matches your database type when creating an adapter.
+
+## Factory Functions
+
+Adapters can be created from factory functions instead of direct ORM instances. This is useful for
+lazy initialization (in serverless environments).
+
+```typescript @fragno-test:factory-functions types-only
+async function createDbConnection() {
+  const db = {} as any; // Your ORM instance
+  return db;
+}
+
+declare const DrizzleAdapter: any;
+export const adapter = new DrizzleAdapter({
+  db: createDbConnection,
+  provider: "postgresql",
+});
+```
+
+The adapter calls the factory function when it needs a database connection.
+
+## Shared Adapters
+
+Multiple fragments can share the same adapter, meaning they all use your application's single
+database connection.
+
+```typescript @fragno-test:shared-adapters types-only
+declare const adapter: DatabaseAdapter;
+
+// All fragments use the same adapter
+export interface Fragment1Config {
+  databaseAdapter: typeof adapter;
+}
+
+export interface Fragment2Config {
+  databaseAdapter: typeof adapter;
+}
+```
+
+This ensures fragments integrate seamlessly with your existing database infrastructure.
+
+## Cleanup
+
+Adapters manage connection lifecycle automatically. Call `close()` when shutting down your
+application to properly release database connections.
+
+```typescript @fragno-test:cleanup types-only
+declare const adapter: DatabaseAdapter;
+
+export async function cleanup() {
+  await adapter.close();
+}
+```

package/dist/subjects/database-querying.md

@@ -0,0 +1,316 @@
+# Database Querying
+
+Fragno provides a unified database query API that works across different ORMs. This guide covers
+CRUD operations and querying with conditions.
+
+```typescript @fragno-imports
+import { defineFragmentWithDatabase } from "@fragno-dev/db/fragment";
+import { schema, idColumn, column } from "@fragno-dev/db/schema";
+import type { AbstractQuery } from "@fragno-dev/db/query";
+import { createDatabaseFragmentForTest } from "@fragno-dev/test";
+```
+
+```typescript @fragno-prelude:schema
+// Example schema for testing
+const userSchema = schema((s) => {
+  return s
+    .addTable("users", (t) => {
+      return t
+        .addColumn("id", idColumn())
+        .addColumn("email", column("string"))
+        .addColumn("name", column("string"))
+        .addColumn("age", column("integer").nullable())
+        .createIndex("idx_email", ["email"], { unique: true });
+    })
+    .addTable("posts", (t) => {
+      return t
+        .addColumn("id", idColumn())
+        .addColumn("title", column("string"))
+        .addColumn("content", column("string"))
+        .addColumn("authorId", column("string"))
+        .addColumn("publishedAt", column("timestamp").nullable())
+        .createIndex("idx_author", ["authorId"]);
+    });
+});
+
+type UserSchema = typeof userSchema;
+```
+
+```typescript @fragno-test-init
+// Create a test fragment with database
+const testFragmentDef = defineFragmentWithDatabase("test-db-fragment").withDatabase(userSchema);
+
+const { fragment, test } = await createDatabaseFragmentForTest(
+  { definition: testFragmentDef, routes: [] },
+  {
+    adapter: { type: "kysely-sqlite" },
+  },
+);
+
+const db = fragment.db;
+```
+
+## Create
+
+Create a single record in the database.
+
+```typescript @fragno-test:create-user
+// should create a single user
+const userId = await db.create("users", {
+  id: "user-123",
+  email: "john@example.com",
+  name: "John Doe",
+  age: 30,
+});
+
+expect(userId).toBeDefined();
+expect(userId.valueOf()).toBe("user-123");
+```
+
+The `create` method returns a `FragnoId` object representing the created record's ID.
+
+## Create Many
+
+Create multiple records at once.
+
+```typescript @fragno-test:create-many
+// should create multiple users at once
+const userIds = await db.createMany("users", [
+  {
+    id: "user-1",
+    email: "user1@example.com",
+    name: "User One",
+    age: 25,
+  },
+  {
+    id: "user-2",
+    email: "user2@example.com",
+    name: "User Two",
+    age: 35,
+  },
+]);
+
+expect(userIds).toHaveLength(2);
+expect(userIds[0].valueOf()).toBe("user-1");
+expect(userIds[1].valueOf()).toBe("user-2");
+```
+
+## Find First
+
+Query for a single record using an index.
+
+```typescript @fragno-test:find-user-by-email
+// should find user by email using index
+await db.create("users", {
+  id: "user-find-1",
+  email: "findme@example.com",
+  name: "Find Me",
+  age: 28,
+});
+
+const user = await db.findFirst("users", (b) =>
+  b.whereIndex("idx_email", (eb) => eb("email", "=", "findme@example.com")),
+);
+
+expect(user).toBeDefined();
+expect(user?.email).toBe("findme@example.com");
+expect(user?.name).toBe("Find Me");
+```
+
+Use `findFirst` when you expect a single result or want to get the first matching record.
+
+## Find First with Select
+
+Query a single record and select specific columns.
+
+```typescript @fragno-test:find-user-select
+export async function findUserEmailOnly(userId: string) {
+  const user = await db.findFirst("users", (b) =>
+    b.whereIndex("primary", (eb) => eb("id", "=", userId)).select(["id", "email"]),
+  );
+
+  return user; // Returns only id and email fields
+}
+```
+
+## Find Many
+
+Query for multiple records matching conditions.
+
+```typescript @fragno-test:find-many
+// should find multiple posts by author
+await db.createMany("posts", [
+  {
+    id: "post-1",
+    title: "First Post",
+    content: "Content 1",
+    authorId: "author-123",
+    publishedAt: null,
+  },
+  {
+    id: "post-2",
+    title: "Second Post",
+    content: "Content 2",
+    authorId: "author-123",
+    publishedAt: null,
+  },
+  {
+    id: "post-3",
+    title: "Other Post",
+    content: "Content 3",
+    authorId: "author-456",
+    publishedAt: null,
+  },
+]);
+
+const posts = await db.find("posts", (b) =>
+  b.whereIndex("idx_author", (eb) => eb("authorId", "=", "author-123")),
+);
+
+expect(posts).toHaveLength(2);
+expect(posts[0].authorId).toBe("author-123");
+expect(posts[1].authorId).toBe("author-123");
+```
+
+The `find` method returns all records matching the where clause.
+
+## Find with Pagination
+
+Limit the number of results returned.
+
+```typescript @fragno-test:find-paginated
+export async function findUsersPaginated(pageSize: number) {
+  const users = await db.find("users", (b) => b.whereIndex("primary").pageSize(pageSize));
+
+  return users;
+}
+```
+
+## Cursor-Based Pagination
+
+Use `findWithCursor` for efficient pagination with cursor support.
+
+```typescript @fragno-test:cursor-pagination
+const firstPage = await db.findWithCursor("users", (b) =>
+  b.whereIndex("idx_email").orderByIndex("idx_email", "asc").pageSize(2),
+);
+
+const cursor = firstPage.cursor;
+if (cursor) {
+  const nextPage = await db.findWithCursor("users", (b) => b.after(cursor));
+}
+```
+
+The `findWithCursor` method returns a `CursorResult` object containing:
+
+- `items`: The array of results for the current page
+- `cursor`: A `Cursor` object for fetching the next page (undefined if no more results)
+
+The cursor automatically stores pagination metadata (index, ordering, page size), so you can simply
+pass it to `b.after()` for the next page.
+
+## Find All
+
+Query all records from a table.
+
+```typescript @fragno-test:find-all
+export async function findAllUsers() {
+  const users = await db.find("users", (b) => b.whereIndex("primary"));
+
+  return users;
+}
+```
+
+When using `whereIndex("primary")` without conditions, it returns all records.
+
+## Update
+
+Update a single record by ID.
+
+```typescript @fragno-test:update-user
+// should update a user's email
+await db.create("users", {
+  id: "user-update-1",
+  email: "old@example.com",
+  name: "Update Test",
+  age: 30,
+});
+
+await db.update("users", "user-update-1", (b) =>
+  b.set({
+    email: "new@example.com",
+  }),
+);
+
+const updatedUser = await db.findFirst("users", (b) =>
+  b.whereIndex("primary", (eb) => eb("id", "=", "user-update-1")),
+);
+
+expect(updatedUser?.email).toBe("new@example.com");
+expect(updatedUser?.name).toBe("Update Test");
+```
+
+The `update` method modifies a single record identified by its ID.
+
+## Update Many
+
+Update multiple records matching a condition.
+
+```typescript @fragno-test:update-many
+export async function updatePostsPublishedDate(authorId: string, publishedAt: Date) {
+  await db.updateMany("posts", (b) =>
+    b.whereIndex("idx_author", (eb) => eb("authorId", "=", authorId)).set({ publishedAt }),
+  );
+}
+```
+
+`updateMany` finds all matching records and updates them.
+
+## Delete
+
+Delete a single record by ID.
+
+```typescript @fragno-test:delete-user
+// should delete a user by ID
+await db.create("users", {
+  id: "user-delete-1",
+  email: "delete@example.com",
+  name: "Delete Me",
+  age: 25,
+});
+
+await db.delete("users", "user-delete-1");
+
+const deletedUser = await db.findFirst("users", (b) =>
+  b.whereIndex("primary", (eb) => eb("id", "=", "user-delete-1")),
+);
+
+expect(deletedUser).toBeNull();
+```
+
+## Delete Many
+
+Delete multiple records matching a condition.
+
+```typescript @fragno-test:delete-many
+export async function deletePostsByAuthor(authorId: string) {
+  await db.deleteMany("posts", (b) =>
+    b.whereIndex("idx_author", (eb) => eb("authorId", "=", authorId)),
+  );
+}
+```
+
+`deleteMany` finds all matching records and deletes them.
+
+## Querying with Conditions
+
+Use expression builders within `whereIndex()` to create queries with conditions.
+
+```typescript @fragno-test:query-conditions
+const user = await db.findFirst("users", (b) =>
+  b.whereIndex("idx_email", (eb) => eb("email", "=", "adult1@example.com")),
+);
+```
+
+The expression builder (the `eb` parameter) is used within the `whereIndex()` callback to specify
+conditions on indexed columns.