apiwork 0.0.0 → 0.0.2

package/README.md

@@ -0,0 +1,311 @@
+# apiwork-js
+
+JavaScript toolkit for [Apiwork](https://apiwork.dev).
+
+Provides a parser, TypeScript types, and code generators for TypeScript, [Zod](https://zod.dev), and [Sorbus](https://sorbus.dev).
+
+## Installation
+
+```bash
+npm install apiwork
+# or
+pnpm add apiwork
+```
+
+## Schema
+
+The [Apiwork schema](https://apiwork.dev/guide/exports/apiwork) is a portable JSON description of your API. Parse it and work with typed, camelCased objects:
+
+```ts
+import { parse } from 'apiwork';
+import type { Schema, Resource, Action, Param } from 'apiwork';
+
+// From raw JSON data
+const schema = parse(data);
+
+// From a URL
+const schema = await parse.url('http://localhost:3000/api/v1/.apiwork');
+
+// From a file
+const schema = await parse.file('./apiwork.json');
+
+for (const resource of schema.resources) {
+  console.log(resource.identifier);
+}
+```
+
+> `parse.url()` and `parse.file()` throw `ParseError` on failure, with the underlying error preserved on `error.cause`.
+
+## CLI
+
+```bash
+apiwork typescript ./apiwork.json --outdir src/api/sorbus
+apiwork zod ./apiwork.json --outdir src/api/sorbus
+apiwork sorbus ./apiwork.json --outdir src/api/sorbus
+```
+
+The source can be a local file or a URL:
+
+```bash
+apiwork sorbus http://localhost:3000/api/v1/.apiwork --outdir src/api/sorbus
+```
+
+## Generators
+
+### TypeScript
+
+Generates pure TypeScript types from representations and enums. Use this if you only need types without runtime validation.
+
+### Zod
+
+Generates Zod validation schemas alongside TypeScript types. Use this if you need runtime validation without a typed HTTP client.
+
+### Sorbus
+
+Generates a typed [Sorbus](https://sorbus.dev) client with operations, schemas, and endpoints. Includes everything from the TypeScript and Zod generators.
+
+## Options
+
+All three generators share common options (`fileCase`, `importExtension`, `transformIdentifier`) plus their own `version` for the output they produce:
+
+```ts
+import { generate } from 'apiwork/sorbus';
+
+const files = generate(schema, {
+  version: 1,                     // Sorbus major version (default: 1)
+  zod: { version: 4 },            // Zod inline-schemas (default: 4)
+  typescript: { version: 5 },     // TypeScript types (default: 5)
+  fileCase: 'kebab',
+  importExtension: '.js',
+  transformIdentifier: (identifier, source) => {
+    if (source === 'api') return `Api${identifier}`;
+    if (source === 'client' && identifier === 'Client') return 'MyClient';
+    return identifier;
+  },
+});
+```
+
+### `version`
+
+Each generator targets a specific major version of its output:
+
+| Generator | `version` | Default |
+|---|---|---|
+| `apiwork/typescript` | TypeScript major | `5` |
+| `apiwork/zod` | Zod major | `4` |
+| `apiwork/sorbus` | Sorbus major | `1` |
+
+Generators that produce output for multiple libraries take nested configuration:
+
+```ts
+// apiwork/typescript — just TS version
+generate(schema, { version: 5 });
+
+// apiwork/zod — Zod version + TS version for exported types
+generate(schema, {
+  version: 4,
+  typescript: { version: 5 },
+});
+
+// apiwork/sorbus — Sorbus version + Zod + TS
+generate(schema, {
+  version: 1,
+  zod: { version: 4 },
+  typescript: { version: 5 },
+});
+```
+
+### `fileCase`
+
+The file name case format. Accepts `'kebab'` (default), `'camel'`, `'pascal'`, or `'snake'`.
+
+| Value | Example |
+|---|---|
+| `'kebab'` | `invoice-line-item.ts` |
+| `'camel'` | `invoiceLineItem.ts` |
+| `'pascal'` | `InvoiceLineItem.ts` |
+| `'snake'` | `invoice_line_item.ts` |
+
+### `importExtension`
+
+The extension appended to relative import paths. Accepts `''` (default), `'.js'`, or `'.ts'`. Use `'.js'` for Node ESM or Deno.
+
+```ts
+// importExtension: ''   →  from '../api'
+// importExtension: '.js' →  from '../api.js'
+```
+
+### `transformIdentifier`
+
+A callback invoked for every identifier the generator emits. Return the name unchanged to keep the default, or return a new name to rename it.
+
+```ts
+transformIdentifier?: (identifier: string, source: IdentifierSource) => string;
+
+type IdentifierSource = 'domain' | 'api' | 'endpoint' | 'client';
+```
+
+| `source` | Covers |
+|---|---|
+| `'domain'` | Types and schemas in `domains/*` (scoped domain types). |
+| `'api'` | Types and schemas in `api.ts` (global domain types — highest collision risk). |
+| `'endpoint'` | Types and schemas in `endpoints/*` (request, response, definition). |
+| `'client'` | Sorbus-specific symbols: `Client`, `createClient`, `contract`. |
+
+Example — prefix all global types and rename the Sorbus client:
+
+```ts
+transformIdentifier: (identifier, source) => {
+  if (source === 'api') return `Api${identifier}`;
+  if (source === 'client' && identifier === 'Client') return 'SkiftleClient';
+  if (source === 'client' && identifier === 'createClient') return 'createSkiftleClient';
+  return identifier;
+}
+```
+
+## Generated output
+
+Given this Apiwork schema:
+
+```json
+{
+  "enums": [
+    { "name": "invoice_status", "values": ["draft", "sent", "paid"] }
+  ],
+  "types": [
+    {
+      "name": "invoice",
+      "type": "object",
+      "shape": [
+        { "name": "id", "type": "string" },
+        { "name": "number", "type": "string" },
+        { "name": "status", "type": "string", "enum": "invoice_status" },
+        { "name": "issuedOn", "type": "date", "nullable": true },
+        { "name": "createdAt", "type": "datetime" },
+        { "name": "updatedAt", "type": "datetime" }
+      ]
+    }
+  ],
+  "resources": [
+    {
+      "identifier": "invoices",
+      "path": "invoices",
+      "actions": [
+        { "name": "invoices.index", "method": "get", "path": "/invoices" },
+        { "name": "invoices.show", "method": "get", "path": "/invoices/:id" },
+        { "name": "invoices.create", "method": "post", "path": "/invoices" },
+        { "name": "invoices.destroy", "method": "delete", "path": "/invoices/:id" }
+      ]
+    }
+  ]
+}
+```
+
+`apiwork sorbus` generates:
+
+```
+api.ts
+domains/
+  index.ts
+endpoints/
+  invoices.ts
+  index.ts
+contract.ts
+client.ts
+```
+
+See the [full generated output](https://apiwork.dev/examples/representations#codegen) for a complete example.
+
+## Frontend integration
+
+Add a script to generate the client from your API:
+
+```json
+{
+  "scripts": {
+    "sorbus": "apiwork sorbus http://localhost:3000/api/v1/.apiwork --outdir src/api/sorbus"
+  }
+}
+```
+
+```bash
+pnpm sorbus
+```
+
+Optionally, format the generated output:
+
+```json
+{
+  "scripts": {
+    "sorbus": "apiwork sorbus http://localhost:3000/api/v1/.apiwork --outdir src/api/sorbus && biome check --write src/api/sorbus"
+  }
+}
+```
+
+Using Prettier or Oxfmt? Replace `biome check --write` with `prettier --write` or `oxfmt`.
+
+Use the generated client:
+
+```ts
+import { createClient } from './sorbus/client';
+
+const api = createClient('http://localhost:3000/api/v1');
+
+const { invoices } = await api.invoices.index();
+
+const { invoice } = await api.invoices.show({ id: '1' });
+
+const result = await api.invoices.create(
+  { invoice: { number: 'INV-001', customerId: '1' } },
+  { catch: [422] },
+);
+
+if (!result.ok) {
+  console.log(result.data);
+}
+```
+
+## API Reference
+
+### `apiwork`
+
+Parser and schema types.
+
+**Values:**
+- `parse(data)` — parse raw JSON data into a `Schema`
+- `parse.url(url)` — fetch and parse from a URL
+- `parse.file(path)` — read and parse from a file
+- `ParseError` — thrown on parse failures, with `cause` on `error.cause`
+
+**Types:**
+
+`Action`, `ActionMethod`, `ActionRequest`, `ActionResponse`, `ArrayParam`, `BinaryParam`, `BooleanParam`, `DateParam`, `DatetimeParam`, `DecimalParam`, `Enum`, `ErrorCode`, `FileCase`, `GenerateOptions`, `IdentifierSource`, `Info`, `InfoContact`, `InfoLicense`, `InfoServer`, `IntegerParam`, `LiteralParam`, `NumberParam`, `ObjectParam`, `ObjectType`, `Param`, `RecordParam`, `ReferenceParam`, `Resource`, `Schema`, `StringParam`, `TimeParam`, `Type`, `UnionParam`, `UnionType`, `UnknownParam`, `UuidParam`
+
+### `apiwork/typescript`
+
+TypeScript code generator — produces pure TypeScript types from the schema.
+
+- `generate(schema, options?)` — returns a `Map<string, string>` of file paths to file contents
+- `TypescriptGenerateOptions` — options type
+
+### `apiwork/zod`
+
+Zod code generator — produces Zod schemas plus TypeScript types.
+
+- `generate(schema, options?)` — returns a `Map<string, string>` of file paths to file contents
+- `ZodGenerateOptions` — options type
+
+### `apiwork/sorbus`
+
+Sorbus code generator — produces a typed Sorbus client, contract, Zod schemas, and TypeScript types.
+
+- `generate(schema, options?)` — returns a `Map<string, string>` of file paths to file contents
+- `SorbusGenerateOptions` — options type
+
+---
+
+All exported symbols carry full TSDoc. Hover over any import in your IDE to see descriptions, parameter docs, and examples.
+
+## License
+
+MIT

package/dist/bin/apiwork.js

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+import {
+  parse
+} from "../chunk-7NDS6XB6.js";
+import {
+  generate
+} from "../chunk-ZP6ZWEPI.js";
+import {
+  generate as generate2
+} from "../chunk-4AJOYIJC.js";
+import {
+  generate as generate3
+} from "../chunk-NQPUJJ3O.js";
+import {
+  writeFiles
+} from "../chunk-QGKZLUZR.js";
+import "../chunk-MWFEILAW.js";
+
+// src/cli.ts
+import { parseArgs } from "util";
+var generators = {
+  sorbus: generate,
+  typescript: generate2,
+  zod: generate3
+};
+async function run(args) {
+  const { positionals, values } = parseArgs({
+    allowPositionals: true,
+    args,
+    options: {
+      outdir: {
+        short: "o",
+        type: "string"
+      }
+    }
+  });
+  const [command, url] = positionals;
+  if (!command || !url) {
+    console.error("Usage: apiwork <generator> <url> --outdir <dir>");
+    console.error("Generators: typescript, zod, sorbus");
+    process.exit(1);
+  }
+  const generator = generators[command];
+  if (!generator) {
+    console.error(`Unknown generator: ${command}`);
+    console.error(`Available: ${Object.keys(generators).join(", ")}`);
+    process.exit(1);
+  }
+  const outdir = values.outdir ?? ".";
+  const schema = url.startsWith("http://") || url.startsWith("https://") ? await parse.url(url) : await parse.file(url);
+  const files = generator(schema);
+  await writeFiles(outdir, files);
+  for (const filename of files.keys()) {
+    console.log(`  ${filename}`);
+  }
+}
+
+// src/bin/apiwork.ts
+run(process.argv.slice(2));

package/dist/chunk-4AJOYIJC.js

@@ -0,0 +1,37 @@
+import {
+  buildEndpoints,
+  buildSchemas,
+  buildScopeIndex,
+  resolveGenerateOptions
+} from "./chunk-QGKZLUZR.js";
+
+// src/typescript/generate.ts
+function generate(schema, options = {}) {
+  const resolvedOptions = resolveGenerateOptions(options);
+  const scopeIndex = buildScopeIndex(schema);
+  const files = /* @__PURE__ */ new Map();
+  for (const [filename, content] of buildSchemas(
+    schema,
+    { zod: false },
+    resolvedOptions
+  )) {
+    files.set(filename, content);
+  }
+  for (const [filename, content] of buildEndpoints(
+    schema,
+    scopeIndex,
+    {
+      endpoints: false,
+      reexportChildren: false,
+      zod: false
+    },
+    resolvedOptions
+  )) {
+    files.set(filename, content);
+  }
+  return files;
+}
+
+export {
+  generate
+};

package/dist/chunk-7NDS6XB6.js

@@ -0,0 +1,57 @@
+import {
+  camelCaseKeys
+} from "./chunk-MWFEILAW.js";
+
+// src/parse.ts
+import { readFile } from "fs/promises";
+var ParseError = class extends Error {
+  constructor(message, options) {
+    super(message, options);
+    this.name = "ParseError";
+  }
+};
+function parseData(data) {
+  return camelCaseKeys(data);
+}
+async function parseUrl(url) {
+  let response;
+  try {
+    response = await fetch(url);
+  } catch (cause) {
+    throw new ParseError(`Failed to fetch schema from ${url}`, { cause });
+  }
+  if (!response.ok) {
+    throw new ParseError(
+      `Failed to fetch schema from ${url}: ${response.status} ${response.statusText}`
+    );
+  }
+  let data;
+  try {
+    data = await response.json();
+  } catch (cause) {
+    throw new ParseError(`Schema at ${url} is not valid JSON`, { cause });
+  }
+  return parseData(data);
+}
+async function parseFile(path) {
+  let content;
+  try {
+    content = await readFile(path, "utf-8");
+  } catch (cause) {
+    throw new ParseError(`Failed to read schema from ${path}`, { cause });
+  }
+  try {
+    return parseData(JSON.parse(content));
+  } catch (cause) {
+    throw new ParseError(`Schema at ${path} is not valid JSON`, { cause });
+  }
+}
+var parse = Object.assign(parseData, {
+  file: parseFile,
+  url: parseUrl
+});
+
+export {
+  ParseError,
+  parse
+};

package/dist/chunk-MWFEILAW.js

@@ -0,0 +1,28 @@
+// src/utils/camel-case.ts
+function camelCase(name) {
+  const leading = /^_+/.exec(name)?.[0] ?? "";
+  return leading + name.slice(leading.length).replace(
+    /[-_]([a-z])/g,
+    (_match, character) => character.toUpperCase()
+  );
+}
+
+// src/utils/camel-case-keys.ts
+function camelCaseKeys(value) {
+  if (Array.isArray(value)) {
+    return value.map(camelCaseKeys);
+  }
+  if (value !== null && typeof value === "object") {
+    const result = {};
+    for (const [key, entryValue] of Object.entries(value)) {
+      result[camelCase(key)] = camelCaseKeys(entryValue);
+    }
+    return result;
+  }
+  return value;
+}
+
+export {
+  camelCase,
+  camelCaseKeys
+};

package/dist/chunk-NQPUJJ3O.js

@@ -0,0 +1,37 @@
+import {
+  buildEndpoints,
+  buildSchemas,
+  buildScopeIndex,
+  resolveGenerateOptions
+} from "./chunk-QGKZLUZR.js";
+
+// src/zod/generate.ts
+function generate(schema, options = {}) {
+  const resolvedOptions = resolveGenerateOptions(options);
+  const scopeIndex = buildScopeIndex(schema);
+  const files = /* @__PURE__ */ new Map();
+  for (const [filename, content] of buildSchemas(
+    schema,
+    { zod: true },
+    resolvedOptions
+  )) {
+    files.set(filename, content);
+  }
+  for (const [filename, content] of buildEndpoints(
+    schema,
+    scopeIndex,
+    {
+      endpoints: false,
+      reexportChildren: false,
+      zod: true
+    },
+    resolvedOptions
+  )) {
+    files.set(filename, content);
+  }
+  return files;
+}
+
+export {
+  generate
+};