@fragno-dev/corpus 0.0.2 → 0.0.4

package/src/subjects/defining-routes.md

@@ -1,272 +0,0 @@
-# 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: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: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:route
-// 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:route
-// 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
-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 `withServices` can be used in routes for business logic.
-
-```typescript
-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
-interface MyFragmentConfig {
-  apiKey: string;
-}
-
-interface MyFragmentDeps {
-  config: MyFragmentConfig;
-}
-
-interface MyFragmentServices {
-  getStatus: () => string;
-}
-
-const myFragmentDefinition = defineFragment<MyFragmentConfig>("my-fragment")
-  .withDependencies(({ config }) => {
-    return {
-      config,
-    };
-  })
-  .withServices(({ deps }) => {
-    return {
-      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/src/subjects/drizzle-adapter.md

@@ -1,60 +0,0 @@
-# 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 { drizzle } from "drizzle-orm/node-postgres";
-import type { NodePgDatabase } from "drizzle-orm/node-postgres";
-```
-
-## Basic Setup
-
-Create a DrizzleAdapter with your Drizzle database instance and provider.
-
-```typescript
-interface MyDatabase {
-  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
-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/src/subjects/kysely-adapter.md

@@ -1,59 +0,0 @@
-# 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
-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
-async function createDatabase() {
-  // Async initialization logic
-  return new Kysely({ dialect: {} as Dialect });
-}
-
-export const adapter = new KyselyAdapter({
-  db: createDatabase,
-  provider: "postgresql",
-});
-```

package/src/test-setup.ts

@@ -1,110 +0,0 @@
-import { writeFileSync, mkdirSync } from "node:fs";
-import { join, dirname } from "node:path";
-import { fileURLToPath } from "node:url";
-import { loadAllSubjects } from "./parser";
-
-const __dirname = fileURLToPath(new URL(".", import.meta.url));
-const TEMP_TEST_DIR = join(__dirname, "../.corpus-tests");
-
-/**
- * Global setup for vitest that parses all markdown files
- * and generates temporary test files from @fragno-test blocks
- */
-export async function setup() {
-  // Create temp directory (if it doesn't exist)
-  mkdirSync(TEMP_TEST_DIR, { recursive: true });
-
-  try {
-    // Load all subjects
-    const subjects = loadAllSubjects();
-
-    // Generate test files for each subject
-    for (const subject of subjects) {
-      // Skip test generation if examples contain declare statements (documentation only)
-      const allCode = subject.examples.map((example) => example.code).join("\n");
-      if (allCode.includes("declare ")) {
-        console.log(`⊘ Skipped ${subject.id} (contains declare statements - documentation only)`);
-        continue;
-      }
-
-      // Separate examples by test type
-      const routeTests = subject.examples.filter((ex) => ex.testType === "route");
-      const databaseTests = subject.examples.filter((ex) => ex.testType === "database");
-
-      // Skip if no actual tests
-      if (routeTests.length === 0 && databaseTests.length === 0) {
-        console.log(`⊘ Skipped ${subject.id} (no test directives found)`);
-        continue;
-      }
-
-      const testFileName = `${subject.id}.generated.test.ts`;
-      const testFilePath = join(TEMP_TEST_DIR, testFileName);
-
-      // Generate test file content
-      let testFileContent = `/* eslint-disable */
-// Auto-generated test file for subject: ${subject.title}
-// DO NOT EDIT - This file is generated by test-setup.ts
-
-import { describe, it, expect } from "vitest";
-${subject.imports}
-
-${subject.init ? `${subject.init}\n` : ""}
-`;
-
-      // Generate route tests
-      if (routeTests.length > 0) {
-        testFileContent += `\ndescribe("${subject.id} - route tests", () => {\n`;
-
-        for (let i = 0; i < routeTests.length; i++) {
-          const example = routeTests[i];
-          const testName = example.testName || `route test ${i + 1}`;
-
-          testFileContent += `  it("${testName}", () => {\n`;
-          // Indent the code
-          const indentedCode = example.code
-            .split("\n")
-            .map((line) => `    ${line}`)
-            .join("\n");
-          testFileContent += `${indentedCode}\n`;
-          testFileContent += `  });\n\n`;
-        }
-
-        testFileContent += `});\n`;
-      }
-
-      // Generate database tests
-      if (databaseTests.length > 0) {
-        testFileContent += `\ndescribe("${subject.id} - database tests", () => {\n`;
-
-        for (let i = 0; i < databaseTests.length; i++) {
-          const example = databaseTests[i];
-          const testName = example.testName || `database test ${i + 1}`;
-
-          testFileContent += `  it("${testName}", async () => {\n`;
-          // Indent the code
-          const indentedCode = example.code
-            .split("\n")
-            .map((line) => `    ${line}`)
-            .join("\n");
-          testFileContent += `${indentedCode}\n`;
-          testFileContent += `  });\n\n`;
-        }
-
-        testFileContent += `});\n`;
-      }
-
-      // Ensure directory exists
-      mkdirSync(dirname(testFilePath), { recursive: true });
-
-      // Write test file
-      writeFileSync(testFilePath, testFileContent, "utf-8");
-    }
-
-    console.log(`✓ Generated ${subjects.length} test file(s) in ${TEMP_TEST_DIR}`);
-  } catch (error) {
-    if (error instanceof Error) {
-      console.error("Error generating test files:", error.message);
-    }
-    // Don't throw - allow tests to continue even if generation fails
-  }
-}

package/tsconfig.json

@@ -1,10 +0,0 @@
-{
-  "extends": "@fragno-private/typescript-config/tsconfig.base.json",
-  "compilerOptions": {
-    "outDir": "./dist",
-    "rootDir": ".",
-    "composite": true
-  },
-  "include": ["src"],
-  "exclude": ["node_modules", "dist"]
-}

package/tsdown.config.ts

@@ -1,7 +0,0 @@
-import { defineConfig } from "tsdown";
-
-export default defineConfig({
-  entry: "./src/index.ts",
-  dts: true,
-  outDir: "./dist",
-});

package/vitest.config.ts

@@ -1,13 +0,0 @@
-import { defineConfig, mergeConfig } from "vitest/config";
-import { baseConfig } from "@fragno-private/vitest-config";
-
-export default defineConfig(
-  mergeConfig(baseConfig, {
-    test: {
-      globalSetup: "./src/test-setup.ts",
-      coverage: {
-        enabled: false,
-      },
-    },
-  }),
-);