@fragno-dev/corpus 0.0.4 → 0.0.6

package/dist/subjects/defining-routes.md

@@ -0,0 +1,229 @@
+# Defining Routes
+
+Routes are the core of a Fragno fragment, defining HTTP endpoints that handle requests and return
+responses. This guide covers the essential patterns for defining routes.
+
+```typescript @fragno-imports
+import {
+  defineFragment,
+  defineRoute,
+  defineRoutes,
+  instantiate,
+  type FragnoPublicConfig,
+} from "@fragno-dev/core";
+import { z } from "zod";
+```
+
+## Basic GET Route
+
+A simple GET route with an output schema.
+
+```typescript @fragno-test:basic-get-route
+// should define a basic GET route
+const basicGetRoute = defineRoute({
+  method: "GET",
+  path: "/hello",
+  outputSchema: z.string(),
+  handler: async (_, { json }) => {
+    return json("Hello, World!");
+  },
+});
+
+expect(basicGetRoute.method).toBe("GET");
+expect(basicGetRoute.path).toBe("/hello");
+```
+
+The `outputSchema` uses Zod (or any Standard Schema compatible library) to define the response type.
+The handler receives a context object and helpers like `json()` for sending responses.
+
+## POST Route with Input Schema
+
+Routes can accept and validate request bodies using `inputSchema`.
+
+```typescript @fragno-test:post-route
+// should define a POST route with input schema
+const createItemRoute = defineRoute({
+  method: "POST",
+  path: "/items",
+  inputSchema: z.object({
+    name: z.string(),
+    description: z.string().optional(),
+  }),
+  outputSchema: z.object({
+    id: z.string(),
+    name: z.string(),
+    description: z.string().optional(),
+  }),
+  handler: async ({ input }, { json }) => {
+    const data = await input.valid();
+
+    return json({
+      id: "item-123",
+      name: data.name,
+      description: data.description,
+    });
+  },
+});
+
+expect(createItemRoute.method).toBe("POST");
+expect(createItemRoute.inputSchema).toBeDefined();
+```
+
+The `input.valid()` method validates the request body against the schema and returns the typed data.
+
+## Query Parameters
+
+Routes can declare query parameters they expect to receive.
+
+```typescript @fragno-test:query-parameters
+// should define a route with query parameters
+const listItemsRoute = defineRoute({
+  method: "GET",
+  path: "/items",
+  queryParameters: ["page", "limit", "filter"],
+  outputSchema: z.array(
+    z.object({
+      id: z.string(),
+      name: z.string(),
+    }),
+  ),
+  handler: async ({ query }, { json }) => {
+    const page = query.get("page") || "1";
+    const limit = query.get("limit") || "10";
+    const filter = query.get("filter");
+
+    return json([
+      { id: "1", name: "Item 1" },
+      { id: "2", name: "Item 2" },
+    ]);
+  },
+});
+
+expect(listItemsRoute.queryParameters).toEqual(["page", "limit", "filter"]);
+```
+
+Query parameters are accessed via `query.get(name)` from the context.
+
+## Error Handling
+
+Routes can define custom error codes and return errors with appropriate status codes.
+
+```typescript @fragno-test:error-handling
+// should define a route with error codes
+const validateItemRoute = defineRoute({
+  method: "POST",
+  path: "/validate",
+  inputSchema: z.object({
+    value: z.string(),
+  }),
+  outputSchema: z.object({ valid: z.boolean() }),
+  errorCodes: ["INVALID_VALUE", "VALUE_TOO_SHORT"],
+  handler: async ({ input }, { json, error }) => {
+    const data = await input.valid();
+
+    if (data.value.length < 3) {
+      return error(
+        {
+          message: "Value must be at least 3 characters",
+          code: "VALUE_TOO_SHORT",
+        },
+        400,
+      );
+    }
+
+    if (!/^[a-z]+$/.test(data.value)) {
+      return error(
+        {
+          message: "Value must contain only lowercase letters",
+          code: "INVALID_VALUE",
+        },
+        400,
+      );
+    }
+
+    return json({ valid: true });
+  },
+});
+
+expect(validateItemRoute.errorCodes).toEqual(["INVALID_VALUE", "VALUE_TOO_SHORT"]);
+```
+
+The `error()` helper sends an error response with a custom error code and HTTP status.
+
+## Using Dependencies
+
+Routes can access dependencies defined in `withDependencies` through route factories.
+
+```typescript @fragno-test:using-dependencies
+interface AppConfig {
+  apiKey?: string;
+}
+
+const definition = defineFragment<AppConfig>("test")
+  .withDependencies(({ config }) => ({ timestamp: Date.now() }))
+  .build();
+
+export const routesWithDeps = defineRoutes<typeof definition>().create(({ config, deps }) => {
+  return [
+    defineRoute({
+      method: "GET",
+      path: "/config-info",
+      outputSchema: z.object({
+        hasApiKey: z.boolean(),
+        timestamp: z.number(),
+      }),
+      handler: async (_, { json }) => {
+        return json({
+          hasApiKey: !!config.apiKey,
+          timestamp: deps.timestamp,
+        });
+      },
+    }),
+  ];
+});
+```
+
+Dependencies are passed to the route factory function and can be used in route handlers.
+
+## Using Services
+
+Services defined in `providesService` can be used in routes for business logic.
+
+```typescript @fragno-test:using-services
+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<typeof definition>().create(({ services }) => {
+  return [
+    defineRoute({
+      method: "GET",
+      path: "/data",
+      outputSchema: z.string(),
+      handler: async (_, { json }) => {
+        const data = services.getData();
+        return json(data);
+      },
+    }),
+    defineRoute({
+      method: "POST",
+      path: "/process",
+      inputSchema: z.object({ input: z.string() }),
+      outputSchema: z.string(),
+      handler: async ({ input }, { json }) => {
+        const { input: inputData } = await input.valid();
+        const result = await services.processData(inputData);
+        return json(result);
+      },
+    }),
+  ];
+});
+```
+
+Services provide reusable business logic that can be shared across multiple routes.

package/dist/subjects/drizzle-adapter.md

@@ -0,0 +1,60 @@
+# Drizzle Adapter
+
+The DrizzleAdapter connects Fragno's database API to your Drizzle ORM instance.
+
+```typescript @fragno-imports
+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

@@ -0,0 +1,116 @@
+# Fragment Instantiation
+
+Fragno provides the `instantiate` function, which uses a builder pattern to help you and your user
+create Fragments.
+
+```typescript @fragno-imports
+import {
+  defineFragment,
+  defineRoute,
+  instantiate,
+  type FragnoPublicConfig,
+} from "@fragno-dev/core";
+import { z } from "zod";
+```
+
+## Basic Usage
+
+```typescript @fragno-test:builder-basic
+/** Fragment specific config */
+interface AppConfig {
+  apiKey: string;
+}
+
+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 (
+    instantiate(fragmentDefinition)
+      .withConfig(config)
+      /** Options are passed to Fragno internally */
+      .withOptions(options)
+      .build()
+  );
+}
+
+// What your user will call to instantiate the fragment:
+const instance = createMyFragment({ apiKey: "my-secret-key" }, { mountRoute: "/api/v1" });
+
+expect(instance.name).toBe("api-fragment");
+expect(instance.mountRoute).toBe("/api/v1");
+```
+
+Use `withConfig` to provide the fragment's configuration and `withOptions` to set options like
+`mountRoute`.
+
+### Builder with Routes
+
+Also see the `defining-routes` subject.
+
+```typescript @fragno-test:builder-with-routes
+// should add routes using withRoutes
+const fragmentDefinition = defineFragment("routes-fragment").build();
+
+const route1 = defineRoute({
+  method: "GET",
+  path: "/hello",
+  outputSchema: z.string(),
+  handler: async (_, { json }) => json("Hello"),
+});
+
+const route2 = defineRoute({
+  method: "GET",
+  path: "/goodbye",
+  outputSchema: z.string(),
+  handler: async (_, { json }) => json("Goodbye"),
+});
+
+const instance = instantiate(fragmentDefinition)
+  .withRoutes([route1, route2])
+  .withOptions({})
+  .build();
+
+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`.
+
+### Builder with Services and Dependencies
+
+Also see the `fragment-services` subject.
+
+```typescript @fragno-test:builder-with-services
+// should provide services and dependencies
+interface AppConfig {
+  apiKey: string;
+}
+
+interface ILogger {
+  log(message: string): void;
+}
+
+const fragment = defineFragment<AppConfig>("service-fragment")
+  .withDependencies(({ config }) => ({
+    client: { key: config.apiKey },
+  }))
+  .usesService<"logger", ILogger>("logger")
+  .build();
+
+const loggerImpl: ILogger = {
+  log: (msg) => console.log(msg),
+};
+
+const instance = instantiate(fragment)
+  .withConfig({ apiKey: "my-key" })
+  .withServices({ logger: loggerImpl })
+  .withOptions({})
+  .build();
+
+expect(instance.$internal.deps.client.key).toBe("my-key");
+```
+
+Use `withDependencies` to create dependencies from config, and `withServices` to provide required
+services.

package/dist/subjects/fragment-services.md

@@ -0,0 +1,189 @@
+# Fragment Services
+
+Services in Fragno provide a way to define reusable business logic and expose functionality to users
+of your Fragment. Services are also used to share logic between several Fragments.
+
+Note that if the goal is to make your user provide certain functionality, it usually makes more
+sense to add a required property to the fragment's config.
+
+```typescript @fragno-imports
+import { defineFragment, instantiate, type FragnoPublicConfig } from "@fragno-dev/core";
+```
+
+## Providing Services
+
+Fragments provide services using `providesService()`. Services can be passed as a direct object or
+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 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 fragmentDefinition = defineFragment("api-fragment")
+  .providesBaseService(({ config }) => ({
+    makeRequest: async (endpoint: string) => {
+      return { data: "response" };
+    },
+  }))
+  .build();
+
+const instance = instantiate(fragmentDefinition).withOptions({}).build();
+expect(instance.services.makeRequest).toBeInstanceOf(Function);
+```
+
+### Named vs Unnamed Services
+
+Unnamed services (shown above) are exposed directly on `instance.services` for direct user
+consumption. Named services provide better organization and enable fragments to work together via
+required services.
+
+```typescript @fragno-test:provide-named-services
+// should provide named services
+const fragmentDefinition = defineFragment("logger-fragment")
+  .providesService("logger", () => ({
+    log: (message: string) => console.log(message),
+    error: (message: string) => console.error(message),
+  }))
+  .build();
+
+const instance = instantiate(fragmentDefinition).withOptions({}).build();
+expect(instance.services.logger.log).toBeDefined();
+expect(instance.services.logger.error).toBeDefined();
+```
+
+### Using `defineService` helper method
+
+Use `defineService` when service methods need proper `this` binding. This is particularly important
+for database fragments where methods need access to the current unit of work.
+
+```typescript @fragno-test:chaining-services
+// should chain multiple service definitions
+const fragmentDefinition = defineFragment("multi-service-fragment")
+  .providesService("logger", ({ defineService }) =>
+    defineService({
+      log: (msg: string) => console.log(msg),
+    }),
+  )
+  .providesService("validator", ({ defineService }) =>
+    defineService({
+      validate: (input: string) => input.length > 0,
+    }),
+  )
+  .build();
+```
+
+## Using Services
+
+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
+interface IEmailService {
+  sendEmail(to: string, subject: string, body: string): Promise<void>;
+}
+
+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) => {
+    // Implementation
+  },
+};
+
+const instance = instantiate(fragmentDefinition)
+  .withServices({ email: emailImpl })
+  .withOptions({})
+  .build();
+
+expect(instance.services.sendNotification).toBeDefined();
+```
+
+### Optional Services
+
+```typescript @fragno-test:optional-service
+// should mark a service as optional
+interface ILogger {
+  log(message: string): void;
+}
+
+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 = instantiate(fragmentDefinition).withOptions({}).build();
+
+expect(instance).toBeDefined();
+expect(instance.services.maybeLog).toBeDefined();
+```
+
+### Using Services in Provided Services
+
+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
+interface IEmailService {
+  sendEmail(to: string, subject: string, body: string): Promise<void>;
+}
+
+const fragmentDefinition = defineFragment("welcome-fragment")
+  .usesService<"email", IEmailService>("email")
+  .providesBaseService(({ serviceDeps }) => ({
+    sendWelcomeEmail: async (to: string) => {
+      await serviceDeps.email.sendEmail(to, "Welcome!", "Welcome to our service!");
+    },
+  }))
+  .build();
+
+const emailImpl: IEmailService = {
+  sendEmail: async () => {},
+};
+
+const instance = instantiate(fragmentDefinition)
+  .withServices({ email: emailImpl })
+  .withOptions({})
+  .build();
+
+expect(instance.services.sendWelcomeEmail).toBeDefined();
+```
+
+### Missing Required Services
+
+```typescript @fragno-test:missing-required-service
+// should throw when required service not provided
+interface IStorageService {
+  save(key: string, value: string): Promise<void>;
+}
+
+const fragmentDefinition = defineFragment("storage-fragment")
+  .usesService<"storage", IStorageService>("storage")
+  .build();
+
+expect(() => {
+  instantiate(fragmentDefinition).withOptions({}).build();
+}).toThrow("Fragment 'storage-fragment' requires service 'storage' but it was not provided");
+```

package/dist/subjects/kysely-adapter.md

@@ -0,0 +1,59 @@
+# Kysely Adapter
+
+The KyselyAdapter connects Fragno's database API to your Kysely database instance.
+
+```typescript @fragno-imports
+import { KyselyAdapter } from "@fragno-dev/db/adapters/kysely";
+import { Kysely } from "kysely";
+import type { Dialect } from "kysely";
+```
+
+## Basic Setup
+
+Create a KyselyAdapter with your Kysely database instance and provider.
+
+```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,
+});
+
+export const adapter = new KyselyAdapter({
+  db,
+  provider: "postgresql",
+});
+```
+
+The adapter requires your Kysely instance and the database provider (`"postgresql"`, `"mysql"`, or
+`"sqlite"`).
+
+## Factory Function
+
+For async database initialization, pass a factory function instead of a direct instance.
+
+```typescript @fragno-test:factory-function types-only
+async function createDatabase() {
+  // Async initialization logic
+  return new Kysely({ dialect: {} as Dialect });
+}
+
+export const adapter = new KyselyAdapter({
+  db: createDatabase,
+  provider: "postgresql",
+});
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fragno-dev/corpus",
-  "version": "0.0.4",
+  "version": "0.0.6",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -21,12 +21,19 @@
     "drizzle-orm": "^0.44.7",
     "kysely": "^0.28.0",
     "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.9",
+    "@fragno-dev/db": "0.1.15",
+    "@fragno-dev/test": "0.1.13",
     "@fragno-private/typescript-config": "0.0.1",
     "@fragno-private/vitest-config": "0.0.0"
   },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/rejot-dev/fragno.git",
+    "directory": "packages/corpus"
+  },
+  "homepage": "https://fragno.dev",
+  "license": "MIT",
   "scripts": {
     "build": "tsdown",
     "build:watch": "tsdown --watch",