The TypeScript layer (@skmtc/lang-typescript)

Read skmtc-generator first; you will normally have copied the skmtc-model skeleton (model generators — load that skill) or cloned @skmtc/gen-tanstack-query-fetch-zod (operation) — those are the worked examples. This skill carries the rules that aren't visible from imitation alone.

1. Declaring the language

The declaration is the import graph — no lang config field exists. src/base.ts imports a factory; the returned class extends TsSnippet, which carries the static lang Drivers read pre-construction.

import { toTsModelProjectionBase } from '@skmtc/lang-typescript'

export const MyBase = toTsModelProjectionBase<EnrichmentSchema>({
  id: denoJson.name,
  toIdentifierName({ refName }) { return decapitalize(camelCase(refName)) },
  toIdentifierType: () => ({ type: 'variable' }),
  toExportPath({ refName, enrichments, variant }) {
    const name = this.toIdentifierName({ refName, enrichments, variant })
    return `@/types/${name}.generated.ts`   // '@/' is basePath; always forward slashes
  },
  toEnrichmentSchema
})

Factories: toTsModelProjectionBase, toTsOasOperationProjectionBase (+ webhook/GQL variants). Snippets extend TsSnippet directly. Casing helpers (camelCase, capitalize, decapitalize) and toEndpointName come from @skmtc/core. An export path is @/ plus a forward-slash path relative to basePath; write it as a template literal, never with a path-library join, which would use the host's separator (backslashes on Windows) inside generated import text.

The veneers take two type parameters: EnrichmentType and ProjectionOptions, the caller options a peer passes as { options } on an insert (skmtc-generator §4). Declare the second to accept options; toIdentifierName / toExportPath then receive options and the instance stores it as this.options:

import { toTsModelProjectionBase } from '@skmtc/lang-typescript'

type ShapeOptions = { suffix: 'Input' | 'Output' }

export const MyBase = toTsModelProjectionBase<EnrichmentSchema, ShapeOptions>({
  id: denoJson.name,
  toIdentifierName({ refName, options }) { return `${camelCase(refName)}${options.suffix}` },
  toIdentifierType: () => ({ type: 'variable' }),
  toExportPath({ refName, enrichments, variant, options }) {
    const name = this.toIdentifierName({ refName, enrichments, variant, options })
    return `@/types/${name}.generated.ts`
  },
  toEnrichmentSchema
})

Consuming a peer that declares options needs nothing from this layer: this.insertModel(Peer, refName, { options }).

A projection consumable by peers via insertNormalizedModel also needs two statics: schemaToValueFn (your router) and createIdentifier.

2. The three register shapes

Caller	Call	Destination
Projection	this.register(args)	its own export file
Projection	this.registerInto(path, args)	explicit file
Snippet	this.register({ ...args, destinationPath })	required — snippets own no file

Free functions for transform-level code: register(context, args); defineAndRegister(context, { identifier, value, destinationPath }) — no cache check (pair with context.findDefinition for the accumulator get-or-create idiom). Args: { imports?: Record<module, ImportNameArg[]>, reExports?, definitions?, custom? }. register creates the file on first write and drops self-imports, so register imports unconditionally — per-leaf registration (every snippet needing z registers { zod: ['z'] }) is the correct pattern, and merging is idempotent. An imports key spelled from the workspace root (@/, ./, /) is an export path; any other key (zod, types/y.ts) is a module specifier, written as it is.

3. Identifier kinds

TypeScript output has five entity kinds — TsEntityType = 'variable' | 'type' | 'class' | 'interface' | 'namespace' — factories createVariable(name, { typeName? }), createType, createClass, createInterface, createNamespace. No 'function' kind: a generated function is a variable whose value renders as an arrow function. The engine's identifier type is an opaque string; isTsEntityType narrows it to the five above. ContentSettings.identifier is the neutral IdentifierBase; toTsIdentifier(identifier) narrows it back to the TsIdentifier a reExports entry needs (a barrel: registerInto(barrelPath, { reExports: { [exportPath]: [toTsIdentifier(settings.identifier)] } })).

toIdentifierType is one lever with three effects: declaration keyword; block form (class/interface/namespace take no = value;); and whether consumers import it type-only (type and interface do — this is what keeps consumers compiling under verbatimModuleSyntax/TS1484, and you get it by choosing the kind, never by writing import syntax). File dedup keys on keyword+name, so class Foo + namespace Foo coexist (declaration merging); first write wins per slot.

4. Emitted-import rules

Concise forms per module: ['z'] (named), [{ default: 'invariant' }] (aliased/default), [{ name: 'User', type: 'type' }] (type-only). Sharp edge: only type: 'type' triggers type-only in the concise form — type: 'interface' does NOT; tag interfaces type: 'type'. Register against @/… export paths, where @/ is the workspace root. At render TsFile re-keys each module through settings.packages: same package → @/ from that package's root; another package → the innermost root's moduleName; no root → as written. A package file that imports a workspace-root path under no root throws at render.

5. Composition helpers

All Stringable, all deferring joins to render — use them instead of array.join whenever items are snippets (joining pre-renders and orphans provenance):

• List — List.toObject/toArray/toParams/toLines/toKeyValue, List.fromKeys(record).toObject(fn), new List(values, { separator, bookends, skipEmpty }).
• FunctionParameter({ typeDefinition, destructure, required, skipEmpty }) — one object, four readings: toString() (declaration), toInbound() (call site), toPropertyList(), hasProperty(name).
• toPathTemplate('/users/{id}') → /users/${id}; toPathParams → /users/:id; PathParams bundles type + parameter + template.
• keyValues, withDescription, handleKey, handlePropertyName; TsClass/TsHeritage for class syntax (TsHeritage registers its own heritage imports).

6. Sanitizing emitted names

Two different questions: sanitizeIdentifier(name) for binding names (export const <name>; repairs '2fa' → '_2fa', reserved → suffixed) vs sanitizePropertyName(name) for property keys / destructuring (returns a rename pair when repair is needed). Never hand-roll keyword lists.

7. Files

Render order: custom banner → re-exports → imports → definitions; first-wins per definition slot makes output order-independent. You almost never construct TsFile/TsImport/TsDefinition yourself — register and the Drivers do.

8. The contrast that matters

// WRONG: stored rendered text — z import never registers, refs duplicate
this.properties[key] = `z.string().optional()`
// RIGHT: stored snippet — imports settle, cache sees it, provenance holds
this.properties[key] = toMyValue({ schema: propSchema, required, destinationPath, context })

A cached peer name is a legitimate string — minding the two insert return shapes: this.responseName = definition.identifier.name from insertNormalizedModel, or .toName() off insertModel's Inserted handle. Modifier pipelines (applyModifiers-style) run inside toString(), never to build stored fields.

9. TypeScript pitfalls

Symptom	Fix
TS1484 in consumers	Identifier kind type/interface; concise imports need type: 'type'
Interface import emitted as value	Tag it type: 'type' (known concise-form gap)
TS7022/7024 on recursive schemas	Set settings.identifier.typeName (e.g. z.ZodType<X>) post-construction; the name stays stable
Provenance holes under some nodes	toString must be a prototype method, never an arrow field
Doubled ?/modifiers	One owner: apply modifiers once, at the leaf's render