@fragno-dev/corpus 0.0.3 → 0.0.5

package/dist/subjects/defining-routes.md

@@ -0,0 +1,272 @@
+# 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 { defineRoute, defineRoutes, defineFragment, createFragment } from "@fragno-dev/core";
+import 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;
+}
+
+interface AppDeps {
+  config: AppConfig;
+  timestamp: number;
+}
+
+export const routesWithDeps = defineRoutes<AppConfig, AppDeps>().create(({ deps }) => {
+  return [
+    defineRoute({
+      method: "GET",
+      path: "/config-info",
+      outputSchema: z.object({
+        hasApiKey: z.boolean(),
+        timestamp: z.number(),
+      }),
+      handler: async (_, { json }) => {
+        return json({
+          hasApiKey: !!deps.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
+interface DataService {
+  getData: () => string;
+  processData: (input: string) => Promise<string>;
+}
+
+export const routesWithServices = defineRoutes<{}, {}, DataService>().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.
+
+## 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

@@ -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,113 @@
+# Fragment Instantiation
+
+Fragno provides the `instantiateFragment` function, which uses a builder pattern to help you and
+your user create Fragments.
+
+```typescript @fragno-imports
+import {
+  defineFragment,
+  createFragment,
+  instantiateFragment,
+  defineRoute,
+  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 fragment = defineFragment<AppConfig>("api-fragment");
+
+// 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)
+      .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.config.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 fragment = defineFragment<{}>("routes-fragment");
+
+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 = instantiateFragment(fragment).withConfig({}).withRoutes([route1, route2]).build();
+
+expect(instance.config.routes).toHaveLength(2);
+expect(instance.config.routes[0].path).toBe("/hello");
+expect(instance.config.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");
+
+const loggerImpl: ILogger = {
+  log: (msg) => console.log(msg),
+};
+
+const instance = instantiateFragment(fragment)
+  .withConfig({ apiKey: "my-key" })
+  .withServices({ logger: loggerImpl })
+  .build();
+
+expect(instance.deps.client.key).toBe("my-key");
+expect(instance.services.logger).toBeDefined();
+```
+
+Use `withDependencies` to create dependencies from config, and `withServices` to provide required
+services.

package/dist/subjects/fragment-services.md

@@ -0,0 +1,178 @@
+# 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, instantiateFragment } from "@fragno-dev/core";
+import 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 services.
+const fragment = defineFragment<{}>("email-fragment").providesService({
+  sendEmail: async (to: string, subject: string) => {
+    // Email sending logic here
+  },
+});
+```
+
+```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 instance = instantiateFragment(fragment).withConfig({}).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 fragment = defineFragment<{}>("logger-fragment").providesService(
+  "logger",
+  ({ defineService }) =>
+    defineService({
+      log: (message: string) => console.log(message),
+      error: (message: string) => console.error(message),
+    }),
+);
+
+const instance = instantiateFragment(fragment).withConfig({}).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 fragment = defineFragment<{}>("multi-service-fragment")
+  .providesService("logger", ({ defineService }) =>
+    defineService({
+      log: (msg: string) => console.log(msg),
+    }),
+  )
+  .providesService("validator", ({ defineService }) =>
+    defineService({
+      validate: (input: string) => input.length > 0,
+    }),
+  );
+```
+
+## Using Services
+
+Fragments specify required services using `usesService`. Services can be marked as optional with
+`{ optional: true }`, 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 fragment = defineFragment<{}>("notification-fragment").usesService<"email", IEmailService>(
+  "email",
+);
+
+const emailImpl: IEmailService = {
+  sendEmail: async (to, subject, body) => {
+    // Implementation
+  },
+};
+
+const instance = instantiateFragment(fragment)
+  .withConfig({})
+  .withServices({ email: emailImpl })
+  .build();
+
+expect(instance.services.email).toBeDefined();
+expect(instance.services.email.sendEmail).toBeDefined();
+```
+
+### Optional Services
+
+```typescript @fragno-test:optional-service
+// should mark a service as optional
+interface ILogger {
+  log(message: string): void;
+}
+
+const fragment = defineFragment<{}>("app-fragment").usesService<"logger", ILogger>("logger", {
+  optional: true,
+});
+
+// Can instantiate without providing the service
+const instance = instantiateFragment(fragment).withConfig({}).build();
+
+expect(instance).toBeDefined();
+// logger will be undefined
+expect(instance.services.logger).toBeUndefined();
+```
+
+### Using Services in Provided Services
+
+Used services are available via `deps` 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 fragment = defineFragment<{}>("welcome-fragment")
+  .usesService<"email", IEmailService>("email")
+  .providesService(({ deps }) => ({
+    sendWelcomeEmail: async (to: string) => {
+      await deps.email.sendEmail(to, "Welcome!", "Welcome to our service!");
+    },
+  }));
+
+const emailImpl: IEmailService = {
+  sendEmail: async () => {},
+};
+
+const instance = instantiateFragment(fragment)
+  .withConfig({})
+  .withServices({ email: emailImpl })
+  .build();
+
+expect(instance.services.sendWelcomeEmail).toBeDefined();
+expect(instance.services.email).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 fragment = defineFragment<{}>("storage-fragment").usesService<"storage", IStorageService>(
+  "storage",
+);
+
+expect(() => {
+  instantiateFragment(fragment).withConfig({}).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.3",
+  "version": "0.0.5",
   "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.6",
-    "@fragno-dev/db": "0.1.13",
-    "@fragno-dev/test": "0.1.10",
+    "@fragno-dev/core": "0.1.8",
+    "@fragno-dev/db": "0.1.14",
+    "@fragno-dev/test": "0.1.12",
     "@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",