@hyperscale0/sdk 1.0.338 → 1.0.340

package/product-types.js

@@ -0,0 +1,162 @@
+import { createClient } from "./client.js";
+
+const usage = `Usage: npx @hyperscale0/sdk types --product <prd_id> [--name ProductName]
+Reads HYPERSCALE_API_KEY, plus HYPERSCALE_BASE_URL and HYPERSCALE_ENVIRONMENT when set.`;
+
+// Code-unit order, so the output does not depend on the machine's locale.
+const byName = ([left], [right]) => (left < right ? -1 : left > right ? 1 : 0);
+
+// Stands in for a schema discovery left out, so the type still fits ProductTypes.
+const anyRecord = { type: "object" };
+
+const union = (members) => [...new Set(members)].join(" | ") || "never";
+
+const comment = (schema, indent) =>
+  typeof schema?.description === "string"
+    ? `${indent}/** ${schema.description.replace(/\s+/g, " ").replaceAll("*/", "*\\/")} */\n`
+    : "";
+
+/** One JSON Schema as a TypeScript type. Keywords it does not map read as unknown. */
+function typeOf(schema, indent) {
+  if (typeof schema !== "object" || schema === null) return "unknown";
+  if ("const" in schema) return JSON.stringify(schema.const);
+  if (Array.isArray(schema.enum))
+    return union(schema.enum.map((value) => JSON.stringify(value)));
+  const variants = schema.oneOf ?? schema.anyOf;
+  if (Array.isArray(variants))
+    return union(variants.map((variant) => typeOf(variant, indent)));
+  if (Array.isArray(schema.type))
+    return union(
+      schema.type.map((type) => typeOf({ ...schema, type }, indent)),
+    );
+  switch (schema.type) {
+    case "string":
+      return "string";
+    case "number":
+    case "integer":
+      return "number";
+    case "boolean":
+      return "boolean";
+    case "null":
+      return "null";
+    case "array":
+      return `ReadonlyArray<${typeOf(schema.items, indent)}>`;
+    case "object":
+      return objectType(schema, indent);
+    default:
+      return "unknown";
+  }
+}
+
+function objectType(schema, indent) {
+  const inner = `${indent}  `;
+  const properties = Object.entries(schema.properties ?? {}).sort(byName);
+  const required = new Set(schema.required ?? []);
+  const extra = schema.additionalProperties;
+  const lines = properties.map(
+    ([name, property]) =>
+      `${comment(property, inner)}${inner}readonly ${JSON.stringify(name)}${required.has(name) ? "" : "?"}: ${typeOf(property, inner)};`,
+  );
+  if (extra === false && properties.length === 0)
+    return "{ readonly [key: string]: never }";
+  // A named property's type must fit the index signature, so beside named
+  // properties the extra values read as unknown.
+  if (extra !== false && (properties.length === 0 || extra !== undefined))
+    lines.push(
+      `${inner}readonly [key: string]: ${properties.length === 0 ? typeOf(extra, inner) : "unknown"};`,
+    );
+  return `{\n${lines.join("\n")}\n${indent}}`;
+}
+
+/** A key and how to render its type at an indent, with an optional doc line. */
+function block(entries, indent) {
+  if (entries.length === 0) return "{}";
+  const inner = `${indent}  `;
+  const lines = entries
+    .sort(byName)
+    .map(
+      ([key, render, description]) =>
+        `${comment({ description }, inner)}${inner}${key}: ${render(inner)};`,
+    );
+  return `{\n${lines.join("\n")}\n${indent}}`;
+}
+
+function kindType(kind, indent) {
+  // Node 20 has no Map.groupBy.
+  const variants = new Map();
+  for (const action of kind.actions)
+    variants.set(action.name, [...(variants.get(action.name) ?? []), action]);
+  const actions = [...variants].map(([name, entries]) => [
+    JSON.stringify(name),
+    (inner) =>
+      union(
+        entries.map((action) =>
+          block(
+            [
+              ["fields", (at) => typeOf(action.fieldsSchema ?? anyRecord, at)],
+              ["input", (at) => typeOf(action.inputSchema ?? anyRecord, at)],
+            ],
+            inner,
+          ),
+        ),
+      ),
+  ]);
+  return block(
+    [
+      [
+        "fields",
+        (inner) =>
+          typeOf(kind.createSchema?.properties?.fields ?? anyRecord, inner),
+      ],
+      ["actions", (inner) => block(actions, inner)],
+    ],
+    indent,
+  );
+}
+
+/**
+ * The declaration source for one Product, from its product.objects.discover
+ * output. The same discovery gives the same bytes, so a regenerated file
+ * diffs only where the Product changed.
+ */
+export function productTypes(discovery, name = "Product") {
+  if (!/^[A-Za-z_$][\w$]*$/.test(name))
+    throw new Error(`${name} is not a TypeScript type name`);
+  const kinds = discovery.kinds.map((kind) => [
+    JSON.stringify(kind.kind),
+    (inner) => kindType(kind, inner),
+    kind.title,
+  ]);
+  return `// Generated by \`npx @hyperscale0/sdk types\` from product.objects.discover.
+// Regenerate after each publish instead of editing it.
+export interface ${name} ${block([["kinds", (inner) => block(kinds, inner)]], "")}
+`;
+}
+
+/** `types --product <prd_id> [--name ProductName]`: the declaration, or an Error. */
+export async function typesCommand(args, env) {
+  const [command, ...rest] = args;
+  const flags = {};
+  for (let index = 0; index < rest.length; index += 2) {
+    const flag = rest[index];
+    const value = rest[index + 1];
+    if (!["--product", "--name"].includes(flag) || value === undefined)
+      throw new Error(usage);
+    flags[flag.slice(2)] = value;
+  }
+  const productId = flags.product ?? env.HYPERSCALE_PRODUCT_ID;
+  if (command !== "types" || !productId) throw new Error(usage);
+  if (!env.HYPERSCALE_API_KEY)
+    throw new Error(
+      "Set HYPERSCALE_API_KEY to a key from `hyperscale key create --product <id>`.",
+    );
+  const client = createClient({
+    apiKey: env.HYPERSCALE_API_KEY,
+    productId,
+    ...(env.HYPERSCALE_BASE_URL ? { baseUrl: env.HYPERSCALE_BASE_URL } : {}),
+    ...(env.HYPERSCALE_ENVIRONMENT
+      ? { environment: env.HYPERSCALE_ENVIRONMENT }
+      : {}),
+  });
+  return productTypes(await client.discover(), flags.name);
+}