@pepys/kit 0.0.0-stage → 0.0.1

package/src/generators/collect-view-kinds.ts

@@ -0,0 +1,8 @@
+import type { ConsumerDeclaration } from '../consumers/types.ts';
+import type { EntityKind } from '../link-types/types.ts';
+
+// The ID column of an entity view holds IDs of the view's kind, keyed `<table>.<column>`. Any other
+// entityID column holds an ID of any kind, because a column declares no kind.
+export function collectViewKinds(consumer: ConsumerDeclaration): ReadonlyMap<string, EntityKind> {
+  return new Map(consumer.entityViews.map((view) => [`${view.table}.${view.id}`, view.kind]));
+}

package/src/generators/format-column-type.ts

@@ -0,0 +1,16 @@
+import { match } from 'ts-pattern';
+import type { EntityKind } from '../link-types/types.ts';
+import type { ColumnDeclaration } from '../types.ts';
+import { toEntityIDTypeName } from './to-entity-id-type-name.ts';
+
+export function formatColumnType(column: ColumnDeclaration, kind: EntityKind | undefined): string {
+  const type = match(column.kind)
+    .with('text', 'timestamp', () => 'string')
+    .with('integer', 'real', () => 'number')
+    .with('boolean', () => 'boolean')
+    .with('json', () => 'unknown')
+    .with('entityID', () => (kind === undefined ? 'EntityID' : toEntityIDTypeName(kind)))
+    .exhaustive();
+
+  return column.nullable === true && column.kind !== 'json' ? `${type} | null` : type;
+}

package/src/generators/format-entity-ids.ts

@@ -0,0 +1,46 @@
+import type { EntityKind } from '../link-types/types.ts';
+import { formatLiteral } from './format-literal.ts';
+import { toEntityIDTypeName } from './to-entity-id-type-name.ts';
+
+// The glue brands IDs with its own symbols: scriptc refuses a type-fest import, and a brand whose
+// tag is `string` and not a literal. So a kinded ID is an EntityID with a second, literal tag.
+export function formatEntityIDs(kinds: readonly EntityKind[]): string[] {
+  return [
+    [
+      'declare const idTag: unique symbol;',
+      'declare const kindTag: unique symbol;',
+      '',
+      "export type EntityID = string & { readonly [idTag]: 'EntityID' };",
+      '',
+      'type KindedID<Kind extends string> = EntityID & { readonly [kindTag]: Kind };',
+    ].join('\n'),
+    ...kinds.map((kind) => formatKindedID(kind)),
+  ];
+}
+
+function formatKindedID(kind: EntityKind): string {
+  const name = toEntityIDTypeName(kind);
+  const prefix = formatLiteral(`${kind}:`);
+
+  return [
+    `export type ${name} = KindedID<${formatLiteral(kind)}>;`,
+    '',
+    `export function to${name}(id: string): ${name} {`,
+    `  const text = ${prefix} + id;`,
+    '',
+    `  if (!is${name}(text)) {`,
+    `    throw new Error(${formatLiteral(`an ID of the kind ${kind} is never empty`)});`,
+    '  }',
+    '',
+    '  return text;',
+    '}',
+    '',
+    `export function parse${name}(text: string): ${name} | undefined {`,
+    `  return is${name}(text) ? text : undefined;`,
+    '}',
+    '',
+    `function is${name}(text: string): text is ${name} {`,
+    `  return text.length > ${prefix}.length && text.startsWith(${prefix});`,
+    '}',
+  ].join('\n');
+}

package/src/generators/format-fact-reader.ts

@@ -0,0 +1,194 @@
+import type { z } from 'zod';
+import type { ConsumerInput } from '../consumers/types.ts';
+import type { FactFamily } from '../sources/types.ts';
+import { buildPayloadShape } from './build-payload-shape.ts';
+import { formatLiteral } from './format-literal.ts';
+import { formatPayloadShape } from './format-payload-shape.ts';
+import type { FormattedShape } from './format-payload-shape.ts';
+import { toEntityIDTypeName } from './to-entity-id-type-name.ts';
+import { toPascalCase } from './to-pascal-case.ts';
+
+interface FactReaderParameters {
+  consumerName: string;
+  input: ConsumerInput;
+
+  // the families on the consumer's streams
+  families: readonly FactFamily[];
+}
+
+// The fact union of the consumer's streams, its decoder, and the read: `readScopeFacts` in scope
+// mode, `parse<Consumer>Fact` in fact mode. A fact whose type no family declares, or whose payload
+// does not decode, reads as no fact.
+export function formatFactReader(parameters: FactReaderParameters): string[] {
+  const fact = `${parameters.consumerName}Fact`;
+  const groups = collectPayloadGroups(parameters.families);
+
+  const members = groups.map((group) => ({
+    types: group.types,
+    payload: formatPayloadShape(
+      buildPayloadShape(group.schema),
+      `${toPascalCase(pickPayloadName(group.types))}Payload`,
+    ),
+  }));
+
+  return [
+    ...members.flatMap((member) => member.payload.interfaces),
+    formatFactUnion(fact, members),
+    ...formatRead(fact, parameters.input),
+    formatFactDecoder(fact, members),
+    ...members.flatMap((member) => member.payload.decoders),
+  ];
+}
+
+interface PayloadGroup {
+  schema: z.ZodType;
+  types: string[];
+}
+
+// Fact types that share one schema share one payload type and one decoder.
+function collectPayloadGroups(families: readonly FactFamily[]): PayloadGroup[] {
+  const groups = new Map<z.ZodType, string[]>();
+
+  for (const family of families) {
+    for (const [type, schema] of Object.entries(family.types)) {
+      groups.set(schema, [...(groups.get(schema) ?? []), type]);
+    }
+  }
+
+  return [...groups].map(([schema, types]) => ({ schema, types }));
+}
+
+// Types that share a schema share the dotted prefix of their names, such as `github.pull_request`
+// for every action of a pull request delivery.
+function pickPayloadName(types: readonly string[]): string {
+  const [first = [], ...rest] = types.map((type) => type.split('.'));
+  const end = first.findIndex((part, index) => rest.some((other) => other[index] !== part));
+  const shared = end === -1 ? first : first.slice(0, end);
+
+  return shared.length > 0 ? shared.join('.') : (types[0] ?? '');
+}
+
+interface FactMember {
+  types: readonly string[];
+  payload: FormattedShape;
+}
+
+function formatFactUnion(fact: string, members: readonly FactMember[]): string {
+  if (members.length === 0) {
+    return `export type ${fact} = never;`;
+  }
+
+  const lines = members.map(
+    (member) =>
+      `  | { id: string; type: ${formatTypeUnion(member.types)}; entity: string; at: string; payload: ${member.payload.type} }`,
+  );
+
+  return [`export type ${fact} =`, ...lines].join('\n').concat(';');
+}
+
+function formatTypeUnion(types: readonly string[]): string {
+  return types.map((type) => formatLiteral(type)).join(' | ');
+}
+
+function formatRead(fact: string, input: ConsumerInput): string[] {
+  if (input.mode === 'fact') {
+    return [
+      [
+        `export function parse${fact}(factJSON: string): ${fact} | undefined {`,
+        '  const parsed: unknown = JSON.parse(factJSON);',
+        '',
+        `  return decode${fact}(parsed);`,
+        '}',
+      ].join('\n'),
+    ];
+  }
+
+  const scope = toEntityIDTypeName(input.scopeKind);
+
+  return [
+    [
+      'declare function readScopeFactsLength(scope: string): number;',
+      'declare function readScopeFactsInto(scope: string, facts: Uint8Array): void;',
+    ].join('\n'),
+    [
+      "// every fact of the scope on the consumer's streams, one per fact ID, in the host's order",
+      `export function readScopeFacts(scope: ${scope}): ${fact}[] {`,
+      '  const buffer = new Uint8Array(readScopeFactsLength(scope));',
+      '',
+      '  readScopeFactsInto(scope, buffer);',
+      '',
+      '  const parsed: unknown = JSON.parse(new TextDecoder().decode(buffer));',
+      `  const facts: ${fact}[] = [];`,
+      '',
+      '  if (!Array.isArray(parsed)) {',
+      '    return facts;',
+      '  }',
+      '',
+      '  for (let index = 0; index < parsed.length; index += 1) {',
+      `    const decoded = decode${fact}(parsed[index]);`,
+      '',
+      '    if (decoded !== undefined) {',
+      '      facts.push(decoded);',
+      '    }',
+      '  }',
+      '',
+      '  return facts;',
+      '}',
+    ].join('\n'),
+  ];
+}
+
+function formatFactDecoder(fact: string, members: readonly FactMember[]): string {
+  const parameter = members.length === 0 ? '_value' : 'value';
+
+  const branches = members.flatMap((member) => [
+    `  if (${member.types.map((type) => `type === ${formatLiteral(type)}`).join(' || ')}) {`,
+    ...formatPayloadDecode(member.payload),
+    '    return { id, type, entity, at, payload: decoded };',
+    '  }',
+    '',
+  ]);
+
+  const body =
+    members.length === 0
+      ? []
+      : [
+          "  if (typeof value !== 'object' || value === null || Array.isArray(value)) {",
+          '    return undefined;',
+          '  }',
+          '',
+          "  const id = 'id' in value ? value.id : undefined;",
+          "  const type = 'type' in value ? value.type : undefined;",
+          "  const entity = 'entity' in value ? value.entity : undefined;",
+          "  const at = 'at' in value ? value.at : undefined;",
+          "  const payload = 'payload' in value ? value.payload : undefined;",
+          '',
+          "  if (typeof id !== 'string' || typeof entity !== 'string' || typeof at !== 'string') {",
+          '    return undefined;',
+          '  }',
+          '',
+          ...branches,
+        ];
+
+  return [
+    `function decode${fact}(${parameter}: unknown): ${fact} | undefined {`,
+    ...body,
+    '  return undefined;',
+    '}',
+  ].join('\n');
+}
+
+function formatPayloadDecode(payload: FormattedShape): string[] {
+  if (!payload.canFail) {
+    return ['    const decoded = payload;', ''];
+  }
+
+  return [
+    `    const decoded = ${payload.decode('payload')};`,
+    '',
+    '    if (decoded === undefined) {',
+    '      return undefined;',
+    '    }',
+    '',
+  ];
+}

package/src/generators/format-literal.ts

@@ -0,0 +1,13 @@
+// A TypeScript literal in single quotes, the quote style of the rest of the glue.
+export function formatLiteral(value: string | number | boolean): string {
+  if (typeof value !== 'string') {
+    return String(value);
+  }
+
+  const escaped = JSON.stringify(value)
+    .slice(1, -1)
+    .replaceAll(String.raw`\"`, '"')
+    .replaceAll("'", String.raw`\'`);
+
+  return `'${escaped}'`;
+}

package/src/generators/format-model-contract.ts

@@ -0,0 +1,23 @@
+// scriptc attests a library whose entry exports a model type, a message union tagged by `kind`,
+// `init` and `update`. It takes the types through a re-export but not the functions, so the entry
+// declares `init` and `update` and calls these two.
+export function formatModelContract(consumerName: string): string {
+  const model = `${consumerName}Model`;
+  const message = `${consumerName}Message`;
+
+  return [
+    `export interface ${model} {`,
+    '  input: string;',
+    '}',
+    '',
+    `export type ${message} = { kind: 'apply'; input: string } | { kind: 'reset' };`,
+    '',
+    `export function init${model}(): ${model} {`,
+    "  return { input: '' };",
+    '}',
+    '',
+    `export function update${model}(model: ${model}, message: ${message}): ${model} {`,
+    `  return message.kind === 'reset' ? init${model}() : { ...model, input: message.input };`,
+    '}',
+  ].join('\n');
+}

package/src/generators/format-operations.ts

@@ -0,0 +1,109 @@
+import type { ConsumerDeclaration } from '../consumers/types.ts';
+import type { EntityKind, LinkTypeDeclaration } from '../link-types/types.ts';
+import type { ColumnDeclaration, TableDeclaration } from '../types.ts';
+import { collectViewKinds } from './collect-view-kinds.ts';
+import { formatColumnType } from './format-column-type.ts';
+import { formatLiteral } from './format-literal.ts';
+import { formatPropertyName } from './format-property-name.ts';
+import { toEntityIDTypeName } from './to-entity-id-type-name.ts';
+import { toPascalCase } from './to-pascal-case.ts';
+
+// The row and key type of each table, the link of each link type, the operation union, and one
+// constructor per link type. A delete and an unlink are fact mode only.
+export function formatOperations(consumer: ConsumerDeclaration): string[] {
+  const consumerName = toPascalCase(consumer.name);
+  const isFactMode = consumer.input.mode === 'fact';
+  const tables = Object.entries(consumer.tables);
+  const columnKinds = collectViewKinds(consumer);
+
+  return [
+    ...tables.map(([name, table]) =>
+      formatRecord(`${toPascalCase(name)}Row`, Object.entries(table.columns), columnKinds, name),
+    ),
+    ...(isFactMode
+      ? tables.map(([name, table]) =>
+          formatRecord(`${toPascalCase(name)}Key`, collectKey(table), columnKinds, name),
+        )
+      : []),
+    formatOperationUnion(consumerName, consumer, isFactMode),
+    ...consumer.links.map((link) => formatLinkConstructor(consumerName, link)),
+    ...(isFactMode
+      ? consumer.links.map((link) => formatUnlinkConstructor(consumerName, link))
+      : []),
+  ];
+}
+
+function formatRecord(
+  typeName: string,
+  columns: readonly (readonly [string, ColumnDeclaration])[],
+  columnKinds: ReadonlyMap<string, EntityKind>,
+  tableName: string,
+): string {
+  const fields = columns.map(
+    ([name, column]) =>
+      `  ${formatPropertyName(name)}: ${formatColumnType(column, columnKinds.get(`${tableName}.${name}`))};`,
+  );
+
+  return [`export interface ${typeName} {`, ...fields, '}'].join('\n');
+}
+
+function collectKey(table: TableDeclaration): [string, ColumnDeclaration][] {
+  return table.primaryKey.flatMap((name) => {
+    const column = table.columns[name];
+
+    return column === undefined ? [] : [[name, column]];
+  });
+}
+
+function formatOperationUnion(
+  consumerName: string,
+  consumer: ConsumerDeclaration,
+  isFactMode: boolean,
+): string {
+  const tableMembers = Object.keys(consumer.tables).flatMap((name) => {
+    const key = formatPropertyName(name);
+    const upsert = `  | { upsert: { ${key}: ${toPascalCase(name)}Row } }`;
+
+    return isFactMode ? [upsert, `  | { delete: { ${key}: ${toPascalCase(name)}Key } }`] : [upsert];
+  });
+
+  const linkMembers = consumer.links.flatMap((link) => {
+    const type = formatLiteral(link.name);
+    const ends = `from: ${formatEndType(link.from)}; to: ${formatEndType(link.to)}`;
+    const linkMember = `  | { link: { type: ${type}; ${ends}; confidence: number; evidence: string } }`;
+
+    return isFactMode ? [linkMember, `  | { unlink: { type: ${type}; ${ends} } }`] : [linkMember];
+  });
+
+  const members = [...tableMembers, ...linkMembers];
+
+  if (members.length === 0) {
+    return `export type ${consumerName}Operation = never;`;
+  }
+
+  return `${[`export type ${consumerName}Operation =`, ...members].join('\n')};`;
+}
+
+function formatEndType(kinds: readonly EntityKind[]): string {
+  return kinds.map((kind) => toEntityIDTypeName(kind)).join(' | ');
+}
+
+function formatLinkConstructor(consumerName: string, link: LinkTypeDeclaration): string {
+  const ends = `from: ${formatEndType(link.from)}; to: ${formatEndType(link.to)}`;
+
+  return [
+    `export function link${toPascalCase(link.name)}(link: { ${ends}; confidence: number; evidence: string }): ${consumerName}Operation {`,
+    `  return { link: { type: ${formatLiteral(link.name)}, from: link.from, to: link.to, confidence: link.confidence, evidence: link.evidence } };`,
+    '}',
+  ].join('\n');
+}
+
+function formatUnlinkConstructor(consumerName: string, link: LinkTypeDeclaration): string {
+  const ends = `from: ${formatEndType(link.from)}; to: ${formatEndType(link.to)}`;
+
+  return [
+    `export function unlink${toPascalCase(link.name)}(link: { ${ends} }): ${consumerName}Operation {`,
+    `  return { unlink: { type: ${formatLiteral(link.name)}, from: link.from, to: link.to } };`,
+    '}',
+  ].join('\n');
+}

package/src/generators/format-payload-shape.ts

@@ -0,0 +1,181 @@
+import { match } from 'ts-pattern';
+import type { PayloadField, PayloadShape } from './build-payload-shape.ts';
+import { formatLiteral } from './format-literal.ts';
+import { formatPropertyAccess } from './format-property-access.ts';
+import { formatPropertyName } from './format-property-name.ts';
+import { toPascalCase } from './to-pascal-case.ts';
+
+// The glue's type for one payload shape, the expression that decodes an `unknown` identifier into
+// it (or `undefined` when the value does not fit), and the interfaces and decoders it needs.
+export interface FormattedShape {
+  type: string;
+  decode: (identifier: string) => string;
+  canFail: boolean;
+  interfaces: readonly string[];
+  decoders: readonly string[];
+}
+
+export function formatPayloadShape(shape: PayloadShape, name: string): FormattedShape {
+  return match(shape)
+    .with({ kind: 'string' }, { kind: 'number' }, { kind: 'boolean' }, (primitive) => ({
+      type: primitive.kind,
+      decode: (identifier: string) =>
+        `typeof ${identifier} === '${primitive.kind}' ? ${identifier} : undefined`,
+      canFail: true,
+      interfaces: [],
+      decoders: [],
+    }))
+    .with({ kind: 'literal' }, (literal) => {
+      const values = literal.values.map((value) => formatLiteral(value));
+
+      return {
+        type: values.join(' | '),
+        decode: (identifier: string) =>
+          `${values.map((value) => `${identifier} === ${value}`).join(' || ')} ? ${identifier} : undefined`,
+        canFail: true,
+        interfaces: [],
+        decoders: [],
+      };
+    })
+    .with({ kind: 'nullable' }, (nullable) => {
+      const inner = formatPayloadShape(nullable.inner, name);
+
+      return {
+        type: `${inner.type} | null`,
+        decode: (identifier: string) =>
+          `${identifier} === null ? null : ${inner.decode(identifier)}`,
+        canFail: inner.canFail,
+        interfaces: inner.interfaces,
+        decoders: inner.decoders,
+      };
+    })
+    .with({ kind: 'object' }, (object) => formatObjectShape(object.fields, name))
+    .with({ kind: 'array' }, (array) => formatArrayShape(array.element, name))
+    .with({ kind: 'unknown' }, () => ({
+      type: 'unknown',
+      decode: (identifier: string) => identifier,
+      canFail: false,
+      interfaces: [],
+      decoders: [],
+    }))
+    .exhaustive();
+}
+
+function formatObjectShape(fields: readonly PayloadField[], name: string): FormattedShape {
+  const formatted = fields.map((field) => ({
+    field,
+    shape: formatPayloadShape(field.shape, `${name}${toPascalCase(field.name)}`),
+  }));
+
+  const members = formatted.map(
+    (entry) =>
+      `  ${formatPropertyName(entry.field.name)}${entry.field.isOptional ? '?' : ''}: ${entry.shape.type};`,
+  );
+
+  const reads = formatted.flatMap((entry, index) =>
+    formatFieldRead(entry.field, entry.shape, index),
+  );
+
+  const properties = formatted.map((entry, index) =>
+    entry.field.isOptional
+      ? `    ...(field${index} === undefined ? {} : { ${formatPropertyName(entry.field.name)}: field${index} }),`
+      : `    ${formatPropertyName(entry.field.name)}: field${index},`,
+  );
+
+  const decoder = [
+    `function decode${name}(value: unknown): ${name} | undefined {`,
+    "  if (typeof value !== 'object' || value === null || Array.isArray(value)) {",
+    '    return undefined;',
+    '  }',
+    '',
+    ...reads,
+    '  return {',
+    ...properties,
+    '  };',
+    '}',
+  ].join('\n');
+
+  return {
+    type: name,
+    decode: (identifier: string) => `decode${name}(${identifier})`,
+    canFail: true,
+    interfaces: [
+      [`export interface ${name} {`, ...members, '}'].join('\n'),
+      ...formatted.flatMap((entry) => entry.shape.interfaces),
+    ],
+    decoders: [decoder, ...formatted.flatMap((entry) => entry.shape.decoders)],
+  };
+}
+
+function formatFieldRead(field: PayloadField, shape: FormattedShape, index: number): string[] {
+  const read = `${formatLiteral(field.name)} in value ? ${formatPropertyAccess('value', field.name)} : undefined`;
+
+  if (!shape.canFail) {
+    return [`  const field${index} = ${read};`, ''];
+  }
+
+  if (field.isOptional) {
+    return [
+      `  const raw${index} = ${read};`,
+      `  const field${index} = raw${index} === undefined ? undefined : ${shape.decode(`raw${index}`)};`,
+      '',
+      `  if (raw${index} !== undefined && field${index} === undefined) {`,
+      '    return undefined;',
+      '  }',
+      '',
+    ];
+  }
+
+  return [
+    `  const raw${index} = ${read};`,
+    `  const field${index} = ${shape.decode(`raw${index}`)};`,
+    '',
+    `  if (field${index} === undefined) {`,
+    '    return undefined;',
+    '  }',
+    '',
+  ];
+}
+
+// An index loop: `for...of` over a parsed list makes scriptc link its dynamic invoke object.
+function formatArrayShape(element: PayloadShape, name: string): FormattedShape {
+  const item = formatPayloadShape(element, `${name}Item`);
+  const type = item.type.includes(' | ') ? `(${item.type})[]` : `${item.type}[]`;
+
+  const push = item.canFail
+    ? [
+        `    const item = ${item.decode('element')};`,
+        '',
+        '    if (item === undefined) {',
+        '      return undefined;',
+        '    }',
+        '',
+        '    items.push(item);',
+      ]
+    : ['    items.push(element);'];
+
+  const decoder = [
+    `function decode${name}(value: unknown): ${type} | undefined {`,
+    '  if (!Array.isArray(value)) {',
+    '    return undefined;',
+    '  }',
+    '',
+    `  const items: ${type} = [];`,
+    '',
+    '  for (let index = 0; index < value.length; index += 1) {',
+    '    const element: unknown = value[index];',
+    ...push,
+    '  }',
+    '',
+    '  return items;',
+    '}',
+  ].join('\n');
+
+  return {
+    type,
+    decode: (identifier: string) => `decode${name}(${identifier})`,
+    canFail: true,
+    interfaces: item.interfaces,
+    decoders: [decoder, ...item.decoders],
+  };
+}

package/src/generators/format-property-access.ts

@@ -0,0 +1,6 @@
+import { formatLiteral } from './format-literal.ts';
+import { isIdentifier } from './is-identifier.ts';
+
+export function formatPropertyAccess(object: string, name: string): string {
+  return isIdentifier(name) ? `${object}.${name}` : `${object}[${formatLiteral(name)}]`;
+}

package/src/generators/format-property-name.ts

@@ -0,0 +1,6 @@
+import { formatLiteral } from './format-literal.ts';
+import { isIdentifier } from './is-identifier.ts';
+
+export function formatPropertyName(name: string): string {
+  return isIdentifier(name) ? name : formatLiteral(name);
+}