@compilacion/ratchet

Author ratchet designs against a pinned domain-model version, and build them into self-contained TypeScript.

A ratchet is a thin wrapper around a generated builder (an entity.action event, or a whole eventGroup) where some inputs are pinned: the pinned fields disappear from the wrapper's parameters and are baked into the body. A ratchet only ever tightens — a pinned field can no longer be set downstream; everything left unpinned stays available.

The package bundles the domain model's runtimecontracts and TypeScript base builders, version-pinned to the release it was published from. That makes authoring model-aware and lets the build produce output that compiles on its own.

npm install @compilacion/ratchet
npm install @compilacion/colleciones-clientos   # peer dep (>=2.1.0) used by generated wrappers

30-second example

import { forModel } from '@compilacion/ratchet';

// 1. author (model-aware: the extends target AND the pinned input are validated)
const config = forModel('immoscoop', '0.1.0')
  .ratchet('haalbaarheidsattest', { version: '1.0' })
  .extend('ctaEngage', 'ctaEngageNew', { ctaId: '12' })
  .toJSON();

# 2. build into a self-contained folder of TypeScript
npx ratchet-build designs.json --out ./ratchet

# validate without building — point it at a file OR a whole folder (CI gate)
npx ratchet-build validate ./ratchets

Documentation

• Authoring a designs JSON — concepts, the fluent builder, hand-writing + the schema, validation, discovering extends/pins.
• Building into a package — the CLI, the output layout, self-containment, compiling and shipping it.
• Bundled models & versions — which domain models and versions this package is pinned to (auto-generated per release).

API at a glance

| Export | Purpose | | --- | --- | | forModel(name, version?) | Model-bound entry: .ratchet(), .validate(), .build(), .extendsTargets(), .pinnableKeys(), .model (version asserts the bundled contract) | | ratchet(name, opts, { model }) | Single-extend authoring builder (.extend(target, newName, input, enrichments), .toJSON(), .validate()) | | validateConfig(config) | { errors } — full validation that resolves the bundled model itself from meta.domainModel.modelName. Never throws | | validateDesigns(config, model) | { errors } — structural + extends + input + modelVersion (you supply the model) | | buildRatchetPackage(config, { outDir }) | Build a config into a self-contained folder | | availableModels() / loadModel(name) | List / load the bundled contracts | | ratchetDesignsSchema / validateStructure(config) | The JSON schema + a structural validator | | looksLikeRatchet(obj) | Cheap shape check (meta.domainModel + methods) — used by the folder scan |

CLI:

ratchet-build [build] <designs.json | dir> [--out <dir>]   build one ratchet, or every ratchet in a folder
ratchet-build validate <designs.json | dir>                validate only — writes nothing, exits 1 on any error

A directory is scanned recursively; non-ratchet .json (tsconfig, package.json, …) is skipped and reported. A folder build writes each ratchet into <out>/<meta.name>/.