@formfeed/devkit 0.2.0 → 0.3.1

package/types/lib/types/emit-python.d.ts

@@ -0,0 +1,6 @@
+import { type TemplateTypes } from './model.js';
+/**
+ * `formfeed_templates.py`: a TypedDict per template and `typed(client)`, whose `renders.create`
+ * overloads check `data` for the known slugs and fall back to the plain signature otherwise.
+ */
+export declare function emitPython(templates: TemplateTypes[]): string;

package/types/lib/types/emit-ts.d.cts

@@ -0,0 +1,10 @@
+import { type TemplateTypes } from './model.cjs';
+export interface TypeScriptOptions {
+    /** The module the generated file augments; `@formfeed/sdk` for customers. */
+    sdkModule?: string;
+}
+/**
+ * `formfeed.d.ts`: one data type per template plus the augmentation of `FormfeedTemplates`, which
+ * makes `renders.create({ template: 'invoice', data })` check `data` against `InvoiceData`.
+ */
+export declare function emitTypeScript(templates: TemplateTypes[], options?: TypeScriptOptions): string;

package/types/lib/types/emit-ts.d.ts

@@ -0,0 +1,10 @@
+import { type TemplateTypes } from './model.js';
+export interface TypeScriptOptions {
+    /** The module the generated file augments; `@formfeed/sdk` for customers. */
+    sdkModule?: string;
+}
+/**
+ * `formfeed.d.ts`: one data type per template plus the augmentation of `FormfeedTemplates`, which
+ * makes `renders.create({ template: 'invoice', data })` check `data` against `InvoiceData`.
+ */
+export declare function emitTypeScript(templates: TemplateTypes[], options?: TypeScriptOptions): string;

package/types/lib/types/index.d.cts

@@ -0,0 +1,15 @@
+import type { LocalTemplate } from '../project.cjs';
+import { type TypeScriptOptions } from './emit-ts.cjs';
+import { type TypeSource } from './model.cjs';
+export type TypesLanguage = 'ts' | 'python';
+export declare const defaultTypesFile: Record<TypesLanguage, string>;
+/**
+ * The schema of a template folder: `schema.json` when it has one, else inferred over all its data
+ * sets (a field only some sets carry is optional), marked as inferred so every field is optional.
+ */
+export declare function localTypeSource(tpl: LocalTemplate): TypeSource;
+/** The generated file for `sources` in `language`; the same input always gives the same bytes. */
+export declare function generateTypes(sources: TypeSource[], language: TypesLanguage, options?: TypeScriptOptions): string;
+export { buildTypes, pascalCase, relaxRequired, singular } from './model.cjs';
+export type { SchemaOrigin, TemplateTypes, TypeNode, TypeSource } from './model.cjs';
+export type { TypeScriptOptions } from './emit-ts.cjs';

package/types/lib/types/index.d.ts

@@ -0,0 +1,15 @@
+import type { LocalTemplate } from '../project.js';
+import { type TypeScriptOptions } from './emit-ts.js';
+import { type TypeSource } from './model.js';
+export type TypesLanguage = 'ts' | 'python';
+export declare const defaultTypesFile: Record<TypesLanguage, string>;
+/**
+ * The schema of a template folder: `schema.json` when it has one, else inferred over all its data
+ * sets (a field only some sets carry is optional), marked as inferred so every field is optional.
+ */
+export declare function localTypeSource(tpl: LocalTemplate): TypeSource;
+/** The generated file for `sources` in `language`; the same input always gives the same bytes. */
+export declare function generateTypes(sources: TypeSource[], language: TypesLanguage, options?: TypeScriptOptions): string;
+export { buildTypes, pascalCase, relaxRequired, singular } from './model.js';
+export type { SchemaOrigin, TemplateTypes, TypeNode, TypeSource } from './model.js';
+export type { TypeScriptOptions } from './emit-ts.js';

package/types/lib/types/model.d.cts

@@ -0,0 +1,81 @@
+/**
+ * The language-neutral model `formfeed types` emits from (spec 19 §2.4): each template's data schema
+ * becomes a tree of type nodes plus the named objects it refers to, so the TypeScript and Python
+ * emitters share one reading of JSON Schema and differ only in spelling.
+ */
+export type TypeNode = {
+    kind: 'unknown';
+    note?: string;
+} | {
+    kind: 'never';
+} | {
+    kind: 'primitive';
+    name: 'string' | 'number' | 'integer' | 'boolean' | 'null';
+} | {
+    kind: 'literal';
+    value: string | number | boolean | null;
+} | {
+    kind: 'array';
+    items: TypeNode;
+} | {
+    kind: 'record';
+    values: TypeNode;
+} | {
+    kind: 'ref';
+    name: string;
+} | {
+    kind: 'union';
+    members: TypeNode[];
+} | {
+    kind: 'intersection';
+    members: TypeNode[];
+};
+export interface Field {
+    key: string;
+    type: TypeNode;
+    required: boolean;
+    doc: string[];
+}
+export interface NamedObject {
+    name: string;
+    doc: string[];
+    fields: Field[];
+    /** Type of properties the schema does not list, when `additionalProperties` is a schema. */
+    extra: TypeNode | null;
+}
+/** Where a template's schema came from; the header of the generated file says it per template. */
+export type SchemaOrigin = 'local' | 'stored' | 'inferred';
+export interface TypeSource {
+    slug: string;
+    schema: Record<string, unknown>;
+    origin: SchemaOrigin;
+    /** The version the schema belongs to, for the header. */
+    version?: number | null;
+    channel?: string | null;
+}
+export interface TemplateTypes {
+    slug: string;
+    origin: SchemaOrigin;
+    version: number | null;
+    channel: string | null;
+    /** The name the data type is exported under (`InvoiceData`). */
+    rootName: string;
+    /** The data type; a `ref` to `rootName` when the schema is an object. */
+    root: TypeNode;
+    /** Named objects in the order they were first met, the root first. */
+    objects: NamedObject[];
+}
+export declare function pascalCase(text: string): string;
+/** `items` → `Item`, `addresses` → `Address`, `entries` → `Entry`; null when the word is not a plural. */
+export declare function singular(word: string): string | null;
+/** Names already handed out in one generated file; a clash gets a number. */
+export declare class NameRegistry {
+    private readonly used;
+    constructor(reserved?: Iterable<string>);
+    claim(wanted: string): string;
+}
+/** An inferred schema knows which fields the sample had, not which the template needs: all optional. */
+export declare function relaxRequired(schema: unknown): unknown;
+/** Builds the model for a set of templates; names are unique across the whole file. */
+export declare function buildTypes(sources: TypeSource[], reserved?: Iterable<string>): TemplateTypes[];
+export declare function originNote(t: Pick<TemplateTypes, 'origin' | 'version' | 'channel'>): string;

package/types/lib/types/model.d.ts

@@ -0,0 +1,81 @@
+/**
+ * The language-neutral model `formfeed types` emits from (spec 19 §2.4): each template's data schema
+ * becomes a tree of type nodes plus the named objects it refers to, so the TypeScript and Python
+ * emitters share one reading of JSON Schema and differ only in spelling.
+ */
+export type TypeNode = {
+    kind: 'unknown';
+    note?: string;
+} | {
+    kind: 'never';
+} | {
+    kind: 'primitive';
+    name: 'string' | 'number' | 'integer' | 'boolean' | 'null';
+} | {
+    kind: 'literal';
+    value: string | number | boolean | null;
+} | {
+    kind: 'array';
+    items: TypeNode;
+} | {
+    kind: 'record';
+    values: TypeNode;
+} | {
+    kind: 'ref';
+    name: string;
+} | {
+    kind: 'union';
+    members: TypeNode[];
+} | {
+    kind: 'intersection';
+    members: TypeNode[];
+};
+export interface Field {
+    key: string;
+    type: TypeNode;
+    required: boolean;
+    doc: string[];
+}
+export interface NamedObject {
+    name: string;
+    doc: string[];
+    fields: Field[];
+    /** Type of properties the schema does not list, when `additionalProperties` is a schema. */
+    extra: TypeNode | null;
+}
+/** Where a template's schema came from; the header of the generated file says it per template. */
+export type SchemaOrigin = 'local' | 'stored' | 'inferred';
+export interface TypeSource {
+    slug: string;
+    schema: Record<string, unknown>;
+    origin: SchemaOrigin;
+    /** The version the schema belongs to, for the header. */
+    version?: number | null;
+    channel?: string | null;
+}
+export interface TemplateTypes {
+    slug: string;
+    origin: SchemaOrigin;
+    version: number | null;
+    channel: string | null;
+    /** The name the data type is exported under (`InvoiceData`). */
+    rootName: string;
+    /** The data type; a `ref` to `rootName` when the schema is an object. */
+    root: TypeNode;
+    /** Named objects in the order they were first met, the root first. */
+    objects: NamedObject[];
+}
+export declare function pascalCase(text: string): string;
+/** `items` → `Item`, `addresses` → `Address`, `entries` → `Entry`; null when the word is not a plural. */
+export declare function singular(word: string): string | null;
+/** Names already handed out in one generated file; a clash gets a number. */
+export declare class NameRegistry {
+    private readonly used;
+    constructor(reserved?: Iterable<string>);
+    claim(wanted: string): string;
+}
+/** An inferred schema knows which fields the sample had, not which the template needs: all optional. */
+export declare function relaxRequired(schema: unknown): unknown;
+/** Builds the model for a set of templates; names are unique across the whole file. */
+export declare function buildTypes(sources: TypeSource[], reserved?: Iterable<string>): TemplateTypes[];
+export declare function originNote(t: Pick<TemplateTypes, 'origin' | 'version' | 'channel'>): string;