Skip to main content

content-mapper

Webda's compile-time code generation, as a TypeScript 7.1 content mapper.

TypeScript 7 removed custom emit transformers, ts-patch and language-service plugins. This package replaces them with the supported mechanism: it rewrites model and service sources (*.model.ts, *.service.ts) into ordinary TypeScript before the compiler sees them, with span maps so diagnostics, hover and rename still land on the authored text.

You rarely use it directly: webdac build (from @webda/compiler) runs it for you.

What it generates​

GeneratorOutput
accessorsTyped accessors that coerce on assignment (user.createdAt = "2020-01-01" stores a Date) and relations
behaviorsMembers of the Behaviors attached to a model
loadParametersloadParameters() for services extending Service<T>, from their parameters class
qlValidatorCompile-time validation of WebdaQLString<T> queries, reported as TypeScript diagnostics

It also discovers the Webda objects of a project and produces the JSON schemas of models, services and operations used in webda.module.json.

Editor support​

Register the mapper in tsconfig.json to see the generated members in your editor, without false errors when assigning a string to a Date field:

{
  "contentMappers": [{ "package": "@webda/content-mapper", "extensions": [".model.ts", ".service.ts"] }]
}

Content mappers run external code, so TypeScript asks you to trust them: tsc --runExternalCode on the command line, initializationOptions.runExternalCode for the language server.

A model or service declared in a file without the .model.ts / .service.ts suffix is never transformed: webdac build fails and names the file to rename (WEBDA_STRICT_FILE_NAMING=0 downgrades it to a warning while migrating).

Tests with Vitest​

The Vite plugin applies the same generators, so specs exercise the code webdac build emits:

vitest.config.ts
import { webdaContentMapper } from "@webda/content-mapper/vite";
import { defineConfig } from "vitest/config";

export default defineConfig({
  plugins: [webdaContentMapper()]
});

Entry points​

ExportUse
@webda/content-mapperGenerators, WarmSession, runTwoPass, schema generation
@webda/content-mapper/serverThe content mapper process started by TypeScript
@webda/content-mapper/viteThe webdaContentMapper() Vite/Vitest plugin
@webda/content-mapper/coercionsThe default coercion rules
@webda/content-mapper/schema-workerSchema generation in a worker thread

Requires TypeScript >=7.1.

See also​