@fragno-dev/corpus 0.0.5 → 0.0.7

package/README.md

@@ -53,8 +53,10 @@ Optional ID syntax (`:schema`) helps identify code blocks for agent references.
 
 Test-only initialization code (not shown to users, only used in generated tests):
 
-\`\`\`typescript @fragno-test-init const { fragment } = await
-createDatabaseFragmentForTest(testFragmentDef, []); const orm = fragment.services.orm; \`\`\`
+\`\`\`typescript @fragno-test-init const { fragments } = await buildDatabaseFragmentsTest()
+.withTestAdapter({ type: "kysely-sqlite" }) .withFragment("test",
+instantiate(testFragmentDef).withRoutes([]), { definition: testFragmentDef }) .build(); const db =
+fragments.test.db; \`\`\`
 
 ### @fragno-test
 

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

@@ -5,12 +5,8 @@ that integrate with React, Vue, Svelte, and vanilla JavaScript. The `ClientBuild
 hooks and mutators for your routes.
 
 ```typescript @fragno-imports
-import {
-  defineFragment,
-  defineRoute,
-  defineRoutes,
-  type FragnoPublicClientConfig,
-} from "@fragno-dev/core";
+import { defineFragment, defineRoute, defineRoutes } from "@fragno-dev/core";
+import type { FragnoPublicClientConfig } from "@fragno-dev/core/client";
 import { createClientBuilder } from "@fragno-dev/core/client";
 import { computed } from "nanostores";
 import { z } from "zod";
@@ -23,7 +19,7 @@ interface TodoConfig {
 
 const todoFragment = defineFragment<TodoConfig>("todos");
 
-const routes = defineRoutes<TodoConfig>().create(() => [
+const routes = defineRoutes(todoFragment).create(({ defineRoute }) => [
   defineRoute({
     method: "GET",
     path: "/todos",

package/dist/subjects/database-querying.md

@@ -4,10 +4,11 @@ Fragno provides a unified database query API that works across different ORMs. T
 CRUD operations and querying with conditions.
 
 ```typescript @fragno-imports
-import { defineFragmentWithDatabase } from "@fragno-dev/db/fragment";
+import { defineFragment, instantiate } from "@fragno-dev/core";
+import { withDatabase } from "@fragno-dev/db";
 import { schema, idColumn, column } from "@fragno-dev/db/schema";
-import type { AbstractQuery } from "@fragno-dev/db/query";
-import { createDatabaseFragmentForTest } from "@fragno-dev/test";
+import type { SimpleQueryInterface } from "@fragno-dev/db/query";
+import { buildDatabaseFragmentsTest } from "@fragno-dev/test";
 ```
 
 ```typescript @fragno-prelude:schema
@@ -38,16 +39,17 @@ type UserSchema = typeof userSchema;
 
 ```typescript @fragno-test-init
 // Create a test fragment with database
-const testFragmentDef = defineFragmentWithDatabase("test-db-fragment").withDatabase(userSchema);
+const testFragmentDef = defineFragment<{}>("test-fragment")
+  .extend(withDatabase(userSchema))
+  .providesBaseService(() => ({}))
+  .build();
 
-const { fragment, test } = await createDatabaseFragmentForTest(
-  { definition: testFragmentDef, routes: [] },
-  {
-    adapter: { type: "kysely-sqlite" },
-  },
-);
+const { fragments, test } = await buildDatabaseFragmentsTest()
+  .withTestAdapter({ type: "kysely-sqlite" })
+  .withFragment("test", instantiate(testFragmentDef).withConfig({}).withRoutes([]))
+  .build();
 
-const db = fragment.db;
+const db = fragments.test.db;
 ```
 
 ## Create

package/dist/subjects/defining-routes.md

@@ -4,8 +4,13 @@ Routes are the core of a Fragno fragment, defining HTTP endpoints that handle re
 responses. This guide covers the essential patterns for defining routes.
 
 ```typescript @fragno-imports
-import { defineRoute, defineRoutes, defineFragment, createFragment } from "@fragno-dev/core";
-import type { FragnoPublicConfig } from "@fragno-dev/core";
+import {
+  defineFragment,
+  defineRoute,
+  defineRoutes,
+  instantiate,
+  type FragnoPublicConfig,
+} from "@fragno-dev/core";
 import { z } from "zod";
 ```
 
@@ -151,15 +156,14 @@ Routes can access dependencies defined in `withDependencies` through route facto
 
 ```typescript @fragno-test:using-dependencies
 interface AppConfig {
-  apiKey: string;
+  apiKey?: string;
 }
 
-interface AppDeps {
-  config: AppConfig;
-  timestamp: number;
-}
+const definition = defineFragment<AppConfig>("test")
+  .withDependencies(({ config }) => ({ timestamp: Date.now() }))
+  .build();
 
-export const routesWithDeps = defineRoutes<AppConfig, AppDeps>().create(({ deps }) => {
+export const routesWithDeps = defineRoutes<typeof definition>().create(({ config, deps }) => {
   return [
     defineRoute({
       method: "GET",
@@ -170,7 +174,7 @@ export const routesWithDeps = defineRoutes<AppConfig, AppDeps>().create(({ deps
       }),
       handler: async (_, { json }) => {
         return json({
-          hasApiKey: !!deps.config.apiKey,
+          hasApiKey: !!config.apiKey,
           timestamp: deps.timestamp,
         });
       },
@@ -186,12 +190,17 @@ Dependencies are passed to the route factory function and can be used in route h
 Services defined in `providesService` can be used in routes for business logic.
 
 ```typescript @fragno-test:using-services
-interface DataService {
-  getData: () => string;
-  processData: (input: string) => Promise<string>;
-}
+const definition = defineFragment("test")
+  .withDependencies(({ config }) => ({ timestamp: Date.now() }))
+  .providesBaseService(({ defineService }) =>
+    defineService({
+      getData: () => "Hello, World!",
+      processData: async (input: string) => input,
+    }),
+  )
+  .build();
 
-export const routesWithServices = defineRoutes<{}, {}, DataService>().create(({ services }) => {
+export const routesWithServices = defineRoutes<typeof definition>().create(({ services }) => {
   return [
     defineRoute({
       method: "GET",
@@ -218,55 +227,3 @@ export const routesWithServices = defineRoutes<{}, {}, DataService>().create(({
 ```
 
 Services provide reusable business logic that can be shared across multiple routes.
-
-## Complete Fragment Example
-
-A complete example showing how routes integrate with fragment definition.
-
-```typescript @fragno-test:complete-fragment
-interface MyFragmentConfig {
-  apiKey: string;
-}
-
-interface MyFragmentDeps {
-  config: MyFragmentConfig;
-}
-
-interface MyFragmentServices {
-  getStatus: () => string;
-}
-
-const myFragmentDefinition = defineFragment<MyFragmentConfig>("my-fragment")
-  .withDependencies(({ config }) => {
-    return {
-      config,
-    };
-  })
-  .providesService(({ deps, defineService }) => {
-    return defineService({
-      getStatus: () => `API Key: ${deps.config.apiKey.substring(0, 3)}...`,
-    });
-  });
-
-const myRoutes = defineRoutes<MyFragmentConfig, MyFragmentDeps, MyFragmentServices>().create(
-  ({ services }) => {
-    return [
-      defineRoute({
-        method: "GET",
-        path: "/status",
-        outputSchema: z.string(),
-        handler: async (_, { json }) => {
-          return json(services.getStatus());
-        },
-      }),
-    ];
-  },
-);
-
-export function createMyFragment(config: MyFragmentConfig, options: FragnoPublicConfig = {}) {
-  return createFragment(myFragmentDefinition, config, [myRoutes], options);
-}
-```
-
-This example shows the complete flow: fragment definition with dependencies and services, route
-factory using those services, and the fragment creation function.

package/dist/subjects/drizzle-adapter.md

@@ -7,54 +7,3 @@ import { DrizzleAdapter } from "@fragno-dev/db/adapters/drizzle";
 import type { NodePgDatabase } from "drizzle-orm/node-postgres";
 import type { PgliteDatabase } from "drizzle-orm/pglite";
 ```
-
-## Basic Setup
-
-Create a DrizzleAdapter with your Drizzle database instance and provider.
-
-```typescript @fragno-test:basic-setup types-only
-interface MyDatabase extends Record<string, unknown> {
-  users: {
-    id: string;
-    email: string;
-    name: string;
-  };
-  posts: {
-    id: string;
-    title: string;
-    content: string;
-    authorId: string;
-  };
-}
-
-declare const db: NodePgDatabase<MyDatabase>;
-
-export const adapter = new DrizzleAdapter({
-  db,
-  provider: "postgresql",
-});
-```
-
-The adapter requires your Drizzle instance and the database provider (`"postgresql"`, `"mysql"`, or
-`"sqlite"`).
-
-## Factory Function
-
-For async or sync database initialization, pass a factory function instead of a direct instance.
-
-```typescript @fragno-test:factory-function types-only
-import type { PgliteDatabase } from "drizzle-orm/pglite";
-
-async function createDatabase(): Promise<PgliteDatabase> {
-  // Async initialization logic
-  const db = {} as PgliteDatabase;
-  return db;
-}
-
-export const adapter = new DrizzleAdapter({
-  db: createDatabase,
-  provider: "postgresql",
-});
-```
-
-Factory functions can also be synchronous for lazy initialization scenarios.

package/dist/subjects/fragment-instantiation.md

@@ -1,14 +1,13 @@
 # Fragment Instantiation
 
-Fragno provides the `instantiateFragment` function, which uses a builder pattern to help you and
-your user create Fragments.
+Fragno provides the `instantiate` function, which uses a builder pattern to help you and your user
+create Fragments.
 
 ```typescript @fragno-imports
 import {
   defineFragment,
-  createFragment,
-  instantiateFragment,
   defineRoute,
+  instantiate,
   type FragnoPublicConfig,
 } from "@fragno-dev/core";
 import { z } from "zod";
@@ -22,12 +21,12 @@ interface AppConfig {
   apiKey: string;
 }
 
-const fragment = defineFragment<AppConfig>("api-fragment");
+const fragmentDefinition = defineFragment<AppConfig>("api-fragment").build();
 
 // User-facing fragment creator function. This is the main integration point for users of your fragment.
 export function createMyFragment(config: AppConfig, options: FragnoPublicConfig = {}) {
   return (
-    instantiateFragment(fragment)
+    instantiate(fragmentDefinition)
       .withConfig(config)
       /** Options are passed to Fragno internally */
       .withOptions(options)
@@ -38,7 +37,7 @@ export function createMyFragment(config: AppConfig, options: FragnoPublicConfig
 // What your user will call to instantiate the fragment:
 const instance = createMyFragment({ apiKey: "my-secret-key" }, { mountRoute: "/api/v1" });
 
-expect(instance.config.name).toBe("api-fragment");
+expect(instance.name).toBe("api-fragment");
 expect(instance.mountRoute).toBe("/api/v1");
 ```
 
@@ -51,7 +50,7 @@ Also see the `defining-routes` subject.
 
 ```typescript @fragno-test:builder-with-routes
 // should add routes using withRoutes
-const fragment = defineFragment<{}>("routes-fragment");
+const fragmentDefinition = defineFragment("routes-fragment").build();
 
 const route1 = defineRoute({
   method: "GET",
@@ -67,11 +66,14 @@ const route2 = defineRoute({
   handler: async (_, { json }) => json("Goodbye"),
 });
 
-const instance = instantiateFragment(fragment).withConfig({}).withRoutes([route1, route2]).build();
+const instance = instantiate(fragmentDefinition)
+  .withRoutes([route1, route2])
+  .withOptions({})
+  .build();
 
-expect(instance.config.routes).toHaveLength(2);
-expect(instance.config.routes[0].path).toBe("/hello");
-expect(instance.config.routes[1].path).toBe("/goodbye");
+expect(instance.routes).toHaveLength(2);
+expect(instance.routes[0].path).toBe("/hello");
+expect(instance.routes[1].path).toBe("/goodbye");
 ```
 
 Routes can be added as an array using `withRoutes`.
@@ -94,19 +96,20 @@ const fragment = defineFragment<AppConfig>("service-fragment")
   .withDependencies(({ config }) => ({
     client: { key: config.apiKey },
   }))
-  .usesService<"logger", ILogger>("logger");
+  .usesService<"logger", ILogger>("logger")
+  .build();
 
 const loggerImpl: ILogger = {
   log: (msg) => console.log(msg),
 };
 
-const instance = instantiateFragment(fragment)
+const instance = instantiate(fragment)
   .withConfig({ apiKey: "my-key" })
   .withServices({ logger: loggerImpl })
+  .withOptions({})
   .build();
 
-expect(instance.deps.client.key).toBe("my-key");
-expect(instance.services.logger).toBeDefined();
+expect(instance.$internal.deps.client.key).toBe("my-key");
 ```
 
 Use `withDependencies` to create dependencies from config, and `withServices` to provide required

package/dist/subjects/fragment-services.md

@@ -7,8 +7,7 @@ Note that if the goal is to make your user provide certain functionality, it usu
 sense to add a required property to the fragment's config.
 
 ```typescript @fragno-imports
-import { defineFragment, instantiateFragment } from "@fragno-dev/core";
-import type { FragnoPublicConfig } from "@fragno-dev/core";
+import { defineFragment, instantiate, type FragnoPublicConfig } from "@fragno-dev/core";
 ```
 
 ## Providing Services
@@ -17,23 +16,27 @@ Fragments provide services using `providesService()`. Services can be passed as
 via a factory function that receives context (`config`, `deps`, `fragnoConfig`, `defineService`).
 
 ```typescript @fragno-test:provide-direct-object
-// Object syntax is the simplest way to provide services.
-const fragment = defineFragment<{}>("email-fragment").providesService({
-  sendEmail: async (to: string, subject: string) => {
-    // Email sending logic here
-  },
-});
+// Object syntax is the simplest way to provide base services.
+const fragmentDefinition = defineFragment("email-fragment")
+  .providesBaseService(() => ({
+    sendEmail: async (to: string, subject: string) => {
+      // Email sending logic here
+    },
+  }))
+  .build();
 ```
 
 ```typescript @fragno-test:provide-factory-function
 // The factory function receives the fragment's `config`, and `deps` (dependencies).
-const fragment = defineFragment<{}>("api-fragment").providesService(({ config }) => ({
-  makeRequest: async (endpoint: string) => {
-    return { data: "response" };
-  },
-}));
+const fragmentDefinition = defineFragment("api-fragment")
+  .providesBaseService(({ config }) => ({
+    makeRequest: async (endpoint: string) => {
+      return { data: "response" };
+    },
+  }))
+  .build();
 
-const instance = instantiateFragment(fragment).withConfig({}).build();
+const instance = instantiate(fragmentDefinition).withOptions({}).build();
 expect(instance.services.makeRequest).toBeInstanceOf(Function);
 ```
 
@@ -45,16 +48,14 @@ required services.
 
 ```typescript @fragno-test:provide-named-services
 // should provide named services
-const fragment = defineFragment<{}>("logger-fragment").providesService(
-  "logger",
-  ({ defineService }) =>
-    defineService({
-      log: (message: string) => console.log(message),
-      error: (message: string) => console.error(message),
-    }),
-);
+const fragmentDefinition = defineFragment("logger-fragment")
+  .providesService("logger", () => ({
+    log: (message: string) => console.log(message),
+    error: (message: string) => console.error(message),
+  }))
+  .build();
 
-const instance = instantiateFragment(fragment).withConfig({}).build();
+const instance = instantiate(fragmentDefinition).withOptions({}).build();
 expect(instance.services.logger.log).toBeDefined();
 expect(instance.services.logger.error).toBeDefined();
 ```
@@ -66,7 +67,7 @@ for database fragments where methods need access to the current unit of work.
 
 ```typescript @fragno-test:chaining-services
 // should chain multiple service definitions
-const fragment = defineFragment<{}>("multi-service-fragment")
+const fragmentDefinition = defineFragment("multi-service-fragment")
   .providesService("logger", ({ defineService }) =>
     defineService({
       log: (msg: string) => console.log(msg),
@@ -76,13 +77,14 @@ const fragment = defineFragment<{}>("multi-service-fragment")
     defineService({
       validate: (input: string) => input.length > 0,
     }),
-  );
+  )
+  .build();
 ```
 
 ## Using Services
 
-Fragments specify required services using `usesService`. Services can be marked as optional with
-`{ optional: true }`, making them `undefined` if not provided.
+Fragments specify required services using `usesService`. Services can be marked as optional using
+`usesOptionalService`, making them `undefined` if not provided.
 
 ```typescript @fragno-test:declaring-required-service
 // should require a service from the user
@@ -90,9 +92,13 @@ interface IEmailService {
   sendEmail(to: string, subject: string, body: string): Promise<void>;
 }
 
-const fragment = defineFragment<{}>("notification-fragment").usesService<"email", IEmailService>(
-  "email",
-);
+const fragmentDefinition = defineFragment("notification-fragment")
+  .usesService<"email", IEmailService>("email")
+  .providesBaseService(({ serviceDeps }) => ({
+    sendNotification: (to: string, subject: string, body: string) =>
+      serviceDeps.email.sendEmail(to, subject, body),
+  }))
+  .build();
 
 const emailImpl: IEmailService = {
   sendEmail: async (to, subject, body) => {
@@ -100,13 +106,12 @@ const emailImpl: IEmailService = {
   },
 };
 
-const instance = instantiateFragment(fragment)
-  .withConfig({})
+const instance = instantiate(fragmentDefinition)
   .withServices({ email: emailImpl })
+  .withOptions({})
   .build();
 
-expect(instance.services.email).toBeDefined();
-expect(instance.services.email.sendEmail).toBeDefined();
+expect(instance.services.sendNotification).toBeDefined();
 ```
 
 ### Optional Services
@@ -117,21 +122,27 @@ interface ILogger {
   log(message: string): void;
 }
 
-const fragment = defineFragment<{}>("app-fragment").usesService<"logger", ILogger>("logger", {
-  optional: true,
-});
+const fragmentDefinition = defineFragment("app-fragment")
+  .usesOptionalService<"logger", ILogger>("logger")
+  .providesBaseService(({ serviceDeps }) => ({
+    maybeLog: (message: string) => {
+      if (serviceDeps.logger) {
+        serviceDeps.logger.log(message);
+      }
+    },
+  }))
+  .build();
 
 // Can instantiate without providing the service
-const instance = instantiateFragment(fragment).withConfig({}).build();
+const instance = instantiate(fragmentDefinition).withOptions({}).build();
 
 expect(instance).toBeDefined();
-// logger will be undefined
-expect(instance.services.logger).toBeUndefined();
+expect(instance.services.maybeLog).toBeDefined();
 ```
 
 ### Using Services in Provided Services
 
-Used services are available via `deps` in the factory function context, enabling composition.
+Used services are available via `serviceDeps` in the factory function context, enabling composition.
 
 ```typescript @fragno-test:using-in-provided
 // should use external services in provided services
@@ -139,25 +150,25 @@ interface IEmailService {
   sendEmail(to: string, subject: string, body: string): Promise<void>;
 }
 
-const fragment = defineFragment<{}>("welcome-fragment")
+const fragmentDefinition = defineFragment("welcome-fragment")
   .usesService<"email", IEmailService>("email")
-  .providesService(({ deps }) => ({
+  .providesBaseService(({ serviceDeps }) => ({
     sendWelcomeEmail: async (to: string) => {
-      await deps.email.sendEmail(to, "Welcome!", "Welcome to our service!");
+      await serviceDeps.email.sendEmail(to, "Welcome!", "Welcome to our service!");
     },
-  }));
+  }))
+  .build();
 
 const emailImpl: IEmailService = {
   sendEmail: async () => {},
 };
 
-const instance = instantiateFragment(fragment)
-  .withConfig({})
+const instance = instantiate(fragmentDefinition)
   .withServices({ email: emailImpl })
+  .withOptions({})
   .build();
 
 expect(instance.services.sendWelcomeEmail).toBeDefined();
-expect(instance.services.email).toBeDefined();
 ```
 
 ### Missing Required Services
@@ -168,11 +179,11 @@ interface IStorageService {
   save(key: string, value: string): Promise<void>;
 }
 
-const fragment = defineFragment<{}>("storage-fragment").usesService<"storage", IStorageService>(
-  "storage",
-);
+const fragmentDefinition = defineFragment("storage-fragment")
+  .usesService<"storage", IStorageService>("storage")
+  .build();
 
 expect(() => {
-  instantiateFragment(fragment).withConfig({}).build();
+  instantiate(fragmentDefinition).withOptions({}).build();
 }).toThrow("Fragment 'storage-fragment' requires service 'storage' but it was not provided");
 ```

package/dist/subjects/kysely-adapter.md

@@ -4,56 +4,54 @@ The KyselyAdapter connects Fragno's database API to your Kysely database instanc
 
 ```typescript @fragno-imports
 import { KyselyAdapter } from "@fragno-dev/db/adapters/kysely";
-import { Kysely } from "kysely";
-import type { Dialect } from "kysely";
+import {
+  PGLiteDriverConfig,
+  SQLocalDriverConfig,
+  BetterSQLite3DriverConfig,
+} from "@fragno-dev/db/drivers";
+import { SqliteDialect, PostgresDialect, MysqlDialect } from "@fragno-dev/db/dialects";
+import type { Dialect } from "@fragno-dev/db/sql-driver";
+import SQLite from "better-sqlite3";
+import { KyselyPGlite } from "kysely-pglite";
 ```
 
 ## Basic Setup
 
-Create a KyselyAdapter with your Kysely database instance and provider.
+Create a KyselyAdapter with your Kysely dialect and driver configuration.
 
 ```typescript @fragno-test:basic-setup types-only
-interface MyDatabase {
-  users: {
-    id: string;
-    email: string;
-    name: string;
-  };
-  posts: {
-    id: string;
-    title: string;
-    content: string;
-    authorId: string;
-  };
-}
-
-declare const dialect: Dialect;
-
-export const db = new Kysely<MyDatabase>({
-  dialect,
+const dialect = new SqliteDialect({
+  database: new SQLite(":memory:"),
 });
 
 export const adapter = new KyselyAdapter({
-  db,
-  provider: "postgresql",
+  dialect,
+  driverConfig: new BetterSQLite3DriverConfig(),
 });
 ```
 
-The adapter requires your Kysely instance and the database provider (`"postgresql"`, `"mysql"`, or
-`"sqlite"`).
+The adapter requires:
 
-## Factory Function
+- `dialect`: A Kysely dialect instance for your database
+- `driverConfig`: A driver configuration matching your database type (`PGLiteDriverConfig`,
+  `SQLocalDriverConfig`, or `BetterSQLite3DriverConfig`)
 
-For async database initialization, pass a factory function instead of a direct instance.
+## First Party Kysely Dialects
 
-```typescript @fragno-test:factory-function types-only
-async function createDatabase() {
-  // Async initialization logic
-  return new Kysely({ dialect: {} as Dialect });
-}
+Fragno re-exports the "first party" Kysely dialects for SQLite, PostgreSQL, and MySQL. This means
+you can use these dialects without installing them yourself.
+
+```typescript @fragno-test:first-party-kysely-dialects types-only
+import { SqliteDialect, PostgresDialect, MysqlDialect } from "@fragno-dev/db/dialects";
+```
+
+## PGLite Example
+
+```typescript @fragno-test:postgresql-example types-only
+const { dialect } = await KyselyPGlite.create();
 
 export const adapter = new KyselyAdapter({
-  db: createDatabase,
-  provider: "postgresql",
+  dialect,
+  driverConfig: new PGLiteDriverConfig(),
 });
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fragno-dev/corpus",
-  "version": "0.0.5",
+  "version": "0.0.7",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -16,14 +16,17 @@
     "dist"
   ],
   "devDependencies": {
+    "@types/better-sqlite3": "^7.6.13",
     "@types/marked-terminal": "^6.1.1",
     "@types/node": "^22",
+    "better-sqlite3": "^12.5.0",
     "drizzle-orm": "^0.44.7",
     "kysely": "^0.28.0",
+    "kysely-pglite": "^0.6.1",
     "zod": "^4.0.5",
-    "@fragno-dev/core": "0.1.8",
-    "@fragno-dev/db": "0.1.14",
-    "@fragno-dev/test": "0.1.12",
+    "@fragno-dev/core": "0.1.11",
+    "@fragno-dev/db": "0.2.0",
+    "@fragno-dev/test": "1.0.0",
     "@fragno-private/typescript-config": "0.0.1",
     "@fragno-private/vitest-config": "0.0.0"
   },