@ir-kit/kit 0.0.0-stage → 1.0.0

package/docs/k6-toolkit.md

@@ -0,0 +1,62 @@
+# `@ir-kit/kit/k6-toolkit`
+
+Programmatic toolkit for k6 workflows. One library covering the **bundle → run → sync** flow: bundle TypeScript loadtests (tsdown passthrough), spawn the k6 binary, sync the typed client from an OpenAPI spec.
+
+## Install
+
+```sh
+npm install -D @ir-kit/kit
+```
+
+## API
+
+### `bundle(opts)`
+
+Bundles a `.ts` / `.tsx` loadtest into the single ES module k6 expects.
+
+```ts
+import { bundle } from "@ir-kit/kit/k6-toolkit";
+
+await bundle({ entry: "loadtests/smoke.ts", out: ".k6/smoke.js" });
+```
+
+### `runK6(opts)`
+
+Spawns the k6 binary with sensible defaults + structured output.
+
+```ts
+import { runK6 } from "@ir-kit/kit/k6-toolkit";
+
+await runK6({ entry: ".k6/smoke.js", env: { BASE_URL: "https://api.example.com" } });
+```
+
+### `sync(opts)`
+
+Regenerates the typed client from an OpenAPI spec — same logic as the standalone `@ir-kit/kit/sdk/k6` package, surfaced for in-process invocation.
+
+```ts
+import { sync } from "@ir-kit/kit/k6-toolkit";
+
+await sync({ spec: "./openapi.yaml", output: "./src/gen" });
+```
+
+## CLI
+
+The package also ships a `k6-ts` command for shell-driven workflows:
+
+```sh
+k6-ts bundle loadtests/smoke.ts --out .k6/smoke.js
+k6-ts run .k6/smoke.js
+k6-ts sync ./openapi.yaml --output ./src/gen
+k6-ts scaffold --spec ./openapi.yaml --tags pets --output-dir loadtests/
+```
+
+`k6-ts sync` also accepts `-` to read the spec from stdin, so it composes cleanly with [`@ir-kit/kit/recon`](https://github.com/ahmedrowaihi/ir-kit/tree/main/packages/ir-kit/docs/recon.md) (HAR → spec) and similar pipes.
+
+## Status
+
+`0.1.0` — first release under the `@ir-kit/*` scope. Replaces the legacy `@ahmedrowaihi/k6-toolkit` (deprecated).
+
+## Repo
+
+Source at [ahmedrowaihi/ir-kit](https://github.com/ahmedrowaihi/ir-kit/tree/main/packages/ir-kit/docs/k6-toolkit.md).

package/docs/openapi-tools.md

@@ -0,0 +1,19 @@
+# @ir-kit/kit/openapi-tools
+
+OpenAPI helpers for matching requests to routes, merging specs and reading enum and union schemas.
+
+Part of [ir-kit](https://github.com/ahmedrowaihi/ir-kit).
+
+## Install
+
+```bash
+pnpm add @ir-kit/kit
+```
+
+## Usage
+
+To parse a spec, use `parseOpenAPI` from [`@ir-kit/kit/ir`](./ir.md). To compare two specs, use `ir spec diff` or `diffSpecs` from [`@ir-kit/kit/spec`](./spec-diff.md).
+
+## Origin
+
+Previously shipped as `@ir-kit/kit/openapi-ts/orpc/tools` subpath. Extracted into its own package since the utilities are spec-host-agnostic — they don't depend on oRPC.

package/docs/openapi-ts/typia.md

@@ -0,0 +1,154 @@
+# Typia Integration
+
+Instead of Zod, you can use [Typia](https://typia.io/) for runtime validation.
+Typia generates validators at compile-time from TypeScript types — no schema
+duplication.
+
+Integration is via the [`@ir-kit/kit/openapi-ts/typia`](https://github.com/ahmedrowaihi/ir-kit/tree/main/packages/ir-kit/docs/openapi-ts-typia.md)
+companion plugin. This oRPC plugin consumes it through the standard
+validator API, the same way it consumes `zod`, `valibot`, or `arktype`.
+
+## How it works
+
+With `validator: '@ir-kit/kit/openapi-ts/typia'`, the typia plugin emits
+one `typia.createValidate<T>()` per operation plus a bulk
+`typia.json.schemas<[...]>()` call whose result is indexed by
+operation. The oRPC plugin references those symbols directly on each
+contract's `.input()` / `.output()` / `.errors()`.
+
+## Installation
+
+```bash
+bun add -d @ir-kit/kit
+bun add typia @standard-schema/spec
+bun add -d ttsc typescript @ttsc/unplugin
+```
+
+Typia requires a compiler transform to work. Use `@ttsc/unplugin` for
+your bundler.
+
+`@standard-schema/spec` is already a runtime dep of typia; pnpm's strict
+mode hides transitives, so generated code's `import type { StandardSchemaV1 }`
+requires you list it as a direct install.
+
+## Build setup
+
+### tsdown / rolldown
+
+```typescript
+// tsdown.config.ts
+import { defineConfig } from 'tsdown'
+import ttsc from '@ttsc/unplugin/rolldown'
+
+export default defineConfig({
+  entry: ['src/server.ts'],
+  format: 'esm',
+  outDir: 'dist',
+  plugins: [ttsc({ plugins: [{ transform: 'typia/lib/transform' }] })],
+})
+```
+
+### Vite
+
+```typescript
+// vite.config.ts
+import ttsc from '@ttsc/unplugin/vite'
+
+export default {
+  plugins: [ttsc({ plugins: [{ transform: 'typia/lib/transform' }] })],
+}
+```
+
+## openapi-ts config
+
+```typescript
+import { defineConfig } from '@hey-api/openapi-ts';
+import { defineConfig as defineORPCConfig } from '@ir-kit/kit/openapi-ts/orpc';
+import {
+  defineConfig as defineTypiaConfig,
+  typiaTypeTransformer,
+} from '@ir-kit/kit/openapi-ts/typia';
+
+export default defineConfig({
+  input: 'openapi.json',
+  output: { path: './src/generated' },
+  plugins: [
+    '@hey-api/typescript',
+    {
+      name: '@hey-api/transformers',
+      typeTransformers: [typiaTypeTransformer],
+    },
+    defineTypiaConfig(),
+    defineORPCConfig({
+      validator: '@ir-kit/kit/openapi-ts/typia',
+      // ... rest of your config
+    }),
+  ],
+});
+```
+
+`typiaTypeTransformer` annotates generated TypeScript types with typia
+constraint tags (see [table below](#what-the-transformer-does)) so the
+emitted `createValidate<T>()` calls enforce those constraints.
+
+## OpenAPI spec generation
+
+The typia plugin emits a plain JSON Schema twin per operation alongside
+each validator:
+
+```ts
+export const tGetUserData: StandardSchemaV1<...> = createValidate<...>();
+export const tGetUserDataJsonSchema = typiaSchemas.schemas[0];
+```
+
+For oRPC's OpenAPI generator, write a small `ConditionalSchemaConverter`
+that pairs the validator with its twin and registers both with
+`SmartCoercionPlugin`:
+
+```typescript
+import { createTypiaConverter } from './lib/typia-converter'
+import { ZodToJsonSchemaConverter } from '@orpc/zod'
+
+new SmartCoercionPlugin({
+  schemaConverters: [
+    new ZodToJsonSchemaConverter(),
+    createTypiaConverter(),
+  ],
+})
+```
+
+The converter is a thin wrapper — it detects validators produced by
+typia (via `'~standard'.vendor === 'typia'`) and returns the companion
+JSON Schema symbol by naming convention (`${validatorName}JsonSchema`).
+
+## What the transformer does
+
+`typiaTypeTransformer` annotates TypeScript types with Typia constraint
+tags derived from your OpenAPI schema:
+
+| OpenAPI constraint | Typia tag |
+|---|---|
+| `minLength` / `maxLength` | `MinLength<N>` / `MaxLength<N>` |
+| `pattern` | `Pattern<"...">` |
+| `format` | `Format<"...">` |
+| `minimum` / `maximum` | `Minimum<N>` / `Maximum<N>` |
+| `exclusiveMinimum` / `exclusiveMaximum` | `ExclusiveMinimum<N>` / `ExclusiveMaximum<N>` |
+| `multipleOf` | `MultipleOf<N>` |
+| `minItems` / `maxItems` | `MinItems<N>` / `MaxItems<N>` |
+| `uniqueItems` | `UniqueItems` |
+| integer `format` (int32, int64, …) | `Type<"int32">` etc. |
+
+## Error responses
+
+4xx/5xx responses get per-status validators. Generated contracts wire
+them automatically:
+
+```ts
+export const GetUserContract = oc.route({...})
+  .input(tGetUserData)
+  .output(tGetUserResponse)
+  .errors({
+    404: { data: tGetUserResponseError404 },
+    500: { data: tGetUserResponseError500 },
+  });
+```

package/docs/openapi-ts-faker.md

@@ -0,0 +1,78 @@
+# @ir-kit/kit/openapi-ts/faker
+
+Faker.js mock-data factories from an OpenAPI spec. Plugin for [`@hey-api/openapi-ts`](https://heyapi.dev).
+
+## Install
+
+```bash
+npm install -D @ir-kit/kit @hey-api/openapi-ts
+npm install @faker-js/faker
+```
+
+## Use
+
+```ts
+import { defineConfig } from "@hey-api/openapi-ts";
+import { defineConfig as defineFakerConfig } from "@ir-kit/kit/openapi-ts/faker";
+
+export default defineConfig({
+  input: "openapi.yaml",
+  output: { path: "./generated" },
+  plugins: [
+    "@hey-api/typescript",
+    defineFakerConfig({
+      fieldNameHints: { email: "internet.email", firstName: "person.firstName" },
+    }),
+  ],
+});
+```
+
+## Resolution order (per property)
+
+1. OpenAPI `format` → `formatMapping`
+2. `fieldNameHints` exact match (keys are case/separator-insensitive: `email`, `Email`, `user_email` all normalize the same)
+3. `enum` → `helpers.arrayElement([...])`
+4. Type fallback (`integer` → `number.int`, etc.)
+
+No default field hints. `formatMapping` ships with sensible defaults you can override.
+
+## Mapping
+
+| OpenAPI | Output |
+| --- | --- |
+| `type: object` | `() => ({ ...props })` |
+| `allOf` | merged object |
+| `oneOf` / `anyOf` | `helpers.arrayElement([() => v1, () => v2])()` |
+| `enum` | `helpers.arrayElement([...])` |
+| `type: array` | `helpers.multiple(() => item, { count: { min, max } })` |
+| `$ref` | call to sibling factory: `createMockX()` |
+| cyclic `$ref` | `null` (broken at codegen to avoid runtime recursion) |
+
+## Type safety
+
+`fieldNameHints` and `formatMapping` values are typed against `FakerMethodPath` — every Faker method callable with zero args. Typos and arg-required methods (e.g. `helpers.arrayElement`) fail at compile time.
+
+## Options
+
+```ts
+defineFakerConfig({
+  output: "factories.gen",          // filename
+  fieldNameHints: {},               // field → faker method
+  formatMapping: {},                // format → faker method (merged with defaults)
+  respectConstraints: true,         // honor minimum/maximum, minLength/maxLength, minItems/maxItems
+  generateBatchCreators: true,      // emit createMockXs(count?)
+  defaultBatchCount: 10,            // default count when caller omits arg
+  include: ["User", "Order"],       // only these schemas
+  exclude: ["Internal"],            // skip these schemas
+  filter: (s) => Boolean(s.title),  // custom predicate
+});
+```
+
+When `respectConstraints` is on:
+- `{ minimum: 18, maximum: 99 }` → `number.int({ min: 18, max: 99 })`
+- `{ maxLength: 8 }` → `string.alpha({ length: 8 })`
+- `{ minItems: 2, maxItems: 5 }` → `helpers.multiple(..., { count: { min: 2, max: 5 } })`
+
+## License
+
+MIT

package/docs/openapi-ts-k6.md

@@ -0,0 +1,21 @@
+# @ir-kit/kit/openapi-ts/k6
+
+Thin [`@hey-api/openapi-ts`](https://github.com/hey-api/openapi-ts) plugin that wraps [`@ir-kit/kit/sdk/k6`](../gen). For users who already drive code generation through `openapi-ts.config.ts` — otherwise prefer the [`k6-tools` CLI](../tools).
+
+```ts
+// openapi-ts.config.ts
+import { defineConfig } from "@hey-api/openapi-ts";
+import { defineConfig as defineK6 } from "@ir-kit/kit/openapi-ts/k6";
+
+export default defineConfig({
+  input: "./openapi.yaml",
+  output: "./src/generated",
+  plugins: [
+    defineK6({ output: "./k6", defaultBaseUrl: "https://api.example.com" }),
+  ],
+});
+```
+
+Emits the same four files (`types.ts`, `client.ts`, `data.ts`, `index.ts`) under `<hey-api output.path>/<plugin output>` — see [@ir-kit/kit/sdk/k6](../gen) for output shape.
+
+The plugin is a single function call: it reads the bundled spec from hey-api's context and delegates to `generate()`. No `$` DSL, no symbol planner, no plugin hooks — just spec → files.

package/docs/openapi-ts-kit.md

@@ -0,0 +1,7 @@
+# @ir-kit/kit/openapi-ts/kit
+
+Helpers shared by the ir-kit plugins for [`@hey-api/openapi-ts`](https://github.com/hey-api/openapi-ts).
+
+## `definePlugin(defaultConfig)`
+
+A drop-in replacement for Hey API's `definePluginConfig`. Nested user options are resolved against the plugin's default config table, so `{ naming: { suffix: "Path" } }` keeps the default `casing` instead of dropping it, and dependencies implied by the resolved options are collected.

package/docs/openapi-ts-orpc.md

@@ -0,0 +1,234 @@
+# @ir-kit/kit/openapi-ts/orpc
+
+Generates type-safe [oRPC](https://orpc.unnoq.com/) contracts, routers, server skeletons, clients, and mock factories from OpenAPI specifications. Plugin for [@hey-api/openapi-ts](https://heyapi.dev/).
+
+## Installation
+
+```bash
+bun add -d @ir-kit/kit @hey-api/openapi-ts
+bun add @orpc/contract @orpc/server @orpc/client zod
+```
+
+## What it generates
+
+| File                    | Description                                              | Required              |
+| ----------------------- | -------------------------------------------------------- | --------------------- |
+| `contract.gen.ts`       | Type-safe oRPC contracts with input/output schemas       | Always                |
+| `router.gen.ts`         | Organized router structure                               | Always                |
+| `server.gen.ts`         | `os = implement(router)` helper                          | Optional              |
+| `client.gen.ts`         | Client factory functions (RPC, WebSocket, OpenAPI, etc.) | Optional              |
+| `tanstack.gen.ts`       | TanStack Query utilities                                 | Optional              |
+| `faker.gen.ts`          | Mock data factory functions per tag                      | Optional (faker mode) |
+| `src/handlers/<tag>.ts` | Handler files with three modes                           | Optional              |
+
+---
+
+## Basic Usage
+
+```typescript
+import { defineConfig } from "@hey-api/openapi-ts";
+import { defineConfig as defineORPCConfig } from "@ir-kit/kit/openapi-ts/orpc";
+
+export default defineConfig({
+  input: "openapi.json",
+  output: { path: "./src/generated" },
+  plugins: [
+    "@hey-api/typescript",
+    "zod",
+    defineORPCConfig(), // contracts + router only (default)
+  ],
+});
+```
+
+---
+
+## Server (Backend)
+
+```typescript
+defineORPCConfig({
+  server: {
+    implementation: true,
+    handlers: {
+      dir: "src/handlers",
+      importAlias: "#/",
+      mode: "stub", // 'stub' | 'faker' | 'proxy'
+    },
+  },
+});
+```
+
+### Handler modes
+
+**`stub`** (default) — throws `ORPCError('NOT_IMPLEMENTED')`:
+
+```typescript
+getUser: os.users.getUser.handler(async () => {
+  throw new ORPCError("NOT_IMPLEMENTED");
+}),
+```
+
+**`faker`** — returns mock data from generated `faker.gen.ts` factories:
+
+```typescript
+getUser: os.users.getUser.handler(async () => mockGetUser()),
+```
+
+Requires `@faker-js/faker` as a dependency. Generates type-safe factories with:
+
+- Field name heuristics (email, phone, url, etc.)
+- Enum support via `faker.helpers.arrayElement()`
+- Nested objects and arrays from schema
+- Date `.toISOString()` chaining
+
+**`proxy`** — forwards requests through the generated OpenAPI client:
+
+```typescript
+getUser: os.users.getUser.handler(async ({ input }) => apiClient.users.getUser(input)),
+```
+
+Configure the client import:
+
+```typescript
+handlers: {
+  mode: 'proxy',
+  proxy: { clientImport: { name: 'apiClient', from: '#/lib/client' } },
+}
+```
+
+### Handler file management
+
+- **New tags** create new handler files
+- **Existing files** only get missing procedures appended (never overwritten)
+- **`override: true`** rewrites files completely on each run
+
+---
+
+## Client (Frontend)
+
+```typescript
+defineORPCConfig({
+  client: {
+    rpc: true, // HTTP client (native oRPC RPC protocol)
+    openapi: true, // REST client (OpenAPI protocol)
+    tanstack: true, // TanStack Query utilities
+  },
+});
+```
+
+| Option        | Description                               |
+| ------------- | ----------------------------------------- |
+| `rpc`         | HTTP/Fetch client (native RPC protocol)   |
+| `websocket`   | WebSocket client                          |
+| `messageport` | MessagePort client (Web Workers, iframes) |
+| `openapi`     | REST client (OpenAPI protocol)            |
+| `tanstack`    | TanStack Query utilities                  |
+
+---
+
+## Full Configuration Reference
+
+```typescript
+defineORPCConfig({
+  // Server-side generation
+  server: {
+    implementation: false,
+    handlers: {
+      dir: "src/handlers",
+      importAlias: "#/",
+      implementer: { name: "publicOs", from: "#/procedures" },
+      mode: "stub", // 'stub' | 'faker' | 'proxy'
+      override: false, // rewrite files on each run
+      proxy: { clientImport: { name: "apiClient", from: "#/lib/client" } },
+    },
+  },
+
+  // Client-side generation
+  client: {
+    rpc: false,
+    websocket: false,
+    messageport: false,
+    openapi: false,
+    tanstack: false,
+  },
+
+  // Input structure mode
+  mode: "compact", // 'compact' | 'detailed'
+
+  // Router grouping
+  group: "tags", // 'tags' | 'paths' | 'flat' | 'operationId'
+
+  // JSDoc comments on contracts
+  comments: true,
+
+  // Naming rules (uses hey-api's applyNaming)
+  naming: {
+    contract: { casing: "PascalCase" }, // contract constant names
+    operation: { casing: "camelCase" }, // router/procedure keys
+  },
+
+  // Validator configuration
+  validator: "zod", // string | false | { input: string | false, output: string | false }
+});
+```
+
+### `mode` — Input structure
+
+| Mode | Description |
+| --- | --- |
+| `compact` (default) | Flat merged input — path + body for mutations, path + query for reads |
+| `detailed` | Structured `{ params, query, body, headers }` input |
+
+> **Note:** Standard validators (zod, valibot, arktype) always use detailed mode regardless of this setting. Compact mode is only supported with Typia. This is because hey-api's `createRequestSchema` API always returns a structured object.
+
+### `group` — Router grouping
+
+| Mode             | Description                 | Example                      |
+| ---------------- | --------------------------- | ---------------------------- |
+| `tags` (default) | Group by OpenAPI tag        | `router.users.getById()`     |
+| `paths`          | Group by URL structure      | `router.api.users.getById()` |
+| `flat`           | No grouping                 | `router.getUserById()`       |
+| `operationId`    | Group by operationId prefix | `router.auth.login()`        |
+
+### `validator` — Validation configuration
+
+Works with any hey-api validator plugin (zod, valibot, arktype):
+
+```typescript
+// Single validator for both input and output (default)
+validator: 'zod'
+
+// Separate input/output validators
+validator: { input: 'zod', output: false }
+
+// Disable validation entirely
+validator: false
+```
+
+### `naming` — Name customization
+
+Uses `applyNaming` from `@hey-api/shared`:
+
+```typescript
+naming: {
+  contract: { casing: 'PascalCase' },   // GetUserContract
+  operation: { casing: 'camelCase' },    // getUser
+}
+```
+
+Supports `'camelCase'`, `'PascalCase'`, `'snake_case'`, `'SCREAMING_SNAKE_CASE'`, `'preserve'`, or a custom transform function.
+
+---
+
+## Requirements
+
+- `@hey-api/openapi-ts` >= 0.95.0
+- `@hey-api/typescript` plugin (auto-included as dependency)
+- A validator plugin (`zod`, `valibot`, `arktype`) configured in your plugins
+
+---
+
+## Typia Integration
+
+Want compile-time validators instead of Zod? See [docs/typia.md](docs/typia.md).
+
+Set `validator: { input: 'typia', output: 'typia' }` to use Typia's Standard Schema validators.

package/docs/openapi-ts-paths.md

@@ -0,0 +1,77 @@
+# @ir-kit/kit/openapi-ts/paths
+
+Per-operation route consts emitted from an OpenAPI spec — spec template, URLPattern-style pattern, method, and operationId, ready for tree-shakable runtime routing and matching. Plugin for [`@hey-api/openapi-ts`](https://heyapi.dev).
+
+## Install
+
+```bash
+npm install -D @ir-kit/kit @hey-api/openapi-ts
+```
+
+## Use
+
+```ts
+import { defineConfig } from "@hey-api/openapi-ts";
+import { defineConfig as definePathsConfig } from "@ir-kit/kit/openapi-ts/paths";
+
+export default defineConfig({
+  input: "openapi.yaml",
+  output: { path: "./generated" },
+  plugins: [
+    "@hey-api/typescript",
+    definePathsConfig({
+      output: "paths",                // → generated/paths.ts
+      naming: { casing: "camelCase", suffix: "Route" },
+    }),
+  ],
+});
+```
+
+## Output
+
+For each operation that has a `path` and an `operationId`, the plugin emits:
+
+```ts
+export const getPetByIdRoute = {
+  spec: "/pets/{id}",
+  pattern: "/pets/:id",
+  method: "get",
+  operationId: "getPetById",
+} as const;
+```
+
+- `spec` — the original `{param}` template, useful when re-issuing the request.
+- `pattern` — `:param` form, ready to feed `URLPattern`, `path-to-regexp`, your router of choice.
+- `method` — lower-case verb.
+- `operationId` — the OpenAPI id when present.
+
+`as const` keeps every value literal-typed so downstream code can narrow on `route.method`, etc.
+
+## Why route consts (instead of runtime routing)
+
+Tree-shakable: only the routes you import end up in the bundle. Pair with the matchers in [`@ir-kit/kit/openapi-tools`](../../openapi-tools) for client-side dispatch:
+
+```ts
+import { match } from "@ir-kit/kit/openapi-tools/match";
+import { getPetByIdRoute } from "./generated/paths";
+
+const params = match(getPetByIdRoute.pattern, "/pets/42"); // { id: "42" }
+```
+
+Or feed them to a router framework that takes pattern strings.
+
+## Options
+
+```ts
+definePathsConfig({
+  output: "paths",                    // filename (no extension). Default: "paths"
+  naming: {
+    casing: "camelCase",              // any @hey-api/shared NamingRule | Casing
+    suffix: "Route",                  // appended to each const name
+  },
+});
+```
+
+## License
+
+MIT