@peculiar/json-schema 1.1.12

Clean-room public code sample — generation instructions

Write a brand-new, minimal, self-contained code sample in this clean-room directory.
Do not copy, paraphrase, or reference any existing project source. Work only from this spec.

A csx.json manifest scaffold already exists. Do not recreate it from memory. Preserve its case.goal, packages and symbols; fill its empty case.contract with exact assertions and correct its environment, commands and verifierAdapter for the files you generate.

Goal: verify pkg:npm/%40peculiar/json-schema@1.1.12
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/%40peculiar/json-schema@1.1.12

Rules:
  - One focused purpose; the smallest project that proves the goal.
  - Include a contract test (test/contract.*) that runs OFFLINE and exits 0 exactly when the goal behavior works.
  - Pin every dependency with a lockfile so resolution is reproducible.
  - No secrets, credentials, or tokens. No real URLs (only example.com or localhost). No absolute paths.
  - No personal names, emails, company names, or project identifiers of any kind.
  - No binaries and no generated output (node_modules, dist, target, venv, .git, .env).
  - Keep it under 200 files and 256KB packed.

{"case":{"caseId":"case:sha256:dce3e6646b823e3fd1698e9122e11a8475039d3a1deacb1d6609b32b36e69456","contract":["assert JsonParser.parse deserializes JSON strings into typed class instances with property name mapping and type coercion","assert JsonSerializer.serialize and JsonSerializer.toJSON convert class instances into schema-conforming JSON representations","assert JsonProp supports nested schema classes and repeated array mappings","assert JsonProp supports custom converters via IJsonConverter for bidirectional data transformation","assert JsonParser throws ParserError on missing required fields or type mismatches and throws KeyError when strictProperty is enabled with unknown fields"],"goal":"verify pkg:npm/%40peculiar/json-schema@1.1.12","kind":"HOW","packages":["pkg:npm/%40peculiar/json-schema@1.1.12"],"schemaVersion":1,"symbols":["JsonParser.fromJSON","JsonParser.parse","JsonProp","JsonPropTypes","JsonSerializer.serialize","JsonSerializer.toJSON","KeyError","ParserError"]},"contractCommand":["node","test/contract.mjs"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","libc":"glibc","libcVersion":"2.39","os":"linux","osVersionBucket":"24","packageManager":"npm","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/%40peculiar/json-schema@1.1.12"],"schemaVersion":1,"subject":"pkg:npm/%40peculiar/json-schema@1.1.12","verifierAdapter":"node-typescript@1"}

{
  "name": "sample-peculiar-json-schema",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-peculiar-json-schema",
      "version": "1.0.0",
      "dependencies": {
        "@peculiar/json-schema": "1.1.12"
      }
    },
    "node_modules/@peculiar/json-schema": {
      "version": "1.1.12",
      "resolved": "https://registry.npmjs.org/@peculiar/json-schema/-/json-schema-1.1.12.tgz",
      "integrity": "sha512-coUfuoMeIB7B8/NMekxaDzLhaYmp0HZNPEjYRm9goRou8UZIC3z21s0sL9AWoCw4EG876QyO3kYrc61WNF9B/w==",
      "license": "MIT",
      "dependencies": {
        "tslib": "^2.0.0"
      },
      "engines": {
        "node": ">=8.0.0"
      }
    },
    "node_modules/tslib": {
      "version": "2.8.1",
      "resolved": "https://registry.npmjs.org/tslib/-/tslib-2.8.1.tgz",
      "integrity": "sha512-oJFu94HQb+KVduSUQL7wnpmqnfmLsOA/nAh6b6EH0wCEoK0/mPeXU6c3wKDV83MkOuHPRHtSXKKU99IBazS/2w==",
      "license": "0BSD"
    }
  }
}

{
  "name": "sample-peculiar-json-schema",
  "version": "1.0.0",
  "type": "module",
  "dependencies": {
    "@peculiar/json-schema": "1.1.12"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify pkg:npm/%40peculiar/json-schema@1.1.12",
  "kind": "HOW",
  "packages": [
    "pkg:npm/%40peculiar/json-schema@1.1.12"
  ]
}

import assert from "node:assert/strict";
import {
  JsonProp,
  JsonPropTypes,
  JsonParser,
  JsonSerializer,
  ParserError,
  KeyError,
} from "@peculiar/json-schema";

// Custom converter test for ISO timestamp conversion
const timestampConverter = {
  fromJSON(value) {
    return new Date(value);
  },
  toJSON(value) {
    return value.toISOString();
  },
};

// Nested class schema definition
class Address {
  constructor() {
    this.city = "";
    this.zip = 0;
  }
}
JsonProp({ type: JsonPropTypes.String })(Address.prototype, "city");
JsonProp({ type: JsonPropTypes.Number, name: "postal_code" })(Address.prototype, "zip");

// Main class schema definition
class UserProfile {
  constructor() {
    this.id = "";
    this.displayName = "";
    this.active = true;
    this.tags = [];
    this.address = new Address();
    this.createdAt = new Date();
    this.metadata = undefined;
  }
}
JsonProp({ type: JsonPropTypes.String, name: "user_id" })(UserProfile.prototype, "id");
JsonProp({ type: JsonPropTypes.String, minLength: 2 })(UserProfile.prototype, "displayName");
JsonProp({ type: JsonPropTypes.Boolean, optional: true })(UserProfile.prototype, "active");
JsonProp({ type: JsonPropTypes.String, repeated: true })(UserProfile.prototype, "tags");
JsonProp({ type: Address })(UserProfile.prototype, "address");
JsonProp({ converter: timestampConverter })(UserProfile.prototype, "createdAt");
JsonProp({ type: JsonPropTypes.Any, optional: true })(UserProfile.prototype, "metadata");

// Contract 1: JsonParser.parse deserializes JSON strings into typed class instances with property name mapping and type coercion
const inputJson = JSON.stringify({
  user_id: "usr_12345",
  displayName: "Alice",
  active: true,
  tags: ["admin", "dev"],
  address: {
    city: "Seoul",
    postal_code: 10001,
  },
  createdAt: "2026-01-01T00:00:00.000Z",
  metadata: { roles: [1, 2] },
});

const user = JsonParser.parse(inputJson, { targetSchema: UserProfile });
assert.ok(user instanceof UserProfile);
assert.equal(user.id, "usr_12345");
assert.equal(user.displayName, "Alice");
assert.equal(user.active, true);
assert.deepEqual(user.tags, ["admin", "dev"]);
assert.ok(user.address instanceof Address);
assert.equal(user.address.city, "Seoul");
assert.equal(user.address.zip, 10001);
assert.ok(user.createdAt instanceof Date);
assert.equal(user.createdAt.toISOString(), "2026-01-01T00:00:00.000Z");
assert.deepEqual(user.metadata, { roles: [1, 2] });

// Contract 2: JsonSerializer.serialize and JsonSerializer.toJSON convert class instances into schema-conforming JSON representations
const serializedObj = JsonSerializer.toJSON(user);
assert.equal(serializedObj.user_id, "usr_12345");
assert.equal(serializedObj.displayName, "Alice");
assert.equal(serializedObj.active, true);
assert.deepEqual(serializedObj.tags, ["admin", "dev"]);
assert.deepEqual(serializedObj.address, { city: "Seoul", postal_code: 10001 });
assert.equal(serializedObj.createdAt, "2026-01-01T00:00:00.000Z");
assert.deepEqual(serializedObj.metadata, { roles: [1, 2] });

const serializedJson = JsonSerializer.serialize(user);
const reParsed = JSON.parse(serializedJson);
assert.deepEqual(reParsed, serializedObj);

// Contract 3: JsonProp supports nested schema classes and repeated array mappings
const addressOnly = JsonParser.fromJSON({ city: "Busan", postal_code: 48000 }, { targetSchema: Address });
assert.ok(addressOnly instanceof Address);
assert.equal(addressOnly.city, "Busan");
assert.equal(addressOnly.zip, 48000);

// Contract 4: JsonProp supports custom converters via IJsonConverter for bidirectional data transformation
const roundTripUser = JsonParser.fromJSON(serializedObj, { targetSchema: UserProfile });
assert.ok(roundTripUser.createdAt instanceof Date);
assert.equal(roundTripUser.createdAt.getTime(), new Date("2026-01-01T00:00:00.000Z").getTime());

// Contract 5: JsonParser throws ParserError on missing required fields or type mismatches and throws KeyError when strictProperty is enabled with unknown fields
assert.throws(
  () => JsonParser.fromJSON({ displayName: "A" }, { targetSchema: UserProfile }),
  (err) => err instanceof ParserError
);

assert.throws(
  () =>
    JsonParser.fromJSON(
      {
        user_id: "usr_1",
        displayName: "Alice",
        tags: [],
        address: { city: "Seoul", postal_code: 10001 },
        createdAt: "2026-01-01T00:00:00.000Z",
        unknownField: 123,
      },
      { targetSchema: UserProfile, strictProperty: true }
    ),
  (err) => err instanceof KeyError
);

console.log("Contract verified: all assertions passed.");