@nxara/olio-codegen 0.1.1 → 0.1.2

package/README.md

@@ -1,239 +1,12 @@
 # @nxara/olio-codegen
 
-Generate TypeScript types from GraphQL SDL.
-
-`@nxara/olio-codegen` discovers modules from a directory layout, reads each module's GraphQL SDL, and emits a single strongly typed TypeScript file: schema types, per-module operation contracts, and the application type.
-
-It is deliberately small - SDL in, types out. Schema composition belongs to `@nxara/olio-schema`, the runtime to `@nxara/olio`.
-
-## Install
+Generate TypeScript types from GraphQL SDL: the schema's types and the `Application` contract that types olio's builders, plus typed operations for `@nxara/olio-client`.
 
 ```sh
-bun add @nxara/olio-codegen graphql@16
-```
-
-`graphql` 16 is a peer dependency.
-
-## Usage
-
-There is no bundled CLI; drive codegen from a short script:
-
-```ts
-import { codegen } from "@nxara/olio-codegen";
-
-await codegen({
-  root: import.meta.dirname,
-  modules: "src/modules",
-  typeDefs: "**/typedefs/**/*.gql",
-  output: "src/generated.ts"
-});
-```
-
-Relative paths (`modules`, `output`, `schemaOutput`) resolve against `root`, which defaults to the working directory; pass `import.meta.dirname` so the script runs the same from any folder. `typeDefs` is the exception: it resolves inside each module. `codegenClient` takes `root` the same way, for `schema` (unless it's a URL), `documents` and `output`.
-
-Both reject with a message that names the file and position. Uncaught, the runtime prints it with a stack; to print just the message:
-
-```ts
-await codegen({ ... }).catch((error: Error) => {
-  console.error(error.message);
-  process.exitCode = 1;
-});
-```
-
-`modules` points to a directory whose **direct child directories** are modules. `typeDefs` is resolved relative to each module directory. `codegen` discovers modules, loads and parses their SDL, generates TypeScript, and writes the output (creating parent directories as needed).
-
-SDL files are read exactly as `loadTypeDefs` in `@nxara/olio-tools` reads them (both go through `@nxara/olio-core/files`): `.graphql` / `.gql`, or `.ts` / `.js` files whose default export is SDL or a `DocumentNode`, so an app moving from untyped to typed keeps its SDL where it is (`typeDefs: "**/typedefs/**/*.{gql,ts}"`). Codegen imports `.ts` files, so run it with something that executes TypeScript (bun, tsx, or Node 23.6+).
-
-### Directives
-
-Pass `directives` to apply `@nxara/olio-schema` transformations before generation:
-
-```ts
-import { codegen } from "@nxara/olio-codegen";
-import { copyDirective, implementsDirective } from "@nxara/olio-schema";
-
-await codegen({
-  modules: "src/modules",
-  typeDefs: "**/typedefs/**/*.gql",
-  output: "src/generated.ts",
-  schemaOutput: "src/schema.graphql",
-  directives: [implementsDirective(), copyDirective()]
-});
-```
-
-Their names land in `Application` as `"~directives"`, and olio's types then require the same `directives` in `olio()`.
-
-Set `schemaOutput` to write the final schema to a file, printed from the built schema: each type once with its extensions merged in, the directives applied, ready for schema registries, linters and diff tools. Omit it to generate only TypeScript. The schema is validated before anything is written, so an invalid one fails codegen rather than the server.
-
-## Client types
-
-`codegenClient({ schema, documents, output })` generates the types for [`@nxara/olio-client`](../client), the way graphql-codegen does: `schema` is an SDL file (typically the `schemaOutput` file above) or the running server's URL, introspected (`headers` for one that needs a token); `documents` are the client's `.graphql` operations. The operations are checked against the schema first, with `file:line:column` errors. `watch: true` reruns when an operation (including a new file) or the schema file changes; a server URL isn't watched.
-
-Subscriptions go over WebSocket unless marked `@sse` (`subscription Feed @sse { … }`); `@ws` says the default explicitly. The directive is the client's: codegen records it in the document and removes it from the query the server receives, and imports only the transports the operations use. `@ws` / `@sse` on a query or mutation, both on one subscription, or with arguments, is an error.
-
-Per operation it emits the result type, the variables type and a typed document (`LoginMutation`, `LoginMutationVariables`, `LoginDocument`), plus `operations` for `createClient`. Types are what a client sees on the wire: enums by name, scalars through `ClientScalars`.
-
-```ts
-import { codegenClient } from "@nxara/olio-codegen";
-
-await codegenClient({
-  root: import.meta.dirname,
-  schema: "../server/src/schema.gql", // or "http://localhost:4000/graphql"
-  documents: "src/operations/*.graphql",
-  output: "src/generated.ts"
-});
-```
-
-## Modules
-
-Every direct child directory of `modules` is one module. The directory name is the module ID, and there are no nested modules:
-
-```
-src/modules/
-├── auth/
-│   ├── typedefs/auth.gql
-│   └── query.ts
-├── user/
-│   └── typedefs/user.gql
-└── sales/
-    ├── typedefs/sales.gql
-    └── orders/
-        └── typedefs/orders.gql
-```
-
-This yields modules `auth`, `user`, and `sales`. `typeDefs` resolves inside each module (`src/modules/auth/**/typedefs/**/*.gql`, and so on), so each module's files belong exclusively to that module.
-
-A direct subfolder of a module in which `typeDefs` finds files of its own is a **feature** of that module: here `sales/orders`, with its own entry in `Application` (`"sales/orders"`). Features don't nest.
-
-So the glob decides what is a feature, because codegen runs it inside each subfolder. `**/typedefs/**/*.gql` finds nothing inside `users/typedefs/` itself (there's no `typedefs/` in it), so that folder stays the module's own SDL. `**/*.gql` does find its files, so it makes `typedefs` a feature of every module (`"users/typedefs"`), and `users` ends up with no fields. Keep SDL in `typedefs/` folders and use `**/typedefs/**/*.gql`. The ID is used as-is as the module's key in `Application` (quoted when it is not a valid identifier).
-
-## Application
-
-`Application` lists, per module, the types it declares fields on. Register it with `@nxara/olio`, which derives resolver signatures and middleware targets from it:
-
-```ts
-export type Application = {
-  users: {
-    Query: {
-      type: Query;
-      fields: "user" | "users";
-      args: {
-        user: { id: string };
-      };
-    };
-    User: { type: User; fields: "__isTypeOf" | "id" | "name" };
-  };
-  posts: {
-    Post: { type: Post; fields: "__isTypeOf" | "id" };
-    User: { type: User; fields: "posts" }; // from `extend type User { posts: [Post!]! }`
-  };
-};
-```
-
-- **`type`** is the parent type. Resolvers receive it as `root` and return `type[field]`.
-- **`fields`** are the fields the module owns. A module owns every field it declares, whether in a definition or an `extend`, on root and non-root types alike. The defining module also owns `__isTypeOf` (objects) or `__resolveType` (interfaces and unions, which also list their possible types as `resolveType`).
-- **`args`** appears only for fields that take arguments.
-- **Enums** appear as `{ type; fields: never; enum: "A" | "B" }`, listing the values the module declares (an `extend enum` belongs to the extending module).
-- **Scalars** appear as `{ type; fields: never; scalar: true }` under the module that defines them, which supplies the implementation.
-- **`bypass`** lists, per owned field, the keys its `@bypass` gives it (`bypass: { login: "audit" | "auth" }`). olio types middleware's `bypass` set from every key listed here.
-- **`root`** marks a root type with its operation (`root: "query"`), so olio finds the roots whatever they're named. A hand-written `Application` needs it too.
-
-Middleware targets aren't emitted: a module's targets are its owned fields, and the application's are the root fields.
-
-## Supported SDL
-
-- Object types, interfaces, unions, enums, inputs, and scalars
-- Lists and nullability (`String`, `[String!]!`, …), mapped exactly
-- Type extensions (`extend type User { … }`)
-- Root operation types, under the default names or your own (`schema { query: RootQuery }`)
-
-A schema type can't be named `Application`, `Maybe`, `ResolveEnum`, `ResolveScalar` or `Scalars`, since the generated file declares those names itself.
-
-## Custom scalars
-
-Every scalar goes through one exported table, `Scalars`, so fields read `Scalars["DateTime"]["output"]`. Built-in scalars default to their usual TypeScript types (`ID`/`String` → `string`, `Int`/`Float` → `number`, `Boolean` → `boolean`), and custom scalars default to `unknown`. Register or remap any of them by augmenting `CustomScalars`:
-
-```ts
-declare module "@nxara/olio-codegen" {
-  interface CustomScalars {
-    DateTime: Date;
-    JSON: { input: string; output: unknown };
-    ID: string | ObjectId; // built-ins can be remapped too
-  }
-}
-```
-
-Use the table directly when you need a scalar's type: `Scalars["DateTime"]["input"]`.
-
-Like every registration, it goes in a `.ts` file, or a `.d.ts` with an `import` or `export {}`.
-
-## Enums with internal values
-
-Enums are their GraphQL names by default (`"ADMIN" | "GUEST"`). To store something else, such as a number or a lowercase string, register the internal type by augmenting `CustomEnums`:
-
-```ts
-declare module "@nxara/olio-codegen" {
-  interface CustomEnums {
-    OrderStatus: "confirmed" | "cancelled";
-  }
-}
-```
-
-Every generated position then uses it: object fields, arguments, and inputs, since graphql converts enum inputs to internal values too. Supply the values at runtime through the owning module's `enums` option. Once `CustomEnums` registers an enum, olio's types require it there, with a value for every value the module declares:
-
-```ts
-export const sales = module.sales({
-  typeDefs,
-  resolvers,
-  enums: { OrderStatus: { CONFIRMED: "confirmed", CANCELLED: "cancelled" } }
-});
-```
-
-To keep a map in its own file, write it with the typed builder: `export const OrderStatus = resolvers.sales.OrderStatus({ ... })`, then `enums: { OrderStatus }`, or load such files with `enums: await loadEnums(...)` from `@nxara/olio-tools` (unchecked, like `loadResolvers`).
-
-## Output
-
-`codegen` writes a single TypeScript file to `output`. For:
-
-```graphql
-type Query {
-  user: User
-}
-type User {
-  id: ID!
-  name: String
-}
-```
-
-the emitted `User` type is:
-
-```ts
-export type User = {
-  __typename?: "User";
-  id: Scalars["ID"]["output"];
-  name: Maybe<Scalars["String"]["output"]>;
-};
+bun add -d @nxara/olio-codegen
+bun add graphql@16
 ```
 
-The full output contains:
-
-- the `Scalars` table
-- enums as `const` objects plus union types
-- object types (root types included), interfaces, inputs, and unions. Nullable inputs without a default are optional keys.
-- the `Application` type
-
-The header marks the file as generated:
-
-```ts
-// Generated by @nxara/olio-codegen - do not edit.
-```
-
-## Relationship to @nxara/olio-schema
-
-`@nxara/olio-schema` composes a schema into ordinary GraphQL; `@nxara/olio-codegen` then turns that GraphQL into TypeScript:
-
-```
-SDL → @nxara/olio-schema → DocumentNode → @nxara/olio-codegen → TypeScript
-```
+**[Read the docs](https://olio.nxara.dev/reference/codegen/)**
 
-Codegen has no knowledge of `@implements` or `@copy` - it accepts `SchemaDirective[]` and passes the parsed document through the transformation pipeline.
+Part of [olio](https://olio.nxara.dev): modular, type-safe GraphQL for TypeScript. MIT licensed.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nxara/olio-codegen",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Generate TypeScript types from GraphQL SDL.",
   "keywords": [
     "codegen",
@@ -34,8 +34,8 @@
     "check-types": "tsc -p tsconfig.test.json"
   },
   "dependencies": {
-    "@nxara/olio-core": "0.1.1",
-    "@nxara/olio-schema": "0.1.1"
+    "@nxara/olio-core": "0.1.2",
+    "@nxara/olio-schema": "0.1.2"
   },
   "devDependencies": {
     "graphql": "^16.14.2"