@drzl/cli 4.16.0 → 4.17.0

package/dist/dist-TRJLPIWT.js

@@ -0,0 +1,603 @@
+// ../generator-json-schema/dist/index.js
+import {
+  formatCode,
+  moduleFileName,
+  moduleSpecifier,
+  resolveAffix,
+  schemaName,
+  typeName
+} from "@drzl/validation-core";
+import {
+  COLUMN_FORMATS,
+  insertColumns,
+  isIntegerColumn,
+  parseCheck,
+  selectColumns,
+  updateColumns
+} from "@drzl/validation-core";
+var DRAFT = "https://json-schema.org/draft/2020-12/schema";
+var UUID_FORMAT = "uuid";
+var base64 = (target) => target === "openapi-3.0" ? { type: "string", format: "byte" } : { type: "string", contentEncoding: "base64" };
+function baseSchema(c, mode, target, checks, sets, lengths) {
+  const s = c.shape;
+  if (s) {
+    switch (s.kind) {
+      case "json":
+        return {};
+      case "custom":
+        return {};
+      case "buffer":
+        return base64(target);
+      case "tuple":
+        return target === "openapi-3.0" ? { type: "array", items: { type: "number" }, minItems: s.length, maxItems: s.length } : {
+          type: "array",
+          prefixItems: Array.from({ length: s.length }, () => ({ type: "number" })),
+          minItems: s.length,
+          maxItems: s.length
+        };
+      case "numberObject":
+        return {
+          type: "object",
+          properties: Object.fromEntries(s.fields.map((f) => [f, { type: "number" }])),
+          required: [...s.fields]
+        };
+      case "numberVector":
+        return {
+          type: "array",
+          items: { type: "number" },
+          ...s.length ? { minItems: s.length, maxItems: s.length } : {}
+        };
+      case "bitstring":
+        return {
+          type: "string",
+          pattern: "^[01]*$",
+          ...s.length ? s.exact ? { minLength: s.length, maxLength: s.length } : { maxLength: s.length } : {}
+        };
+      case "byteString":
+        return { type: "string", ...s.length ? { maxLength: s.length } : {} };
+    }
+  }
+  const set = sets.find((x) => x.column === c.name);
+  if (set) return { enum: set.values.map((v) => set.kind === "string" ? v : Number(v)) };
+  if (c.enumValues && c.enumValues.length) return { enum: [...c.enumValues] };
+  const mine = c.arrayDimensions ? [] : checks.filter((k) => k.column === c.name);
+  const eq = mine.find((k) => k.operator === "=");
+  if (eq) {
+    const only = eq.kind === "string" ? eq.value : Number(eq.value);
+    return target === "openapi-3.0" ? { enum: [only] } : { const: only };
+  }
+  switch (c.tsType) {
+    case "string": {
+      const out = { type: "string" };
+      if (c.format === "uuid") out.format = UUID_FORMAT;
+      else if (c.format && COLUMN_FORMATS[c.format]) out.pattern = COLUMN_FORMATS[c.format];
+      if (c.maxLength !== void 0) out.maxLength = c.maxLength;
+      applyByteCap(out, c);
+      applyLengths(out, c, lengths);
+      return out;
+    }
+    case "number": {
+      const out = { type: isIntegerColumn(c) ? "integer" : "number" };
+      if (!c.arrayDimensions) applyNumericBounds(out, c, checks, target);
+      return out;
+    }
+    case "bigint":
+      return { type: "string", pattern: "^-?\\d+$" };
+    case "boolean":
+      return { type: "boolean" };
+    case "Date":
+      return { type: "string", format: "date-time" };
+    case "Uint8Array":
+      return base64(target);
+    default:
+      return {};
+  }
+}
+function applyByteCap(out, c) {
+  if (!c.maxBytes) return;
+  out.maxLength = Math.min(Number(out.maxLength ?? Infinity), c.maxBytes);
+  out.description = `At most ${c.maxBytes} bytes of UTF-8, which JSON Schema has no keyword for. maxLength counts characters: it refuses nothing the column accepts, and a string of multi-byte characters can satisfy it and still be too long for the column.`;
+}
+function applyLengths(out, c, lengths) {
+  for (const k of lengths.filter((x) => x.column === c.name)) {
+    const n = Number(k.value);
+    if (k.operator === ">=") out.minLength = Math.max(Number(out.minLength ?? 0), n);
+    else if (k.operator === ">") out.minLength = Math.max(Number(out.minLength ?? 0), n + 1);
+    else if (k.operator === "<=") out.maxLength = Math.min(Number(out.maxLength ?? Infinity), n);
+    else if (k.operator === "<") out.maxLength = Math.min(Number(out.maxLength ?? Infinity), n - 1);
+    else if (k.operator === "=") {
+      out.minLength = n;
+      out.maxLength = n;
+    }
+  }
+}
+function applyNumericBounds(out, c, checks, target) {
+  let min = c.min !== void 0 ? { value: Number(c.min), exclusive: false } : void 0;
+  let max = c.max !== void 0 ? { value: Number(c.max), exclusive: false } : void 0;
+  for (const k of checks.filter((x) => x.column === c.name && x.kind === "number")) {
+    if (k.operator === ">=") min = { value: Number(k.value), exclusive: false };
+    else if (k.operator === ">") min = { value: Number(k.value), exclusive: true };
+    else if (k.operator === "<=") max = { value: Number(k.value), exclusive: false };
+    else if (k.operator === "<") max = { value: Number(k.value), exclusive: true };
+  }
+  const old = target === "openapi-3.0";
+  if (min) {
+    if (min.exclusive && !old) out.exclusiveMinimum = min.value;
+    else {
+      out.minimum = min.value;
+      if (min.exclusive) out.exclusiveMinimum = true;
+    }
+  }
+  if (max) {
+    if (max.exclusive && !old) out.exclusiveMaximum = max.value;
+    else {
+      out.maximum = max.value;
+      if (max.exclusive) out.exclusiveMaximum = true;
+    }
+  }
+}
+function cardinalityBounds(c, cardinalities) {
+  if (!c.arrayDimensions) return {};
+  const out = {};
+  for (const k of cardinalities.filter((x) => x.column === c.name)) {
+    const n = Number(k.value);
+    if (k.operator === ">=") out.minItems = n;
+    else if (k.operator === ">") out.minItems = n + 1;
+    else if (k.operator === "<=") out.maxItems = n;
+    else if (k.operator === "<") out.maxItems = n - 1;
+    else if (k.operator === "=") {
+      out.minItems = n;
+      out.maxItems = n;
+    }
+  }
+  return out;
+}
+function makeNullable(s, target) {
+  if (target === "openapi-3.0") return { ...s, nullable: true };
+  if (s.type === void 0) {
+    if (Array.isArray(s.enum)) return { ...s, enum: [...s.enum, null] };
+    if ("const" in s) {
+      const { const: k, ...rest } = s;
+      return { ...rest, enum: [k, null] };
+    }
+    return s;
+  }
+  return { ...s, type: [s.type, "null"] };
+}
+function columnSchema(c, mode, target, checks, sets, lengths, cardinalities, applyDefault) {
+  let s = baseSchema(c, mode, target, checks, sets, lengths);
+  const dims = c.arrayDimensions ?? 0;
+  for (let i = 0; i < dims; i++) {
+    s = { type: "array", items: s, ...i === dims - 1 ? cardinalityBounds(c, cardinalities) : {} };
+  }
+  if (c.nullable) s = makeNullable(s, target);
+  if (mode === "insert" && applyDefault && c.defaultValue !== void 0) {
+    s = { ...s, default: c.defaultValue };
+  }
+  return s;
+}
+function rowDescription(rows, cols) {
+  const present = new Set(cols.map((c) => c.name));
+  const applicable = rows.filter((r) => present.has(r.left) && present.has(r.right));
+  if (!applicable.length) return void 0;
+  const list = applicable.map((r) => `${r.name ? `${r.name}: ` : ""}${r.left} ${r.operator} ${r.right}`).join("; ");
+  return `Row constraints not expressible in JSON Schema: ${list}`;
+}
+function tableSchema(table, cols, mode, target, applyDefaults, parsed) {
+  const properties = {};
+  const required = [];
+  for (const c of cols) {
+    properties[c.name] = columnSchema(
+      c,
+      mode,
+      target,
+      parsed.checks,
+      parsed.sets,
+      parsed.lengths,
+      parsed.cardinalities,
+      applyDefaults
+    );
+    const suppliedOnInsert = c.hasDefault || applyDefaults && c.defaultValue !== void 0 || c.isGenerated;
+    const optional = mode === "update" || mode === "insert" && suppliedOnInsert;
+    if (!optional) required.push(c.name);
+  }
+  const desc = rowDescription(parsed.rows, cols);
+  return {
+    ...target === "draft-2020-12" ? { $schema: DRAFT } : {},
+    $id: `${table.tsName}.${mode}`,
+    title: `${mode} ${table.tsName}`,
+    ...desc ? { description: desc } : {},
+    type: "object",
+    properties,
+    ...required.length ? { required } : {},
+    additionalProperties: false
+  };
+}
+function collect(table) {
+  const parsed = (table.checks ?? []).map((k) => parseCheck(k.expression, k.name));
+  return {
+    checks: parsed.flatMap((p) => p.ok ? p.checks : []),
+    sets: parsed.flatMap((p) => p.ok ? p.sets ?? [] : []),
+    rows: parsed.flatMap((p) => p.ok ? p.rows ?? [] : []),
+    lengths: parsed.flatMap((p) => p.ok ? p.lengths ?? [] : []),
+    cardinalities: parsed.flatMap((p) => p.ok ? p.cardinalities ?? [] : [])
+  };
+}
+function tableSchemas(table, opts = {}) {
+  const target = opts.target ?? "draft-2020-12";
+  const parsed = collect(table);
+  const build2 = (cols, mode) => tableSchema(table, cols, mode, target, !!opts.applyDefaults, parsed);
+  return {
+    insert: build2(insertColumns(table), "insert"),
+    update: build2(updateColumns(table), "update"),
+    select: build2(selectColumns(table), "select")
+  };
+}
+function componentsDocument(tables, opts = {}) {
+  const schemas = {};
+  for (const table of tables) {
+    const built = tableSchemas(table, opts);
+    for (const mode of ["insert", "update", "select"]) {
+      const name = `${table.tsName}${mode[0].toUpperCase()}${mode.slice(1)}`;
+      const { $schema: _dialect, $id: _id, ...rest } = built[mode];
+      schemas[name] = rest;
+    }
+  }
+  return { schemas };
+}
+var ERROR_SCHEMA = "Error";
+var componentName = (table, mode) => `${table.tsName}${mode[0].toUpperCase()}${mode.slice(1)}`;
+var ref = (name) => ({ $ref: `#/components/schemas/${name}` });
+var pascal = (s) => s.charAt(0).toUpperCase() + s.slice(1);
+function keyColumns(table) {
+  const names = table.primaryKey?.columns ?? [];
+  if (!names.length) return null;
+  const cols = names.map((n) => table.columns.find((c) => c.name === n));
+  if (cols.some((c) => !c)) return null;
+  return cols;
+}
+var modesFor = (table, key) => [
+  ...table.readOnly ? [] : ["insert"],
+  ...table.readOnly || !key ? [] : ["update"],
+  "select"
+];
+var resourceSegment = (table) => encodeURIComponent(table.name);
+function foreignKeysOf(table) {
+  if (table.foreignKeys?.length) return table.foreignKeys;
+  return table.columns.filter((c) => c.references).map((c) => ({
+    columns: [c.name],
+    foreignTable: c.references.table,
+    foreignColumns: [c.references.column]
+  }));
+}
+var jsonBody = (schema) => ({ content: { "application/json": { schema } } });
+function build(tables, opts) {
+  const target = opts.target ?? "draft-2020-12";
+  const schemaTarget = target === "openapi-3.0" ? "openapi-3.0" : "openapi-3.1";
+  const failure = String(opts.validationStatus ?? 400);
+  const paths = {};
+  const schemas = {};
+  const tags = [];
+  const operationIds = /* @__PURE__ */ new Map();
+  const owner = /* @__PURE__ */ new Map();
+  const claim = (path, by, label) => {
+    const taken = owner.get(path);
+    if (taken !== void 0 && taken.by !== by) {
+      throw new Error(
+        `@drzl/generator-json-schema: the OpenAPI path "${path}" is claimed twice: by table "${taken.label}" (exported as ${taken.by}) and by table "${label}" (exported as ${by}). A path names one resource, so one of the two has to be left out of this generator with the config's "exclude" list.`
+      );
+    }
+    owner.set(path, { by, label });
+  };
+  const operation = (id, table, rest) => {
+    const clash = operationIds.get(id);
+    if (clash !== void 0) {
+      throw new Error(
+        `@drzl/generator-json-schema: the operationId "${id}" would be emitted for both "${clash}" and "${table.name}". An operationId is the method name a client generator derives, and the specification requires it to be unique across the document.`
+      );
+    }
+    operationIds.set(id, table.name);
+    return { operationId: id, tags: [table.name], ...rest };
+  };
+  const built = tables.map((table) => ({
+    table,
+    key: keyColumns(table),
+    segment: resourceSegment(table),
+    schemas: tableSchemas(table, { target: schemaTarget, applyDefaults: opts.applyDefaults })
+  }));
+  for (const { table, key, segment, schemas: built3 } of built) {
+    for (const mode of modesFor(table, key)) {
+      const { $schema: _dialect, $id: _id, ...rest } = built3[mode];
+      schemas[componentName(table, mode)] = rest;
+    }
+    const notes = [];
+    if (!key) notes.push("It has no primary key, so no path addresses a single row.");
+    if (table.readOnly) {
+      notes.push("It refuses every write, so only reads are described.");
+    }
+    tags.push({ name: table.name, description: [`Table "${table.name}".`, ...notes].join(" ") });
+    const T = pascal(table.tsName);
+    const select = ref(componentName(table, "select"));
+    const validationFailed = {
+      description: "The request does not match the schema for this operation.",
+      ...jsonBody(ref(ERROR_SCHEMA))
+    };
+    const collidable = [
+      ...table.primaryKey ? [`primary key (${table.primaryKey.columns.join(", ")})`] : [],
+      ...table.unique.map((u) => `${u.name ? `${u.name} ` : ""}(${u.columns.join(", ")})`)
+    ];
+    const conflict = (constraints) => ({
+      description: `The row collides with an existing one on ${constraints.join("; ")}.`,
+      ...jsonBody(ref(ERROR_SCHEMA))
+    });
+    const collection = `/${segment}`;
+    claim(collection, table.tsName, table.name);
+    const item = {
+      get: operation(`list${T}`, table, {
+        summary: `List every ${table.name} row.`,
+        // No pagination parameters. Whether the server implements a limit, an offset or a cursor is
+        // not something a Drizzle schema states, and a declared parameter nothing honours is worse
+        // than an undeclared one.
+        responses: {
+          "200": {
+            description: `Every ${table.name} row.`,
+            ...jsonBody({ type: "array", items: select })
+          }
+        }
+      })
+    };
+    if (!table.readOnly) {
+      item.post = operation(`create${T}`, table, {
+        summary: `Create a ${table.name} row.`,
+        requestBody: { required: true, ...jsonBody(ref(componentName(table, "insert"))) },
+        responses: {
+          "201": { description: `The ${table.name} row that was created.`, ...jsonBody(select) },
+          [failure]: validationFailed,
+          ...collidable.length ? { "409": conflict(collidable) } : {}
+        }
+      });
+    }
+    paths[collection] = item;
+    if (!key) continue;
+    const itemPath = `${collection}/${key.map((c) => `{${c.name}}`).join("/")}`;
+    claim(itemPath, table.tsName, table.name);
+    const parameters = key.map((c) => ({
+      name: c.name,
+      in: "path",
+      required: true,
+      description: `${c.name}, from the primary key of ${table.name}.`,
+      // The column's own schema rather than a string, so an integer key is declared as one and a
+      // uuid key carries its format. This is the whole point of reading the real key.
+      schema: built3.select.properties[c.name] ?? {}
+    }));
+    const missing = {
+      description: `No ${table.name} row has that ${key.map((c) => c.name).join(" and ")}.`,
+      ...jsonBody(ref(ERROR_SCHEMA))
+    };
+    const byId = {
+      parameters,
+      get: operation(`get${T}`, table, {
+        summary: `Read one ${table.name} row.`,
+        responses: {
+          "200": { description: `The requested ${table.name} row.`, ...jsonBody(select) },
+          [failure]: validationFailed,
+          "404": missing
+        }
+      })
+    };
+    if (!table.readOnly) {
+      byId.patch = operation(`update${T}`, table, {
+        summary: `Patch one ${table.name} row.`,
+        requestBody: { required: true, ...jsonBody(ref(componentName(table, "update"))) },
+        responses: {
+          "200": { description: `The ${table.name} row after the patch.`, ...jsonBody(select) },
+          [failure]: validationFailed,
+          "404": missing,
+          // The primary key is not in the update schema, so a patch cannot collide on it. Only a
+          // unique constraint over other columns can.
+          ...table.unique.length ? {
+            "409": conflict(
+              table.unique.map((u) => `${u.name ? `${u.name} ` : ""}(${u.columns.join(", ")})`)
+            )
+          } : {}
+        }
+      });
+      byId.delete = operation(`delete${T}`, table, {
+        summary: `Delete one ${table.name} row.`,
+        responses: {
+          // No body. Handing back the deleted row is the alternative and it is not a true statement
+          // on every dialect DRZL supports: RETURNING is Postgres and SQLite, and MySQL has no such
+          // clause, so an implementation there has nothing to send.
+          "204": { description: `The ${table.name} row was deleted. No content is returned.` },
+          [failure]: validationFailed,
+          "404": missing
+        }
+      });
+    }
+    paths[itemPath] = byId;
+    if (!opts.includeRelations) continue;
+    for (const child of built) {
+      if (child.table === table) continue;
+      const matching = foreignKeysOf(child.table).filter(
+        (fk) => fk.foreignTable === table.name && fk.foreignColumns.length === key.length && fk.foreignColumns.every((c, i) => c === key[i].name)
+      );
+      if (matching.length !== 1) continue;
+      const subPath = `${itemPath}/${child.segment}`;
+      claim(
+        subPath,
+        `${table.tsName} -> ${child.table.tsName}`,
+        `${table.name} -> ${child.table.name}`
+      );
+      paths[subPath] = {
+        parameters,
+        get: operation(`list${T}${pascal(child.table.tsName)}`, child.table, {
+          summary: `List the ${child.table.name} rows belonging to one ${table.name} row.`,
+          responses: {
+            "200": {
+              description: `The ${child.table.name} rows whose ${matching[0].columns.join(", ")} names this ${table.name} row.`,
+              ...jsonBody({ type: "array", items: ref(componentName(child.table, "select")) })
+            },
+            [failure]: validationFailed,
+            "404": missing
+          }
+        })
+      };
+    }
+  }
+  return { paths, schemas, tags };
+}
+var errorSchema = () => ({
+  title: "error",
+  description: "What an operation returns when it does not return the row.",
+  type: "object",
+  properties: {
+    message: { type: "string" },
+    code: { type: "string" }
+  },
+  required: ["message"],
+  additionalProperties: true
+});
+function openApiDocument(tables, opts = {}) {
+  const target = opts.target ?? "draft-2020-12";
+  const { paths, schemas, tags } = build(tables, opts);
+  if (ERROR_SCHEMA in schemas) {
+    throw new Error(
+      `@drzl/generator-json-schema: a table produced the component schema name "${ERROR_SCHEMA}", which the document already uses for its error responses.`
+    );
+  }
+  return {
+    openapi: target === "openapi-3.0" ? "3.0.3" : "3.1.1",
+    info: {
+      title: opts.info?.title ?? "API",
+      version: opts.info?.version ?? "0.0.0",
+      description: opts.info?.description ?? "Generated by DRZL from a Drizzle schema. Paths, request bodies and response bodies are derived from the schema alone; nothing here has been checked against a running server."
+    },
+    ...opts.servers?.length ? { servers: opts.servers } : {},
+    paths,
+    components: { schemas: { ...schemas, [ERROR_SCHEMA]: errorSchema() } },
+    tags
+  };
+}
+var DEFAULT_FILE_SUFFIX = ".schema.ts";
+function renderTableModule(table, affix, target, applyDefaults) {
+  const T = table.tsName;
+  const schemas = tableSchemas(table, { target, applyDefaults });
+  const decl = (mode) => `export const ${schemaName(mode, T, affix)} = ${JSON.stringify(schemas[mode], null, 2)} as const;
+
+export type ${typeName(mode, T, affix)} = typeof ${schemaName(mode, T, affix)};`;
+  return [decl("insert"), decl("update"), decl("select")].join("\n\n") + "\n";
+}
+function resolveDocument(opt) {
+  if (!opt) return null;
+  const o = opt === true ? {} : opt;
+  if (o.enabled === false) return null;
+  return { ...o, format: o.format ?? "ts" };
+}
+var JsonSchemaGenerator = class {
+  constructor(analysis) {
+    this.analysis = analysis;
+    this.library = "json-schema";
+  }
+  async generate(opts) {
+    const fs = await import("fs/promises");
+    const path = await import("path");
+    const out = path.resolve(process.cwd(), opts.outDir);
+    const files = [];
+    await fs.mkdir(out, { recursive: true });
+    const affix = resolveAffix(opts);
+    const fileSuffix = opts.fileSuffix ?? DEFAULT_FILE_SUFFIX;
+    const target = opts.target ?? "draft-2020-12";
+    const document = resolveDocument(opts.document);
+    for (const table of this.analysis.tables) {
+      const filePath = path.join(out, moduleFileName(table.tsName, fileSuffix));
+      const code = renderTableModule(table, affix, target, !!opts.applyDefaults);
+      const formatted = await formatCode(
+        buildHeader(opts.outputHeader) + code,
+        filePath,
+        opts.format
+      );
+      await fs.writeFile(filePath, formatted, "utf8");
+      files.push(filePath);
+    }
+    if (opts.components) {
+      const doc = componentsDocument(this.analysis.tables, {
+        target,
+        applyDefaults: !!opts.applyDefaults
+      });
+      const componentsPath = path.join(out, "components.ts");
+      const code = `export const components = ${JSON.stringify(doc, null, 2)} as const;
+`;
+      await fs.writeFile(
+        componentsPath,
+        await formatCode(buildHeader(opts.outputHeader) + code, componentsPath, opts.format),
+        "utf8"
+      );
+      files.push(componentsPath);
+    }
+    if (document) {
+      const built = openApiDocument(this.analysis.tables, {
+        target,
+        applyDefaults: !!opts.applyDefaults,
+        includeRelations: !!opts.includeRelations,
+        info: document.info,
+        servers: document.servers,
+        validationStatus: document.validationStatus
+      });
+      const body = JSON.stringify(built, null, 2);
+      if (document.format !== "json") {
+        const tsPath = path.join(out, "openapi.ts");
+        const code = `export const openapi = ${body} as const;
+`;
+        await fs.writeFile(
+          tsPath,
+          await formatCode(buildHeader(opts.outputHeader) + code, tsPath, opts.format),
+          "utf8"
+        );
+        files.push(tsPath);
+      }
+      if (document.format !== "ts") {
+        const jsonPath = path.join(out, "openapi.json");
+        await fs.writeFile(jsonPath, body + "\n", "utf8");
+        files.push(jsonPath);
+      }
+    }
+    const ext = opts.importExtension === "none" ? "" : ".js";
+    const indexPath = path.join(out, "index.ts");
+    const index = this.analysis.tables.map(
+      (t) => `export * from '${moduleSpecifier(t.tsName, fileSuffix, opts.importExtension)}';`
+    ).concat(opts.components ? [`export * from './components${ext}';`] : []).concat(document && document.format !== "json" ? [`export * from './openapi${ext}';`] : []).join("\n") + "\n";
+    const indexFormatted = await formatCode(
+      buildHeader(opts.outputHeader) + index,
+      indexPath,
+      opts.format
+    );
+    await fs.writeFile(indexPath, indexFormatted, "utf8");
+    files.push(indexPath);
+    return files;
+  }
+  renderTable(table, opts) {
+    return renderTableModule(
+      table,
+      resolveAffix(opts),
+      opts?.target ?? "draft-2020-12",
+      !!opts?.applyDefaults
+    );
+  }
+};
+var index_default = JsonSchemaGenerator;
+function buildHeader(h) {
+  if (h?.enabled === false) return "";
+  const text = h?.text ?? "// Generated by DRZL. Do not edit by hand.";
+  return `${text}
+
+`;
+}
+export {
+  DRAFT,
+  JsonSchemaGenerator,
+  componentsDocument,
+  index_default as default,
+  openApiDocument,
+  tableSchemas
+};
+//# sourceMappingURL=dist-TRJLPIWT.js.map