@pepys/kit 0.0.0-stage → 0.1.0

package/src/deployments/define-plugin.ts

@@ -0,0 +1,56 @@
+import { kitVersion } from '../constants.ts';
+import type { ConsumerDeclaration } from '../consumers/types.ts';
+import type { EntityKind, LinkTypeDeclaration } from '../link-types/types.ts';
+import type { AnyQueryDefinition } from '../queries/types.ts';
+import type { SourceDefinition } from '../sources/types.ts';
+import type { Plugin, PluginSettings } from './types.ts';
+
+interface PluginDeclaration<Query extends AnyQueryDefinition> {
+  readonly name: string;
+  readonly sources?: readonly SourceDefinition[] | undefined;
+  readonly consumers?: readonly ConsumerDeclaration[] | undefined;
+  readonly queries?: readonly Query[] | undefined;
+  readonly settings?: PluginSettings | undefined;
+}
+
+export function definePlugin<const Query extends AnyQueryDefinition = never>(
+  plugin: PluginDeclaration<Query>,
+): Plugin<Query> {
+  const sources = plugin.sources ?? [];
+  const consumers = plugin.consumers ?? [];
+
+  return {
+    kit: kitVersion,
+    name: plugin.name,
+    settings: plugin.settings,
+    sources,
+    consumers,
+    queries: plugin.queries ?? [],
+    linkTypes: collectLinkTypes(consumers),
+    entityKinds: collectEntityKinds(sources, consumers),
+  };
+}
+
+function collectLinkTypes(consumers: readonly ConsumerDeclaration[]): LinkTypeDeclaration[] {
+  const byName = new Map<string, LinkTypeDeclaration>();
+
+  for (const linkType of consumers.flatMap((consumer) => consumer.links)) {
+    if (!byName.has(linkType.name)) {
+      byName.set(linkType.name, linkType);
+    }
+  }
+
+  return [...byName.values()];
+}
+
+function collectEntityKinds(
+  sources: readonly SourceDefinition[],
+  consumers: readonly ConsumerDeclaration[],
+): EntityKind[] {
+  const kinds = [
+    ...sources.flatMap((source) => source.families.map((family) => family.entityKind)),
+    ...consumers.flatMap((consumer) => consumer.entityViews.map((view) => view.kind)),
+  ];
+
+  return [...new Set(kinds)];
+}

package/src/deployments/list-receive-routes.ts

@@ -0,0 +1,27 @@
+import type { Deployment, ReceiveRoute } from './types.ts';
+
+export function listReceiveRoutes(deployment: Deployment): ReceiveRoute[] {
+  const routes: ReceiveRoute[] = [];
+
+  for (const source of deployment.plugins.flatMap((plugin) => plugin.sources)) {
+    const path = source.live;
+
+    if (path?.kind !== 'receive') {
+      continue;
+    }
+
+    const reach = path.reach ?? 'private';
+
+    for (const route of [path.route, ...(path.ignoredRoutes ?? [])]) {
+      routes.push({
+        source: source.name,
+        route,
+        check: path.check.kind,
+        reach,
+        stores: route === path.route,
+      });
+    }
+  }
+
+  return routes;
+}

package/src/deployments/types.ts

@@ -0,0 +1,112 @@
+import type { z } from 'zod';
+import type { ConsumerDeclaration } from '../consumers/types.ts';
+import type { EntityKind, LinkTypeDeclaration } from '../link-types/types.ts';
+import type { AnyQueryDefinition } from '../queries/types.ts';
+import type { DeliveryCheck, SourceDefinition } from '../sources/types.ts';
+import type { DeclaredStreamName } from '../types.ts';
+
+export type SettingValue = string | number | boolean;
+
+export interface Plugin<Query extends AnyQueryDefinition = AnyQueryDefinition> {
+  // the kit version the plug-in was declared with
+  readonly kit: number;
+  readonly name: string;
+  readonly settings: PluginSettings | undefined;
+  readonly sources: readonly SourceDefinition[];
+  readonly consumers: readonly ConsumerDeclaration[];
+  readonly queries: readonly Query[];
+
+  // every consumer's `links`, once per name
+  readonly linkTypes: readonly LinkTypeDeclaration[];
+
+  // every family's `entityKind` and every entity view's `kind`, once each
+  readonly entityKinds: readonly EntityKind[];
+}
+
+// Compile-time settings: `pepys build` writes the checked values into the glue of each consumer of
+// the plug-in, so a consumer reads no setting at run time and a new value is a new version.
+export interface PluginSettings<Schema extends z.ZodObject = z.ZodObject> {
+  // a flat object of strings, numbers and booleans
+  readonly schema: Schema;
+  readonly defaults: z.output<Schema>;
+}
+
+export interface Deployment<Plugins extends readonly Plugin[] = readonly Plugin[]> {
+  readonly name: string;
+  readonly plugins: Plugins;
+
+  // Literals by plug-in name: the deployment file reads no environment. A value left out takes the
+  // plug-in's default.
+  readonly settings?: Readonly<Record<string, Readonly<Record<string, SettingValue>>>> | undefined;
+}
+
+// The typed client of one plug-in's queries. A type only, so the kit needs no oRPC. A plug-in with
+// no queries, written inside `defineDeployment`, takes its query type from the call's context, so
+// a query name that is no literal gives no method rather than an index signature.
+export type PluginClient<Target extends Plugin> = {
+  [Query in Target['queries'][number] as string extends Query['name'] ? never : Query['name']]: (
+    input: z.input<Query['input']>,
+  ) => Promise<z.output<Query['output']>>;
+};
+
+export interface CheckedDeployment {
+  readonly name: string;
+  readonly sources: readonly SourceDefinition[];
+  readonly consumers: readonly ConsumerDeclaration[];
+  readonly queries: readonly AnyQueryDefinition[];
+  readonly entityKinds: readonly EntityKind[];
+  readonly linkTypes: readonly LinkTypeDeclaration[];
+
+  // the checked settings of each plug-in that declares some, with the defaults filled in
+  readonly settings: Readonly<Record<string, Readonly<Record<string, SettingValue>>>>;
+}
+
+export type DuplicateOf =
+  | 'plugin'
+  | 'source'
+  | 'stream'
+  | 'route'
+  | 'fact-type'
+  | 'consumer'
+  | 'table'
+  | 'query'
+  | 'link-type'
+  | 'entity-view-kind';
+
+export type DeploymentFailure =
+  | { kind: 'kit-version'; plugin: string; kit: number }
+
+  // `link-type`: one name with two shapes. `entity-view-kind`: a kind needs one owning table.
+  | { kind: 'duplicate'; of: DuplicateOf; name: string; plugins: readonly string[] }
+
+  // a link end or a scope kind that no plug-in of the deployment brings
+  | { kind: 'unknown-entity-kind'; entityKind: EntityKind; plugin: string; usedBy: string }
+  | { kind: 'missing-consumer'; consumer: string; query: string }
+  | { kind: 'missing-stream'; stream: DeclaredStreamName; consumer: string }
+  | { kind: 'reserved-query-name'; query: string }
+  | { kind: 'reserved-table-name'; table: string; consumer: string }
+  | { kind: 'scope-reads'; consumer: string }
+  | { kind: 'reserved-source-name'; source: string }
+
+  // a value that fails the schema, or settings for a plug-in that has none or is not deployed
+  | { kind: 'invalid-settings'; plugin: string; issues: readonly string[] }
+
+  // a read or an entity view that names a table the consumer does not declare
+  | { kind: 'unknown-table'; consumer: string; table: string; usedBy: 'reads' | 'entity-view' }
+  | {
+      kind: 'unknown-column';
+      consumer: string;
+      table: string;
+      column: string;
+      usedBy: 'primary-key' | 'index' | 'entity-view';
+    };
+
+export interface ReceiveRoute {
+  source: string;
+  route: string;
+  check: DeliveryCheck['kind'];
+  reach: 'public' | 'private';
+
+  // false for a route that answers and stores nothing
+  stores: boolean;
+}

package/src/entity-ids/build-entity-id.ts

@@ -0,0 +1,16 @@
+import { toTagged } from '@zgeoff/std';
+import type { EntityID } from '../ids/types.ts';
+import type { Result } from '../types.ts';
+import type { EntityIDFailure } from './entity-id-failure.ts';
+import type { EntityIDParts } from './entity-id-parts.ts';
+import { findEntityIDFailure } from './find-entity-id-failure.ts';
+
+export function buildEntityID(parts: EntityIDParts): Result<EntityID, EntityIDFailure> {
+  const failure = findEntityIDFailure(parts);
+
+  if (failure !== undefined) {
+    return { ok: false, failure };
+  }
+
+  return { ok: true, value: toTagged<EntityID>(`${parts.source}:${parts.kind}:${parts.id}`) };
+}

package/src/entity-ids/entity-id-failure.ts

@@ -0,0 +1,6 @@
+export type EntityIDFailure =
+  | { reason: 'malformed' }
+  | { reason: 'invalid-source' }
+  | { reason: 'reserved-source' }
+  | { reason: 'invalid-kind' }
+  | { reason: 'empty-id' };

package/src/entity-ids/entity-id-parts.ts

@@ -0,0 +1,5 @@
+export interface EntityIDParts {
+  source: string;
+  kind: string;
+  id: string;
+}

package/src/entity-ids/fact-kinds.ts

@@ -0,0 +1,3 @@
+// Each fact ID starts with its kind, so a source named like a kind could make a fact ID read as an
+// entity ID.
+export const factKinds = ['webhook', 'event', 'observation', 'enrichment', 'manual'] as const;

package/src/entity-ids/find-entity-id-failure.ts

@@ -0,0 +1,25 @@
+import type { EntityIDFailure } from './entity-id-failure.ts';
+import type { EntityIDParts } from './entity-id-parts.ts';
+import { factKinds } from './fact-kinds.ts';
+
+const partPattern = /^[a-z][a-z0-9_]*$/u;
+
+export function findEntityIDFailure(parts: EntityIDParts): EntityIDFailure | undefined {
+  if (!partPattern.test(parts.source)) {
+    return { reason: 'invalid-source' };
+  }
+
+  if (factKinds.some((factKind) => factKind === parts.source)) {
+    return { reason: 'reserved-source' };
+  }
+
+  if (!partPattern.test(parts.kind)) {
+    return { reason: 'invalid-kind' };
+  }
+
+  if (parts.id === '') {
+    return { reason: 'empty-id' };
+  }
+
+  return undefined;
+}

package/src/entity-ids/parse-entity-id.ts

@@ -0,0 +1,27 @@
+import type { Result } from '../types.ts';
+import type { EntityIDFailure } from './entity-id-failure.ts';
+import type { EntityIDParts } from './entity-id-parts.ts';
+import { findEntityIDFailure } from './find-entity-id-failure.ts';
+
+export function parseEntityID(text: string): Result<EntityIDParts, EntityIDFailure> {
+  const firstSeparator = text.indexOf(':');
+  const secondSeparator = text.indexOf(':', firstSeparator + 1);
+
+  if (firstSeparator === -1 || secondSeparator === -1) {
+    return { ok: false, failure: { reason: 'malformed' } };
+  }
+
+  const parts = {
+    source: text.slice(0, firstSeparator),
+    kind: text.slice(firstSeparator + 1, secondSeparator),
+    id: text.slice(secondSeparator + 1),
+  };
+
+  const failure = findEntityIDFailure(parts);
+
+  if (failure !== undefined) {
+    return { ok: false, failure };
+  }
+
+  return { ok: true, value: parts };
+}