Open-source manufacturing ERP, MES and QMS. Quoting, MRP, inventory, shop floor, quality and lot/serial traceability on one Postgres schema, with a REST API and MCP server. Self-host or use Carbon Cloud.
TypeScript ai-agentsbill-of-materialserpinventory-managementleanmanufacturingmanufacturing-execution-systemmcp-servermesmrpopen-source-erppostgresqlproduction-planningqmsquality-management-systemreact-routerself-hostedsupabasetraceabilitytypescript
// SPDX-License-Identifier: AGPL-3.0-only
// Carbon (github.com/crbnos/carbon). Modified or adapted versions of this file,
// including ports, remain AGPLv3; serving them over a network requires releasing their source.
/**
* A TypeScript type as a JSON Schema, read with ts-morph: a service
* function's input and its response. Nothing declares a response — it is
* whatever `run` returns — and supabase-js infers the SELECTED columns from the
* select string, so the compiler already knows the exact row shape.
*/
import { Node, type Type } from "ts-morph";
export type JsonSchema = Record<string, unknown>;
/**
* Rows are wide (40+ columns) and embeds nest, so an uncapped walk can emit a
* megabyte for one operation. Depth 6 covers the deepest real select — a row, an
* embedded array, an embed of that, and their columns — which is where PostgREST
* embeds actually stop. Measured: 5 and 6 cost 1.6 MB and 1.7 MB against 1.6 MB at
* 4, so the cap is not what the size hinges on; capping too SHALLOW is visible,
* since a truncated branch renders as a column of nulls in the docs sample.
*/
const MAX_DEPTH = 6;
/** A guard against pathological types, not a real limit — real rows sit well under. */
const MAX_PROPERTIES = 120;
/**
* Collections `JSON.stringify` writes as `{}` — their members are methods and
* symbol-keyed slots, none of which reach the wire. Walking them emitted the
* checker's per-program symbol ids (`__@toStringTag@75448`) as property names,
* so an unrelated edit anywhere renumbered them and flipped the tool's digest.
*/
const JSON_OPAQUE_COLLECTIONS = new Set([
"Map",
"ReadonlyMap",
"WeakMap",
"Set",
"ReadonlySet",
"WeakSet"
]);
/**
* Peel the layers between the declared return type and the payload a caller sees:
* `Promise<PostgrestSingleResponse<T>>` and the hand-rolled
* `Promise<{ data: T | null; error }>` both reduce to `T`.
*
* This mirrors the result readers (`unwrap`, `paged` in
* `@carbon/api/service-tools.server`), which unwrap the Supabase result to its
* `data` — so the schema describes what a caller receives, not the driver's
* envelope.
*/
export function unwrapResponseType(type: Type, at: Node): Type {
let current = type;
for (let i = 0; i < 5; i++) {
const name =
current.getSymbol()?.getName() ?? current.getAliasSymbol()?.getName();
const args = current.getTypeArguments();
if ((name === "Promise" || /^Postgrest\w*Response$/.test(name ?? "")) && args.length > 0) {
current = args[0];
continue;
}
// `{ data: T | null; error: ... }` — the shape services hand-roll.
const data = current.getProperty("data");
if (data && current.getProperty("error")) {
const dataType = data.getTypeAtLocation(at);
current = stripNullish(dataType);
continue;
}
break;
}
return current;
}
function stripNullish(type: Type): Type {
if (!type.isUnion()) return type;
const concrete = type
.getUnionTypes()
.filter((t) => !t.isNull() && !t.isUndefined());
return concrete.length === 1 ? concrete[0] : type;
}
/**
* Walk a TypeScript type into JSON Schema.
*
* `at` is the node types are resolved against (the function declaration) — a
* property's type is only meaningful at a location. `seen` carries the type-text of
* every ancestor so a self-referential type (a tree node, a row embedding its own
* table) terminates instead of recursing forever.
*/
export function typeToJsonSchema(
type: Type,
at: Node,
depth = 0,
seen: ReadonlySet<string> = new Set(),
/** For an INPUT: `undefined` means "may be left out", which `required`
* already says, so it is dropped instead of read as `null`. */
undefinedIsAbsent = false
): JsonSchema {
if (depth > MAX_DEPTH) return {};
if (type.isString()) return { type: "string" };
if (type.isNumber()) return { type: "number" };
if (type.isBoolean()) return { type: "boolean" };
if (type.isNull() || type.isUndefined()) return { type: "null" };
if (type.isAny() || type.isUnknown()) return {};
if (type.isStringLiteral()) {
return { type: "string", enum: [type.getLiteralValue()] };
}
if (type.isNumberLiteral()) {
return { type: "number", enum: [type.getLiteralValue()] };
}
if (type.isBooleanLiteral()) return { type: "boolean" };
if (type.isArray()) {
const element = type.getArrayElementType();
return {
type: "array",
items: element
? typeToJsonSchema(element, at, depth + 1, seen, undefinedIsAbsent)
: {}
};
}
// A tuple or a readonly array is a list on the wire too. Neither is
// `isArray()`, so both fell through to the object walk and came out as a map
// (`typeof riskStatus`, an `as const` list, read as `Record<string, status>`).
if (type.isTuple() || type.isReadonlyArray()) {
const element = type.getNumberIndexType();
return {
type: "array",
items: element
? typeToJsonSchema(element, at, depth + 1, seen, undefinedIsAbsent)
: {}
};
}
if (type.isUnion()) {
return unionToJsonSchema(type, at, depth, seen, undefinedIsAbsent);
}
if (type.isObject()) {
const symbolName = type.getSymbol()?.getName();
if (symbolName && JSON_OPAQUE_COLLECTIONS.has(symbolName)) {
return { type: "object" };
}
// The checker's own type id, NOT `type.getText()`. getText() serializes the
// whole structural type to a string, and a supabase row with embeds
// serializes to a very large one — paying that at every object node was
// measured at 5.2s of a 5.2s walk, i.e. effectively the entire cost of
// walking 1574 return types. The id is O(1), it is only ever a Map key here
// (never emitted — that is the `__@toStringTag@75448` trap noted above), and
// it is per-program so it stays valid for the one walk that uses it.
// Verified byte-identical over all 1574 functions.
const key = String(
(type.compilerType as unknown as { id?: number }).id ?? type.getText()
);
// Cycle: the type is already being expanded further up this branch.
if (seen.has(key)) return { type: "object" };
const nextSeen = new Set(seen).add(key);
// `Record<K, V>` / any index signature. TypeScript reports these as an object
// with ZERO NAMED PROPERTIES, so a plain property walk emits a bare
// `{type:"object"}` and the map's value type is lost — that alone accounted for
// 9 operations with no usable response, plus every Record nested inside one
// that otherwise worked. `additionalProperties` is the JSON Schema equivalent,
// and the docs SchemaTable already renders it as `Record<string, …>`.
const indexValue =
type.getStringIndexType() ?? type.getNumberIndexType() ?? undefined;
const additional = indexValue
? typeToJsonSchema(indexValue, at, depth + 1, nextSeen, undefinedIsAbsent)
: undefined;
// Symbol-keyed members (`[Symbol.iterator]`, reported as `__@iterator@206`)
// are dropped by JSON.stringify, and their names carry unstable checker ids.
const properties = type
.getProperties()
.filter((property) => !property.getName().startsWith("__@"));
// A map with named keys too (a zod `looseObject`: its fields plus any
// other key) publishes both; a bare map only its value type.
if (properties.length === 0) {
return additional
? { type: "object", additionalProperties: additional }
: { type: "object" };
}
if (properties.length > MAX_PROPERTIES) return { type: "object" };
const shape: Record<string, unknown> = {};
const required: string[] = [];
for (const property of properties) {
const propertyType = property.getTypeAtLocation(at);
shape[property.getName()] = typeToJsonSchema(
propertyType,
at,
depth + 1,
nextSeen,
undefinedIsAbsent
);
if (!property.isOptional()) required.push(property.getName());
}
const out: JsonSchema = { type: "object", properties: shape };
if (required.length > 0) out.required = required;
if (additional) out.additionalProperties = additional;
return out;
}
return {};
}
function unionToJsonSchema(
type: Type,
at: Node,
depth: number,
seen: ReadonlySet<string>,
undefinedIsAbsent: boolean
): JsonSchema {
const members = type.getUnionTypes();
const concrete = members.filter((t) => !t.isNull() && !t.isUndefined());
const nullable = members.some(
(t) => t.isNull() || (!undefinedIsAbsent && t.isUndefined())
);
// A union of string literals is an enum — the single most useful thing this
// reflection recovers, and invisible in a hand-written response example.
if (concrete.length > 0 && concrete.every((t) => t.isStringLiteral())) {
return {
type: nullable ? ["string", "null"] : "string",
enum: concrete.map((t) => t.getLiteralValue())
};
}
// `boolean` is internally `true | false`; keep it as one type.
if (concrete.length > 0 && concrete.every((t) => t.isBooleanLiteral())) {
return { type: nullable ? ["boolean", "null"] : "boolean" };
}
if (concrete.length === 1) {
const inner = typeToJsonSchema(
concrete[0],
at,
depth,
seen,
undefinedIsAbsent
);
if (nullable && typeof inner.type === "string") {
return { ...inner, type: [inner.type, "null"] };
}
return inner;
}
// Dedupe: `boolean` is internally `true | false`, so a MIXED union (the `Json`
// type is the common one — string | number | boolean | object | array) yields two
// identical `{type:"boolean"}` members. The all-boolean shortcut above only fires
// when every member is a boolean literal, so mixed unions need this.
const anyOf = dedupe(
concrete.map((t) =>
typeToJsonSchema(t, at, depth + 1, seen, undefinedIsAbsent)
)
);
if (anyOf.length === 1 && !nullable) return anyOf[0];
return nullable ? { anyOf: [...anyOf, { type: "null" }] } : { anyOf };
}
function dedupe(schemas: JsonSchema[]): JsonSchema[] {
const seen = new Set<string>();
const out: JsonSchema[] = [];
for (const schema of schemas) {
const key = JSON.stringify(schema);
if (seen.has(key)) continue;
seen.add(key);
out.push(schema);
}
return out;
}