@supawatch/target-json-schema 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Omar Dulaimi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,23 @@
+# @supawatch/target-json-schema
+
+The JSON Schema target for
+[supawatch](https://github.com/omar-dulaimi/supawatch). Emits one draft-07
+schema per table describing the row as the driver returns it, for API docs,
+cross-language validation, and anything else that speaks JSON Schema.
+
+Configure it in `supawatch.config.ts` (the CLI loads this package by name):
+
+```ts
+targets: [{ kind: "json-schema", strict: true }]
+```
+
+`strict` (default) sets `additionalProperties: false`. The target carries
+its own Ajv verifier, so generated schemas are ground-truth checked against
+real rows like every validator target.
+
+Honest limit: JSON Schema cannot express JS `Date` or `Uint8Array`
+instances, so timestamp and bytea columns emit an accept-anything schema
+with a `$comment` saying why. The alternative, claiming `string`, would
+reject every real driver row.
+
+MIT.

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+import type { Rendered, Snapshot, Table, Target, TargetCapabilities, TargetOptions, Verifier } from "@supawatch/core";
+export type JsonSchemaTargetOptions = TargetOptions;
+export declare function exportNameFor(table: Table): string;
+export declare class JsonSchemaTarget implements Target<JsonSchemaTargetOptions> {
+    readonly name = "json-schema";
+    readonly fileExtension = ".schema.json";
+    readonly barrel = false;
+    readonly capabilities: TargetCapabilities;
+    renderTable(table: Table, _snapshot: Snapshot, opts: JsonSchemaTargetOptions): Rendered;
+    assembleFile(rendered: Rendered): string;
+    verifier(): Verifier;
+}
+export default JsonSchemaTarget;

package/dist/index.js

@@ -0,0 +1,93 @@
+import { readFileSync } from "node:fs";
+import { Ajv } from "ajv";
+// JSON Schema has no type for JS Date instances or Uint8Array; those
+// columns get an accept-anything schema with a $comment saying why. The
+// honest alternative would be claiming "string", which would reject every
+// real driver row and fail ground truth.
+function schemaFor(runtime) {
+    switch (runtime.kind) {
+        case "number":
+            return runtime.integer ? { type: "integer" } : { type: "number" };
+        case "string":
+            return { type: "string" };
+        case "boolean":
+            return { type: "boolean" };
+        case "date":
+            return { $comment: "JS Date instance at runtime; not expressible in JSON Schema" };
+        case "bytes":
+            return { $comment: "Uint8Array at runtime; not expressible in JSON Schema" };
+        case "json":
+        case "unknown":
+            return {};
+        case "array":
+            return { type: "array", items: schemaFor(runtime.element) };
+        case "enum":
+            return { enum: runtime.labels };
+    }
+}
+function fieldSchema(col) {
+    const base = schemaFor(col.runtime);
+    if (!col.nullable)
+        return base;
+    if (Object.keys(base).length === 0 || !("type" in base) && !("enum" in base)) {
+        return base; // accept-anything already includes null
+    }
+    return { anyOf: [base, { type: "null" }] };
+}
+export function exportNameFor(table) {
+    return table.name.replace(/[^a-zA-Z0-9_]/g, "_") + "Row";
+}
+export class JsonSchemaTarget {
+    name = "json-schema";
+    fileExtension = ".schema.json";
+    barrel = false;
+    capabilities = {
+        strictObjects: true,
+        brandedTypes: false,
+        dateInstances: false,
+    };
+    renderTable(table, _snapshot, opts) {
+        const strict = opts.strict !== false;
+        const properties = {};
+        for (const col of table.columns) {
+            properties[col.name] = fieldSchema(col);
+        }
+        const schema = {
+            $schema: "http://json-schema.org/draft-07/schema#",
+            $id: `${table.schema}.${table.name}`,
+            $comment: "Generated by supawatch. Do not edit. Shapes follow driver runtime values.",
+            type: "object",
+            properties,
+            required: table.columns.map((c) => c.name),
+            additionalProperties: !strict,
+        };
+        return {
+            imports: [],
+            body: JSON.stringify(schema, null, 2) + "\n",
+            exportName: exportNameFor(table),
+        };
+    }
+    assembleFile(rendered) {
+        return rendered.body;
+    }
+    verifier() {
+        const ajv = new Ajv({ strict: false, allowUnionTypes: true });
+        return {
+            async load(file, _exportName) {
+                const schema = JSON.parse(readFileSync(file, "utf8"));
+                return ajv.compile(schema);
+            },
+            check(schema, value) {
+                const validate = schema;
+                if (validate(value))
+                    return { ok: true };
+                const first = validate.errors?.[0];
+                return {
+                    ok: false,
+                    reason: first ? `${first.instancePath} ${first.message ?? ""}`.trim() : "invalid",
+                };
+            },
+        };
+    }
+}
+export default JsonSchemaTarget;

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@supawatch/target-json-schema",
+  "version": "0.2.0",
+  "description": "Draft-07 JSON Schemas generated from live Postgres by supawatch, Ajv-verified against real rows.",
+  "keywords": [
+    "supabase",
+    "postgres",
+    "postgresql",
+    "codegen",
+    "schema",
+    "typescript",
+    "json-schema",
+    "ajv",
+    "validation",
+    "openapi"
+  ],
+  "license": "MIT",
+  "author": "Omar Dulaimi",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/omar-dulaimi/supawatch.git",
+    "directory": "packages/target-json-schema"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "ajv": "^8.17.0",
+    "@supawatch/core": "0.2.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.1",
+    "typescript": "^5.9.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json"
+  }
+}