@lyku/lockstep-handles-ts 1.0.0 → 1.3.1

package/LLMs.md

@@ -0,0 +1,88 @@
+# @lyku/lockstep-handles-ts — LLM Reference
+
+This document is a mechanical reference for `@lyku/lockstep-handles-ts`, the TypeScript handler factory generator in the lockstep toolkit.
+
+## Purpose
+
+Generates typed handler wrappers from `TsonHandlerModel` API definitions. Each generated handler factory:
+
+1. Embeds a runtime request validator (built from the model's `request` schema)
+2. Attaches the model definition for framework consumption
+3. Provides full TypeScript types for request, response, and context
+
+## API
+
+### `generateHandles(options: GenerateHandlesOptions): Promise<void>`
+
+Single entry point. Generates `.js` and `.d.ts` files for every handler model in the input.
+
+```typescript
+interface GenerateHandlesOptions {
+	models: Record<string, unknown>; // Endpoint models (auto-filtered)
+	outputDir: string; // Output directory
+	modelsPackage: string; // e.g. '@myapp/api-models'
+	typesPackage: string; // e.g. '@myapp/api-types'
+	contextPackage?: string; // default: '@lyku/lockstep-core/contexts'
+	typesName?: string; // default: 'ApiTypes'
+	clean?: boolean; // default: true
+}
+```
+
+## Generated file structure
+
+For each handler model entry (e.g. `createUser`):
+
+### `createUser.js`
+
+```javascript
+import { createUser } from '@myapp/api-models';
+import { isObject } from '@lyku/lockstep-core'; // only if validator uses it
+
+export const handleCreateUser = (handler) => ({
+	execute: handler, // 'execute' for HTTP, 'onOpen' for WebSocket
+	validator: { validate, validateOrThrow, isValid },
+	model: {
+		/* serialized TsonHandlerModel */
+	},
+});
+```
+
+### `createUser.d.ts`
+
+```typescript
+import { createUser } from '@myapp/api-models';
+import type { MyApiTypes } from '@myapp/api-types';
+import type { CreateUserRequest, CreateUserResponse } from '@myapp/api-types';
+import type { SecureHttpContext } from '@lyku/lockstep-core/contexts';
+
+export declare const handleCreateUser: (handler: (request: CreateUserRequest, context: SecureHttpContext<typeof createUser>) => CreateUserResponse | Promise<CreateUserResponse>) => {
+	/* ... */
+};
+```
+
+## Context type selection
+
+| Protocol  | Authenticated | Context Type               |
+| --------- | ------------- | -------------------------- |
+| HTTP      | true          | `SecureHttpContext`        |
+| HTTP      | false         | `MaybeSecureHttpContext`   |
+| WebSocket | true          | `SecureSocketContext`      |
+| WebSocket | false         | `MaybeSecureSocketContext` |
+
+HTTP vs WebSocket is determined by `model.stream`. Authentication by `model.authenticated`.
+
+## Key behaviors
+
+- **Filtering**: `filterHandlerModels()` from lockstep-core removes non-handler entries from the models record before generation
+- **Validator embedding**: Validators are serialized as inline JavaScript strings (not imports) so handlers are self-contained
+- **Formatting**: All output is formatted with prettier via `formatCode()` from lockstep-core
+- **Naming convention**: endpoint `foo` → factory `handleFoo`, types `FooRequest`/`FooResponse`
+- **WebSocket tweakRequest**: If `model.stream.tweakRequest` exists, a `tweakValidator` is also generated
+- **Index files**: `index.js` uses `.js` extensions in re-exports; `index.d.ts` uses bare specifiers
+
+## Dependencies
+
+| Package                          | Used for                                     |
+| -------------------------------- | -------------------------------------------- |
+| `@lyku/lockstep-core`            | `buildValidator`, `stringifyBON`, `isObject` |
+| `@lyku/lockstep-core/generators` | `formatCode`, `filterHandlerModels`          |

package/README.md

@@ -0,0 +1,130 @@
+# @lyku/lockstep-handles-ts
+
+Generate typed handler factories from `TsonHandlerModel` API definitions. Part of the [lockstep](https://github.com/muzzin/lyku) schema toolkit.
+
+## What it does
+
+Takes your API endpoint models and generates:
+
+- **Handler factories** (`handleCreateUser`, `handleGetPost`, etc.) — typed wrappers that enforce request/response types
+- **Runtime validators** — built from the schema, embedded in each handler
+- **TypeScript declarations** — `.d.ts` files with full context types (auth, WebSocket, HTTP)
+
+## Usage
+
+```typescript
+import { generateHandles } from '@lyku/lockstep-handles-ts';
+import * as models from '@myapp/api-models';
+
+await generateHandles({
+	models,
+	outputDir: 'dist/libs/handles/src',
+	modelsPackage: '@myapp/api-models',
+	typesPackage: '@myapp/api-types',
+	typesName: 'MyApiTypes',
+});
+```
+
+## Options
+
+| Option           | Type      | Default                          | Description                                        |
+| ---------------- | --------- | -------------------------------- | -------------------------------------------------- |
+| `models`         | `Record`  | required                         | Endpoint name to model map (non-handlers filtered) |
+| `outputDir`      | `string`  | required                         | Where to write generated files                     |
+| `modelsPackage`  | `string`  | required                         | Import path for API model definitions              |
+| `typesPackage`   | `string`  | required                         | Import path for generated request/response types   |
+| `contextPackage` | `string`  | `'@lyku/lockstep-core/contexts'` | Import path for handler context types              |
+| `typesName`      | `string`  | `'ApiTypes'`                     | Name of the aggregate types map                    |
+| `clean`          | `boolean` | `true`                           | Clean output directory before generating           |
+
+## Generated output
+
+For an endpoint `createUser`:
+
+```
+outputDir/
+  createUser.js      # Handler factory with embedded validator
+  createUser.d.ts    # TypeScript declaration
+  index.js           # Re-exports all handlers
+  index.d.ts         # Re-exports all types
+```
+
+The generated handler factory:
+
+```typescript
+import { handleCreateUser } from '@myapp/handles';
+
+export const createUser = handleCreateUser(async (request, context) => {
+	// request is typed as CreateUserRequest
+	// context includes auth, session, etc.
+	return { id: newUser.id };
+});
+```
+
+## Where it fits
+
+<!-- Generated from libs/lockstep-core/diagrams/pipeline.mmd — do not edit manually -->
+
+```mermaid
+graph TD
+    input-tables["Table Schemas<br/><small>PostgresRecordModel</small>"]
+    input-api["API Definitions<br/><small>TsonHandlerModel</small>"]
+
+    core-jsonmodels["generateJsonModels"]
+    core-dbtypes["generateDbTypes"]
+    core-apitypes["generateApiTypes"]
+    core-validators["buildValidator"]
+
+    handles-gen["generateHandles"]
+
+    client-gen["generateTsClient"]
+
+    pg-drift["detectDrift"]
+    pg-migrate["generateMigration"]
+
+    output-jsonschemas["JSON Schemas +<br/>TypeScript Types"]
+    output-kysely["Kysely Database<br/>Interface"]
+    output-reqres["Request / Response<br/>TypeScript Types"]
+    output-handlers["Handler Factories<br/>+ Validators"]
+    output-client["Type-safe<br/>HTTP Client"]
+    output-sql["SQL Migrations"]
+
+    input-tables --> core-jsonmodels
+    core-jsonmodels --> output-jsonschemas
+    output-jsonschemas --> core-dbtypes
+    core-dbtypes --> output-kysely
+
+    input-api --> core-apitypes
+    core-apitypes --> output-reqres
+    input-api --> core-validators
+
+    output-reqres --> handles-gen
+    input-api --> handles-gen
+    core-validators -.-> handles-gen
+    handles-gen --> output-handlers
+
+    output-reqres --> client-gen
+    input-api --> client-gen
+    client-gen --> output-client
+
+    input-tables --> pg-drift
+    pg-drift --> pg-migrate
+    pg-migrate --> output-sql
+
+    classDef highlight fill:#4f46e5,stroke:#3730a3,color:#fff,stroke-width:2px
+    classDef dimmed fill:#f1f5f9,stroke:#cbd5e1,color:#94a3b8,stroke-width:1px
+    classDef inputNode fill:#fef3c7,stroke:#f59e0b,color:#92400e,stroke-width:1px
+    classDef outputNode fill:#d1fae5,stroke:#10b981,color:#065f46,stroke-width:1px
+    classDef ownedOutput fill:#a5b4fc,stroke:#4f46e5,color:#1e1b4b,stroke-width:2px
+    classDef ownedInput fill:#fde68a,stroke:#4f46e5,color:#1e1b4b,stroke-width:2px
+    class handles-gen highlight
+    class core-jsonmodels,core-dbtypes,core-apitypes,core-validators,client-gen,pg-drift,pg-migrate dimmed
+    class input-tables inputNode
+    class output-jsonschemas,output-kysely,output-reqres,output-client,output-sql outputNode
+    class input-api ownedInput
+    class output-handlers ownedOutput
+```
+
+## Requirements
+
+Peer dependency on `@lyku/lockstep-core` (provides `buildValidator`, `stringifyBON`, `formatCode`, and `filterHandlerModels`).

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@lyku/lockstep-handles-ts",
-	"version": "1.0.0",
+	"version": "1.3.1",
 	"description": "Generate typed handler factories from TsonHandlerModel API definitions",
 	"type": "module",
 	"main": "./index.js",
@@ -23,6 +23,7 @@
 	"author": "Lyku",
 	"license": "GPL-3.0",
 	"devDependencies": {
+		"@lyku/lockstep-core": "1.3.1",
 		"typescript": "^5.0.0"
 	},
 	"module": "./src/index.js"