@deterministic-code/datasources-cli 0.0.0-stage → 0.1.3

package/node_modules/@deterministic-code/generators-common/src/routes-api.ts

@@ -0,0 +1,82 @@
+export type JsonValue =
+  | string
+  | number
+  | boolean
+  | null
+  | JsonValue[]
+  | { [key: string]: JsonValue };
+
+/** Contract version stamped on every expanded routes-api document. */
+export const ROUTES_API_VERSION = "1.0.0";
+
+/** Named JSON Schema / OpenAPI schema object in the routes-api component map. */
+export type RoutesApiSchema = {
+  type?: string;
+  format?: string;
+  properties?: Record<string, RoutesApiSchema>;
+  items?: RoutesApiSchema;
+  required?: string[];
+  $ref?: string;
+  nullable?: boolean;
+  enum?: unknown[];
+  default?: unknown;
+  maxLength?: number;
+  oneOf?: RoutesApiSchema[];
+  "x-references"?: string;
+};
+
+/** Resolved request/response body: component name, `$ref` schema, rendered example. */
+export type RoutesApiBody = {
+  name: string;
+  schema: { $ref: string } | null;
+  example: JsonValue | null;
+};
+
+/** One expanded operation (CRUD, combined-route child, or custom). */
+export type RoutesApiRouteDef = {
+  path: string;
+  method: string;
+  entity: string | null;
+  isCustom: boolean;
+  request?: RoutesApiBody;
+  response?: RoutesApiBody;
+  byField?: string;
+  byFieldUnique?: boolean;
+  primaryKeyField?: string | null;
+  /** All identity columns when the entity has a composite primary key. */
+  primaryKeyFields?: string[];
+  /** When true, this write requires `If-Match: <updated>` (PUT/PATCH/DELETE). */
+  optimisticConcurrency?: boolean;
+};
+
+/** Single-key `{ <routeName>: def }` map. */
+export type RoutesApiRouteEntry = Record<string, RoutesApiRouteDef>;
+
+/**
+ * Flattened HTTP API catalog: `{ version, routes, components }`.
+ * @see https://github.com/deterministic-code/deterministic-specifications/blob/main/backend/routes-api.spec.yaml
+ */
+export type RoutesApiDoc = {
+  version: string;
+  routes: RoutesApiRouteEntry[];
+  components: Record<string, RoutesApiSchema>;
+};
+
+/** Flatten YAML-style single-key route maps into `[name, def]` pairs. */
+export const namedRoutes = (
+  routes: RoutesApiRouteEntry[],
+): Array<[string, RoutesApiRouteDef]> =>
+  routes.flatMap((item) => {
+    const name = Object.keys(item)[0];
+    const def = name === undefined ? undefined : item[name];
+    if (
+      name === undefined ||
+      def === null ||
+      typeof def !== "object" ||
+      typeof def.path !== "string" ||
+      typeof def.method !== "string"
+    ) {
+      return [];
+    }
+    return [[name, def]];
+  });

package/node_modules/@deterministic-code/generators-common/src/settings.test.ts

@@ -0,0 +1,154 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { fromSettings } from "./settings.ts";
+
+describe("fromSettings", () => {
+  it("defaults schemaVersion to 1.0 and createIndex on", () => {
+    const settings = fromSettings({});
+    assert.equal(settings.applicationName, "generated-frontend");
+    assert.equal(settings.schemaVersion, "1.0");
+    assert.equal(settings.createIndex, true);
+    assert.equal(settings.libraryReferenceMode, undefined);
+  });
+
+  it("reads applicationName and falls back when blank", () => {
+    assert.equal(
+      fromSettings({ application_name: "catalog-ui" }).applicationName,
+      "catalog-ui",
+    );
+    assert.equal(
+      fromSettings({ application_name: "" }).applicationName,
+      "generated-frontend",
+    );
+  });
+
+  it("defaults frontendFramework to vite", () => {
+    assert.equal(fromSettings({}).frontendFramework, "vite");
+    assert.equal(
+      fromSettings({ frontend_generate_framework: "" }).frontendFramework,
+      "vite",
+    );
+    assert.equal(
+      fromSettings({ frontend_generate_framework: "next" }).frontendFramework,
+      "next",
+    );
+    assert.equal(fromSettings({}).fullStack, false);
+    assert.equal(
+      fromSettings({ application_tier: "full-stack" }).fullStack,
+      true,
+    );
+  });
+
+  it("rejects an unknown frontend_generate_framework", () => {
+    assert.throws(
+      () => fromSettings({ frontend_generate_framework: "remix" }),
+      /settings\.frontend_generate_framework must be "vite", "next", "svelte", "angular"/,
+    );
+  });
+
+  it("reads schemaVersion and libraryReferenceMode", () => {
+    const settings = fromSettings({
+      "codegen.schema_version": "9.9",
+      "languages.typescript.library_reference_mode": "bundled",
+    });
+    assert.equal(settings.schemaVersion, "9.9");
+    assert.equal(settings.libraryReferenceMode, "bundled");
+  });
+
+  it("createIndex is off only when codegen.create_index is false", () => {
+    assert.equal(fromSettings({}).createIndex, true);
+    assert.equal(
+      fromSettings({ "codegen.create_index": "true" }).createIndex,
+      true,
+    );
+    assert.equal(
+      fromSettings({ "codegen.create_index": "false" }).createIndex,
+      false,
+    );
+  });
+
+  it("comments=simple and unset emit simpleDoc", () => {
+    assert.equal(fromSettings({}).simpleDoc, true);
+    assert.equal(fromSettings({}).descriptionDoc, false);
+    assert.equal(fromSettings({ comments: "simple" }).simpleDoc, true);
+    assert.equal(fromSettings({ comments: "simple" }).descriptionDoc, false);
+  });
+
+  it("comments=description emits descriptionDoc", () => {
+    const settings = fromSettings({ comments: "description" });
+    assert.equal(settings.simpleDoc, false);
+    assert.equal(settings.descriptionDoc, true);
+  });
+
+  it("comments=none omits both doc flags", () => {
+    const settings = fromSettings({ comments: "none" });
+    assert.equal(settings.simpleDoc, false);
+    assert.equal(settings.descriptionDoc, false);
+  });
+});
+
+describe("usesOptimisticConcurrency", () => {
+  it("returns false for junction and readonly-lookup tables", () => {
+    const on = fromSettings({});
+    assert.equal(
+      on.usesOptimisticConcurrency({ datasourceType: "many-to-many" }),
+      false,
+    );
+    assert.equal(
+      on.usesOptimisticConcurrency({ datasourceType: "readonly-lookup" }),
+      false,
+    );
+    assert.equal(
+      on.usesOptimisticConcurrency({ tags: ["many_to_many"] }),
+      false,
+    );
+    assert.equal(
+      on.usesOptimisticConcurrency({ tags: ["readonly_lookup"] }),
+      false,
+    );
+  });
+
+  it("prefers useOptimisticConcurrency over optimisticConcurrency", () => {
+    const on = fromSettings({});
+    assert.equal(
+      on.usesOptimisticConcurrency({
+        useOptimisticConcurrency: false,
+        optimisticConcurrency: true,
+      }),
+      false,
+    );
+    assert.equal(
+      on.usesOptimisticConcurrency({ useOptimisticConcurrency: true }),
+      true,
+    );
+  });
+
+  it("prefers explicit per-type flag over the global default", () => {
+    const on = fromSettings({});
+    const off = fromSettings({
+      "datasource.use_optimistic_concurrency": "false",
+    });
+    assert.equal(
+      on.usesOptimisticConcurrency({
+        datasourceType: "standard",
+        optimisticConcurrency: false,
+      }),
+      false,
+    );
+    assert.equal(
+      off.usesOptimisticConcurrency({
+        datasourceType: "standard",
+        optimisticConcurrency: true,
+      }),
+      true,
+    );
+    assert.equal(
+      on.usesOptimisticConcurrency({ datasourceType: "standard" }),
+      true,
+    );
+    assert.equal(
+      off.usesOptimisticConcurrency({ datasourceType: "standard" }),
+      false,
+    );
+  });
+});

package/node_modules/@deterministic-code/generators-common/src/settings.ts

@@ -0,0 +1,80 @@
+export type OccTable = {
+  datasourceType?: string | null;
+  optimisticConcurrency?: boolean;
+  tags?: readonly string[];
+  useOptimisticConcurrency?: boolean;
+};
+
+export const FRONTEND_FRAMEWORKS = [
+  "vite",
+  "next",
+  "svelte",
+  "angular",
+] as const;
+
+export type FrontendFramework = (typeof FRONTEND_FRAMEWORKS)[number];
+
+export type ISettings = {
+  readonly applicationName: string;
+  readonly frontendFramework: FrontendFramework;
+  readonly fullStack: boolean;
+  readonly schemaVersion: string;
+  readonly simpleDoc: boolean;
+  readonly descriptionDoc: boolean;
+  readonly createIndex: boolean;
+  readonly libraryReferenceMode: string | undefined;
+  usesOptimisticConcurrency(table: OccTable): boolean;
+};
+
+const isFrontendFramework = (raw: string): raw is FrontendFramework =>
+  (FRONTEND_FRAMEWORKS as readonly string[]).includes(raw);
+
+export const fromSettings = (raw: Record<string, string>): ISettings => {
+  const comments = raw["comments"];
+  const globalOcc = raw["datasource.use_optimistic_concurrency"] !== "false";
+  const frontendFramework = raw["frontend_generate_framework"];
+  if (
+    frontendFramework !== undefined &&
+    frontendFramework !== "" &&
+    !isFrontendFramework(frontendFramework)
+  ) {
+    throw new Error(
+      `settings.frontend_generate_framework must be ${FRONTEND_FRAMEWORKS.map((name) => JSON.stringify(name)).join(", ")}, got ${JSON.stringify(frontendFramework)}`,
+    );
+  }
+  return {
+    applicationName: raw["application_name"] || "generated-frontend",
+    frontendFramework:
+      frontendFramework === undefined || frontendFramework === ""
+        ? "vite"
+        : frontendFramework,
+    fullStack: raw["application_tier"] === "full-stack",
+    schemaVersion: raw["codegen.schema_version"] ?? "1.0",
+    simpleDoc: comments !== "none" && comments !== "description",
+    descriptionDoc: comments === "description",
+    createIndex: raw["codegen.create_index"] !== "false",
+    libraryReferenceMode: raw["languages.typescript.library_reference_mode"],
+    usesOptimisticConcurrency: (table) => {
+      const tags = table.tags ?? [];
+      if (
+        table.datasourceType === "many-to-many" ||
+        tags.includes("many_to_many")
+      ) {
+        return false;
+      }
+      if (
+        table.datasourceType === "readonly-lookup" ||
+        tags.includes("readonly_lookup")
+      ) {
+        return false;
+      }
+      if (table.useOptimisticConcurrency !== undefined) {
+        return table.useOptimisticConcurrency;
+      }
+      if (table.optimisticConcurrency !== undefined) {
+        return table.optimisticConcurrency;
+      }
+      return globalOcc;
+    },
+  };
+};

package/node_modules/@deterministic-code/generators-common/src/spec-types.test.ts

@@ -0,0 +1,156 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import type { DatasourceTable, Type, TypeField } from "@deterministic-code/deterministic-generators-common/parser";
+import {
+  columnFields,
+  fieldTypeOf,
+  identityColumns,
+  isCollectionField,
+  isPkField,
+  primaryKeyColumn,
+  uniqueLookupFields,
+} from "./spec-types.ts";
+
+const field = (name: string, extras: Partial<TypeField> = {}): TypeField => ({
+  name,
+  type: extras.type ?? "integer",
+  kind: "primitive",
+  base: extras.base ?? extras.type ?? "integer",
+  isArray: false,
+  isNullable: false,
+  ...extras,
+});
+
+const typeOf = (partial: Partial<Type> & { name?: string }): Type => ({
+  name: partial.name ?? "item",
+  tags: partial.tags ?? ["datasource_type"],
+  kind: partial.kind ?? "inherit",
+  inherits: partial.inherits,
+  ids: partial.ids,
+  fields: partial.fields ?? [],
+});
+
+const tableOf = (
+  fields: DatasourceTable["fields"] = [],
+): DatasourceTable => ({
+  name: "item",
+  fields,
+  indexes: [],
+  uniqueIndexFields: [],
+});
+
+describe("identityColumns", () => {
+  it("returns type-level ids in declared order", () => {
+    const type = typeOf({
+      inherits: "set",
+      ids: ["left_id", "right_id"],
+      fields: [field("left_id"), field("right_id")],
+    });
+    assert.deepEqual(identityColumns(type), ["left_id", "right_id"]);
+    assert.equal(primaryKeyColumn(undefined, type), "left_id");
+    assert.equal(isPkField(field("right_id"), type), true);
+    assert.equal(isPkField(field("name", { type: "string" }), type), false);
+  });
+
+  it("uses a field marked is_id when ids is absent", () => {
+    const type = typeOf({
+      fields: [field("code", { isId: true }), field("name", { type: "string" })],
+    });
+    assert.deepEqual(identityColumns(type), ["code"]);
+  });
+
+  it("uses is_fixed_id overlay when no authored identity", () => {
+    const type = typeOf({
+      fields: [field("key", { type: "string" })],
+    });
+    const table = tableOf([{ name: "key", isFixedId: true }]);
+    assert.deepEqual(identityColumns(type, table), ["key"]);
+    assert.equal(primaryKeyColumn(table, type), "key");
+  });
+
+  it("injects id when inherits set and nothing is authored", () => {
+    const type = typeOf({
+      inherits: "set",
+      fields: [field("email", { type: "string" })],
+    });
+    assert.deepEqual(identityColumns(type), ["id"]);
+  });
+
+  it("includes every identity column in uniqueLookupFields", () => {
+    const type = typeOf({
+      inherits: "set",
+      ids: ["left_id", "right_id"],
+      fields: [field("left_id"), field("right_id")],
+    });
+    assert.deepEqual(
+      uniqueLookupFields(type).map((e) => e.field),
+      ["left_id", "right_id"],
+    );
+  });
+});
+
+describe("fieldTypeOf", () => {
+  it("walks references to the parent field type", () => {
+    const parent = typeOf({
+      name: "parent",
+      inherits: "set",
+      fields: [field("id", { type: "integer" })],
+    });
+    const ownerId = field("owner_id", {
+      type: "string",
+      references: "parent.id",
+    });
+    const typesByName = new Map([["parent", parent]]);
+    assert.equal(fieldTypeOf(ownerId, typesByName), "integer");
+  });
+
+  it("keeps collection shape types", () => {
+    const addresses = field("addresses", {
+      type: "address[]",
+      kind: "type",
+      base: "address",
+      isArray: true,
+      references: "address.contact_id",
+    });
+    assert.equal(fieldTypeOf(addresses, new Map()), "address[]");
+  });
+
+  it("falls back on a cycle or missing parent", () => {
+    const a = field("a_id", { type: "string", references: "b.id" });
+    const b = field("id", { type: "string", references: "a.a_id" });
+    const typesByName = new Map([
+      ["a", typeOf({ name: "a", fields: [a] })],
+      ["b", typeOf({ name: "b", fields: [b] })],
+    ]);
+    assert.equal(fieldTypeOf(a, typesByName), "string");
+    assert.equal(
+      fieldTypeOf(field("orphan_id", { type: "string", references: "missing.id" }), typesByName),
+      "string",
+    );
+  });
+});
+
+describe("columnFields", () => {
+  it("drops type-kind arrays and keeps scalars", () => {
+    const addresses = field("addresses", {
+      type: "address[]",
+      kind: "type",
+      base: "address",
+      isArray: true,
+    });
+    const email = field("email", { type: "string" });
+    const settings = field("settings", {
+      type: "contact_settings{}",
+      kind: "type",
+      base: "contact_settings",
+      isMap: true,
+    });
+    assert.equal(isCollectionField(addresses), true);
+    assert.equal(isCollectionField(settings), true);
+    assert.equal(isCollectionField(email), false);
+    assert.deepEqual(
+      columnFields([email, addresses, settings]).map((f) => f.name),
+      ["email"],
+    );
+  });
+});

package/node_modules/@deterministic-code/generators-common/src/spec-types.ts

@@ -0,0 +1,234 @@
+import type {
+  DatasourceTable,
+  IDeterministic,
+  ServiceByField,
+  Type,
+  TypeField,
+} from "@deterministic-code/deterministic-generators-common/parser";
+
+export const TYPES_YAML = "types.yaml";
+export const DATASOURCE_YAML = "datasource.yaml";
+export const DATASOURCE_SEEDS_YAML = "datasource_seeds.yaml";
+export const SERVICES_YAML = "services.yaml";
+export const ROUTES_YAML = "routes.yaml";
+
+export const typeHasTag = (type: Type, tag: string): boolean =>
+  type.tags.includes(tag);
+
+export const typesWithTag = (types: readonly Type[], tag: string): Type[] =>
+  types.filter((type) => typeHasTag(type, tag));
+
+export const datasourceTypesOf = (spec: IDeterministic): Type[] =>
+  typesWithTag(spec.expandedTypes, "datasource_type");
+
+export const isDictionaryType = (type: Type | undefined): boolean =>
+  type?.inherits === "dictionary";
+
+export const viewTypesOf = (spec: IDeterministic): Type[] =>
+  typesWithTag(spec.expandedTypes, "view_type").filter(
+    (type) => !isDictionaryType(type),
+  );
+
+export const authoredViewTypesOf = (spec: IDeterministic): Type[] =>
+  typesWithTag(spec.types, "view_type").filter((type) => !isDictionaryType(type));
+
+export const isManyToMany = (type: Type): boolean =>
+  typeHasTag(type, "many_to_many");
+
+export const isReadonlyLookup = (type: Type): boolean =>
+  typeHasTag(type, "readonly_lookup");
+
+/** Nested eager collections (`address[]`, `settings{}`) are view relations, not persisted columns. */
+export const isCollectionField = (field: TypeField): boolean =>
+  field.kind === "type" && (field.isArray || field.isMap === true);
+
+export const columnFields = (fields: readonly TypeField[]): TypeField[] =>
+  fields.filter((field) => !isCollectionField(field));
+
+export const tableKind = (type: Type): string => {
+  if (isManyToMany(type)) return "many-to-many";
+  if (isReadonlyLookup(type)) return "readonly-lookup";
+  return "standard";
+};
+
+type TypeKey = Pick<Type, "inherits" | "fields" | "ids">;
+
+const markedIds = (type: TypeKey): string[] =>
+  type.fields.filter((f) => f.isId === true).map((f) => f.name);
+
+/** Ordered identity columns: `ids`, else `is_id`, else `is_fixed_id`, else injected `id`. */
+export const identityColumns = (
+  type?: TypeKey,
+  table?: DatasourceTable,
+): string[] => {
+  if (type?.ids !== undefined && type.ids.length > 0) return [...type.ids];
+  const marked = type !== undefined ? markedIds(type) : [];
+  if (marked.length > 0) return marked;
+  const fixed = table?.fields.find((f) => f.isFixedId);
+  if (fixed) return [fixed.name];
+  if (type?.inherits === "set" || type === undefined) return ["id"];
+  return [];
+};
+
+export const primaryKeyColumn = (
+  table: DatasourceTable | undefined,
+  type?: TypeKey,
+): string => identityColumns(type, table)[0] ?? "id";
+
+export const pkName = (type: TypeKey, table?: DatasourceTable): string =>
+  primaryKeyColumn(table, type);
+
+export const isPkField = (
+  field: TypeField,
+  type: TypeKey,
+  table?: DatasourceTable,
+): boolean => identityColumns(type, table).includes(field.name);
+
+export const uniqueLookupFields = (
+  type: TypeKey,
+  table?: DatasourceTable,
+): ServiceByField[] => {
+  const out: ServiceByField[] = [];
+  const add = (name: string) => {
+    if (out.some((e) => e.field === name)) return;
+    const f = type.fields.find((x) => x.name === name);
+    if (f !== undefined && isCollectionField(f)) return;
+    out.push({
+      field: name,
+      type: typeof f?.type === "string" ? f.type : "string",
+      ...(typeof f?.size === "number" ? { size: f.size } : {}),
+    });
+  };
+  for (const name of identityColumns(type, table)) add(name);
+  for (const overlay of table?.fields ?? []) {
+    if (overlay.isUnique) add(overlay.name);
+  }
+  for (const name of table?.uniqueIndexFields ?? []) add(name);
+  return out;
+};
+
+export const tableByName = (
+  spec: IDeterministic,
+): Map<string, DatasourceTable> =>
+  new Map(spec.datasource.map((table) => [table.name, table]));
+
+const referenceTarget = (
+  references: NonNullable<TypeField["references"]>,
+): [string, string] => {
+  if (Array.isArray(references)) return [references[0], references[1]];
+  const [table, col] = references.split(".");
+  return [table ?? "", col ?? ""];
+};
+
+/** Walk `references` to the parent field type; collections keep `[]` / `{}`. */
+export const fieldTypeOf = (
+  field: TypeField,
+  typesByName: ReadonlyMap<string, Type>,
+  seen: Set<string> = new Set(),
+): string => {
+  if (field.type.endsWith("[]") || field.type.endsWith("{}")) {
+    return field.type;
+  }
+  if (field.references !== undefined) {
+    const [logicalTable, logicalCol] = referenceTarget(field.references);
+    const key = `${logicalTable}.${logicalCol}`;
+    if (!seen.has(key)) {
+      seen.add(key);
+      const parent = typesByName
+        .get(logicalTable)
+        ?.fields.find((item) => item.name === logicalCol);
+      if (parent !== undefined) return fieldTypeOf(parent, typesByName, seen);
+    }
+  }
+  return field.type || "string";
+};
+
+const splitDot = (value: string): [string, string] | undefined => {
+  const i = value.indexOf(".");
+  return i === -1 ? undefined : [value.slice(0, i), value.slice(i + 1)];
+};
+
+const identityNamesOf = (
+  type: Type | undefined,
+  byName: Map<string, Type>,
+  stack: Set<string> = new Set(),
+): Set<string> => {
+  if (!type) return new Set();
+  if (stack.has(type.name)) return new Set();
+  const local = identityColumns(type);
+  if (local.length > 0) return new Set(local);
+  if (type.inherits && type.inherits !== "dictionary") {
+    stack.add(type.name);
+    return identityNamesOf(byName.get(type.inherits), byName, stack);
+  }
+  return new Set();
+};
+
+export const isOwnerIdentityRef = (
+  references: TypeField["references"],
+  selfName: string,
+  byName: Map<string, Type>,
+): boolean => {
+  if (references === undefined) return false;
+  const parts = (Array.isArray(references) ? references : [references]).map(
+    (ref) => {
+      const split = splitDot(ref);
+      return split ? { type: split[0], field: split[1] } : { type: "", field: ref };
+    },
+  );
+  const owner = parts[0]!.type;
+  if (!owner || owner === selfName) return false;
+  const identity = identityNamesOf(byName.get(owner), byName);
+  return parts.every((p) => p.type === owner && identity.has(p.field));
+};
+
+export const dictionaryEntryFields = (
+  dict: Type,
+): { key: TypeField; value: TypeField } | undefined => {
+  const key = dict.fields.find((f) => f.name === "key");
+  const value = dict.fields.find((f) => f.name === "value");
+  if (key === undefined || value === undefined) return undefined;
+  return { key, value };
+};
+
+export const dictionaryOfField = (
+  field: TypeField,
+  byName: Map<string, Type>,
+): Type | undefined => {
+  if (field.isMap !== true) return undefined;
+  const dict = byName.get(field.base);
+  return isDictionaryType(dict) ? dict : undefined;
+};
+
+export const persistedColumnFields = (
+  type: Type,
+  byName: Map<string, Type>,
+): TypeField[] => {
+  if (!isDictionaryType(type)) return columnFields(type.fields);
+  const value = type.fields.find((f) => f.name === "value");
+  if (
+    value === undefined ||
+    value.kind !== "type" ||
+    value.isArray ||
+    value.isMap === true
+  ) {
+    return columnFields(type.fields);
+  }
+  const nested = byName.get(value.base);
+  if (nested === undefined) return columnFields(type.fields);
+  return [
+    ...columnFields(type.fields.filter((f) => f.name !== "value")),
+    ...columnFields(nested.fields),
+  ];
+};
+
+export const dictionaryUniqueColumns = (
+  type: Type,
+  byName: Map<string, Type>,
+): string[] => {
+  if (!isDictionaryType(type)) return [];
+  const owners = type.fields
+    .filter((f) => isOwnerIdentityRef(f.references, type.name, byName))
+    .map((f) => f.name);
+  return type.fields.some((f) => f.name === "key") ? [...owners, "key"] : owners;
+};