@typfolio/dev-tools 0.2.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -17,23 +17,24 @@ try {
17
17
  }
18
18
  ```
19
19
 
20
- `check` also takes `assets`, the files a template reads besides its input (shared settings, a logo), exactly as a request's `assets`: a template that reads `json("/export-settings.json")` can be checked with that file in place.
20
+ `template` is a template made with `defineTemplate`. The check compiles only the files it declares, with each piece of data's JSON Schema at its `schemaPath`, made from its schema, so a file the template imports without declaring it fails, with what to do.
21
21
 
22
- `checkTemplate(template, { wasm, fonts, modes?, pdf?, assets? })` is the one-shot form that creates and disposes a checker.
22
+ `check` also takes `assets`, the files a template reads besides its data (a logo), exactly as `compile`'s `assets`. A JSON Schema file given there at a data path is used as it is instead of one made from the schema: this is how data without a schema, or a schema without Standard JSON Schema, is checked.
23
23
 
24
- `check` also takes a template made with `defineTemplate`: it compiles only the files the template declares, with each input's JSON Schema at its path, so a file the template imports without declaring it fails, with what to do.
24
+ `checkTemplate(template, { wasm, fonts, modes?, pdf?, assets? })` is the one-shot form that creates and disposes a checker.
25
25
 
26
- `inputSchemaFiles(definitions, { toJSONSchema? })` returns the JSON Schema file of every input of these templates, partials or `defineInput(...)` results, by path, as JSON text. It writes nothing: a script writes the files where the editor reads them, and a test compares them, so a schema that changed without its file fails CI. Schemas that implement Standard JSON Schema (`~standard.jsonSchema`, as Zod's do) need no option; for Zod Mini, pass `toJSONSchema: schema => z.toJSONSchema(schema, { io: 'input' })`.
26
+ `inputSchemaFiles(definitions, { toJSONSchema? })` returns the JSON Schema file of every piece of data these templates and partials read (nested partials included), or of `{ schema, schemaPath }` pairs, by path, as JSON text. It writes nothing: a script writes the files where the editor reads them, and a test compares them, so a schema that changed without its file fails CI. Schemas that implement Standard JSON Schema (`~standard.jsonSchema`, as Zod's do) need no option; for Zod Mini, pass `toJSONSchema: schema => z.toJSONSchema(schema, { io: 'input' })`.
27
27
 
28
28
  ```ts
29
29
  import { inputSchemaFiles } from '@typfolio/dev-tools';
30
30
 
31
- for (const [path, text] of Object.entries(inputSchemaFiles([headerInput, outcomesInput]))) {
31
+ // Every template's own schema file and each of its partials', once per path.
32
+ for (const [path, text] of Object.entries(inputSchemaFiles([outcomes, results]))) {
32
33
  assert.deepEqual(JSON.parse(await readFile(new URL(path, templatesRoot), 'utf8')), JSON.parse(text), `${path} is out of date`);
33
34
  }
34
35
  ```
35
36
 
36
- A check compiles the template once per sample mode (`minimal`, then `full`) the way an editor does, so `input()` builds a sample from the JSON Schema in `template.files`. A compile error is reported in that mode's result; a malformed template or option is thrown. Nothing is written to disk. See "Build-time checks" in [docs/template-authoring.md](../../docs/template-authoring.md) for the rules and a test recipe.
37
+ A check compiles the template once per sample mode (`minimal`, then `full`) the way an editor does, so `input()` builds a sample from the JSON Schema at each data path. A compile error is reported in that mode's result; a malformed template or option is thrown. Nothing is written to disk. See "Build-time checks" in [docs/template-authoring.md](../../docs/template-authoring.md) for the rules and a test recipe.
37
38
 
38
39
  ## `inspectPdf`
39
40
 
package/dist/index.d.ts CHANGED
@@ -1,4 +1,4 @@
1
- import { TypstPdfError, type CompilerOptions, type Diagnostic, type PartialDefinition, type PdfOptions, type PdfTemplate, type StandardSchemaV1, type TemplateDefinition, type TemplateInput } from '@typfolio/core';
1
+ import { TypstPdfError, type AnyTemplate, type Assets, type CompilerOptions, type Diagnostic, type PartialDefinition, type PdfOptions, type StandardSchemaV1 } from '@typfolio/core';
2
2
  /** Which sample `@local/typfolio`'s `input()` builds: every property, or only what the schema requires. */
3
3
  export type SampleMode = 'minimal' | 'full';
4
4
  export interface JSONSchemaOptions {
@@ -8,10 +8,15 @@ export interface JSONSchemaOptions {
8
8
  */
9
9
  toJSONSchema?(schema: StandardSchemaV1): unknown;
10
10
  }
11
- type Definition = TemplateDefinition<unknown, unknown> | PartialDefinition | TemplateInput;
11
+ /** A schema and the path its Typst file reads the data from, for a script that cannot import the definitions. */
12
+ export interface SchemaFile {
13
+ readonly schema: StandardSchemaV1;
14
+ readonly schemaPath: string;
15
+ }
16
+ type Definition = AnyTemplate | PartialDefinition | SchemaFile;
12
17
  /**
13
18
  * The JSON Schema file of each input of these templates, partials (nested ones included) or
14
- * `defineInput(...)` results, by its path, such as `common/header.schema.json`, as JSON text. Write
19
+ * `{ schema, schemaPath }` pairs, by its path, such as `common/header.schema.json`, as JSON text. Write
15
20
  * each next to the Typst files, where its `input(json.with("./header.schema.json"))` reads it in an
16
21
  * editor for a sample, and in a test compare the parsed files with these to catch a schema that
17
22
  * changed without its file. An input without a schema is left out. Nothing is written here.
@@ -20,14 +25,13 @@ export declare function inputSchemaFiles(definitions: Definition | readonly Defi
20
25
  export interface TemplateCheckOptions extends JSONSchemaOptions {
21
26
  /** Defaults to `['minimal', 'full']`. Each mode is a separate compile. */
22
27
  modes?: readonly SampleMode[];
23
- /** Same options as a request's `pdf`. */
28
+ /** Same options as `compile`'s `pdf`. */
24
29
  pdf?: PdfOptions;
25
30
  /**
26
- * Files the template reads besides its input, such as shared settings or a logo: same as a
27
- * request's `assets`. For a template made with `defineTemplate`, a schema file given here is used
28
- * as it is instead of one made from the input's schema.
31
+ * Files the template reads besides its data, such as a logo: as `compile`'s `assets`. A JSON Schema
32
+ * file given here at a data path is used as it is, instead of one made from the schema.
29
33
  */
30
- assets?: Readonly<Record<string, Uint8Array>>;
34
+ assets?: Assets;
31
35
  }
32
36
  export interface TemplateCheckResult {
33
37
  mode: SampleMode;
@@ -46,19 +50,18 @@ export interface TemplateCheckReport {
46
50
  }
47
51
  export interface TemplateChecker {
48
52
  /**
49
- * Compiles `template` once per mode in editor mode: no runtime marker, so `input()` reads the schema
50
- * from `template.files` (at the path its `json.with(...)` names, relative to the file that writes it)
51
- * and builds the sample. A template made with `defineTemplate` is compiled from the files it
52
- * declares only, with each input's JSON Schema at its path (see `inputSchemaFiles`): a file it
53
- * imports without declaring it fails, with what to do. A failed compile is reported in its result;
53
+ * Compiles `template` once per mode in editor mode: no runtime marker, so `input()` reads the JSON
54
+ * Schema at each data path (made from the schema, see `inputSchemaFiles`, or given in `assets`) and
55
+ * builds the sample. The template is compiled from the files it declares only: a file it imports
56
+ * without declaring it fails, with what to do. A failed compile is reported in its result;
54
57
  * a malformed template or option rejects with `INVALID_REQUEST` or `UNSUPPORTED_OPTION`.
55
58
  */
56
- check(template: PdfTemplate | TemplateDefinition<unknown, unknown>, options?: TemplateCheckOptions): Promise<TemplateCheckReport>;
59
+ check(template: AnyTemplate, options?: TemplateCheckOptions): Promise<TemplateCheckReport>;
57
60
  /** Stops accepting checks; waits for an accepted one and frees the compiler. */
58
61
  dispose(): Promise<void>;
59
62
  }
60
63
  /** Same options as `createCompiler`. One active check per checker. */
61
64
  export declare function createTemplateChecker(options: CompilerOptions): Promise<TemplateChecker>;
62
65
  /** One-shot form of `createTemplateChecker`: creates a checker, runs one check, disposes it. */
63
- export declare function checkTemplate(template: PdfTemplate | TemplateDefinition<unknown, unknown>, options: CompilerOptions & TemplateCheckOptions): Promise<TemplateCheckReport>;
66
+ export declare function checkTemplate(template: AnyTemplate, options: CompilerOptions & TemplateCheckOptions): Promise<TemplateCheckReport>;
64
67
  export {};
package/dist/index.js CHANGED
@@ -4,7 +4,7 @@ import { TypstPdfError, } from '@typfolio/core';
4
4
  import { bundledPackageDirectory, createEngine, explainCompileError, initialize, isTemplateDefinition, packageFileMounts, prepareRequest, resolveFonts, } from '@typfolio/core/internal';
5
5
  import { sampleFile, sampleSource } from './sample-source.generated.js';
6
6
  const sampleModes = ['minimal', 'full'];
7
- // Each input of these templates, partials and inputs, nested partials included, once per path.
7
+ // Each input of these templates, partials and schema files, nested partials included, once per path.
8
8
  function inputsOf(definitions) {
9
9
  const found = new Map();
10
10
  const add = (path, schema) => {
@@ -20,16 +20,16 @@ function inputsOf(definitions) {
20
20
  }
21
21
  else if (definition?.kind === 'typfolio-partial') {
22
22
  const partial = definition;
23
- visit(partial.input);
23
+ add(partial.schemaPath, partial.schema);
24
24
  for (const nested of Object.values(partial.partials))
25
25
  visit(nested);
26
26
  }
27
- else if (typeof definition?.path === 'string') {
28
- const input = definition;
29
- add(input.path.replace(/^\/+/, ''), input.schema);
27
+ else if (typeof definition?.schemaPath === 'string') {
28
+ const file = definition;
29
+ add(file.schemaPath.replace(/^\/+/, ''), file.schema);
30
30
  }
31
31
  else {
32
- throw new TypstPdfError('INVALID_REQUEST', 'Expected a defineTemplate(...), a definePartial(...) or a defineInput(...)');
32
+ throw new TypstPdfError('INVALID_REQUEST', 'Expected a defineTemplate(...), a definePartial(...) or { schema, schemaPath }');
33
33
  }
34
34
  };
35
35
  for (const definition of definitions)
@@ -46,7 +46,7 @@ function jsonSchemaOf(schema, path, options) {
46
46
  }
47
47
  /**
48
48
  * The JSON Schema file of each input of these templates, partials (nested ones included) or
49
- * `defineInput(...)` results, by its path, such as `common/header.schema.json`, as JSON text. Write
49
+ * `{ schema, schemaPath }` pairs, by its path, such as `common/header.schema.json`, as JSON text. Write
50
50
  * each next to the Typst files, where its `input(json.with("./header.schema.json"))` reads it in an
51
51
  * editor for a sample, and in a test compare the parsed files with these to catch a schema that
52
52
  * changed without its file. An input without a schema is left out. Nothing is written here.
@@ -78,22 +78,29 @@ function parseOptions(options) {
78
78
  throw new TypstPdfError('INVALID_REQUEST', 'toJSONSchema must be a function');
79
79
  return { modes, pdf, assets, ...(toJSONSchema === undefined ? {} : { toJSONSchema }) };
80
80
  }
81
- // A defined template as the editor sees it: its declared files, and each input's JSON Schema at its path.
81
+ // A template as the editor sees it: its declared files, and each input's JSON Schema at the path its data is read.
82
82
  function editorRequest(template, options) {
83
83
  const { pdf, assets } = options;
84
84
  if (!isTemplateDefinition(template))
85
- return { template, input: null, pdf, ...(assets === undefined ? {} : { assets }) };
86
- const encoder = new TextEncoder();
85
+ throw new TypstPdfError('INVALID_REQUEST', 'check takes a template made with defineTemplate');
86
+ // A JSON Schema is JSON: mounted like data, where `input(json.with(...))` reads it in the editor branch.
87
87
  const schemas = {};
88
+ const given = new Set(Object.keys(assets ?? {}).map(path => path.replace(/^\/+/, '')));
88
89
  for (const [path, schema] of inputsOf([template])) {
89
- if (assets?.[path] !== undefined)
90
+ if (given.has(path))
90
91
  continue;
91
92
  if (schema === undefined) {
92
- throw new TypstPdfError('INVALID_REQUEST', `The input at ${path} has no schema: give its JSON Schema file in assets`);
93
+ throw new TypstPdfError('INVALID_REQUEST', `The data at ${path} has no schema: give its JSON Schema file in assets`);
93
94
  }
94
- schemas[path] = encoder.encode(JSON.stringify(jsonSchemaOf(schema, path, options)));
95
+ schemas[path] = jsonSchemaOf(schema, path, options);
95
96
  }
96
- return { template: { entrypoint: template.entrypoint, files: template.files }, input: null, pdf, assets: { ...assets, ...schemas } };
97
+ return {
98
+ entrypoint: template.entrypoint,
99
+ files: template.files,
100
+ documents: schemas,
101
+ ...(assets === undefined ? {} : { assets }),
102
+ ...(pdf === undefined ? {} : { pdf }),
103
+ };
97
104
  }
98
105
  /** Same options as `createCompiler`. One active check per checker. */
99
106
  export async function createTemplateChecker(options) {
@@ -114,7 +121,6 @@ export async function createTemplateChecker(options) {
114
121
  if (busy)
115
122
  throw new TypstPdfError('BUSY', 'The template checker already has an active check');
116
123
  const { modes, ...rest } = parseOptions(checkOptions);
117
- // `input: null` only fills the reserved /input.json; the editor branch never reads it.
118
124
  const prepared = prepareRequest(editorRequest(template, rest));
119
125
  busy = true;
120
126
  let release;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@typfolio/dev-tools",
3
- "version": "0.2.0",
3
+ "version": "0.3.0",
4
4
  "description": "Dev-time tools for Typfolio templates: schema-based template checks and PDF inspection (install as a devDependency)",
5
5
  "type": "module",
6
6
  "license": "Apache-2.0",
@@ -24,7 +24,7 @@
24
24
  }
25
25
  },
26
26
  "dependencies": {
27
- "@typfolio/core": "^0.2.0"
27
+ "@typfolio/core": "^0.3.0"
28
28
  },
29
29
  "peerDependencies": {
30
30
  "pdfjs-dist": "^6.3.0"