@eslint/object-schema 3.0.5: ObjectSchema validates, merges, and normalizes configuration objects in @eslint/object-schema 3.0.5

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: ObjectSchema validates, merges, and normalizes configuration objects in @eslint/object-schema 3.0.5
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/%40eslint/object-schema@3.0.5
Demonstrate these symbols/APIs:
  - ObjectSchema

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:162cd69c59c7e994ccfc3dcf8bc295acaab2f05c234d7b6c9e107ac2e5bc5af6","contract":["ObjectSchema validates objects against schema definitions and rejects unexpected keys, missing required keys, and invalid types","ObjectSchema enforces dependency relationships where a key requires other keys to be present","ObjectSchema merges multiple objects using built-in overwrite, replace, and assign merge strategies","ObjectSchema supports custom validation and merge functions, retaining previous values or omitting keys when merge returns undefined","ObjectSchema validates and merges nested object structures using subschemas","ValidationStrategy and MergeStrategy provide static utility functions for primitive and complex data types"],"goal":"ObjectSchema validates, merges, and normalizes configuration objects in @eslint/object-schema 3.0.5","kind":"HOW","packages":["pkg:npm/%40eslint/object-schema@3.0.5"],"schemaVersion":1,"symbols":["ObjectSchema"]},"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/%40eslint/object-schema@3.0.5"],"schemaVersion":1,"subject":"pkg:npm/%40eslint/object-schema@3.0.5","symbols":["ObjectSchema"],"verifierAdapter":"node-typescript@1"}

{
  "name": "sample-eslint-object-schema",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-eslint-object-schema",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "@eslint/object-schema": "3.0.5"
      }
    },
    "node_modules/@eslint/object-schema": {
      "version": "3.0.5",
      "resolved": "https://registry.npmjs.org/@eslint/object-schema/-/object-schema-3.0.5.tgz",
      "integrity": "sha512-vqTaUEgxzm+YDSdElad6PiRoX4t8VGDjCtt05zn4nU810UIx/uNEV7/lZJ6KwFThKZOzOxzXy48da+No7HZaMw==",
      "license": "Apache-2.0",
      "engines": {
        "node": "^20.19.0 || ^22.13.0 || >=24"
      }
    }
  }
}

{
  "name": "sample-eslint-object-schema",
  "version": "1.0.0",
  "type": "module",
  "license": "MIT-0",
  "dependencies": {
    "@eslint/object-schema": "3.0.5"
  }
}

{
  "schemaVersion": 1,
  "goal": "ObjectSchema validates, merges, and normalizes configuration objects in @eslint/object-schema 3.0.5",
  "kind": "HOW",
  "packages": [
    "pkg:npm/%40eslint/object-schema@3.0.5"
  ],
  "symbols": [
    "ObjectSchema"
  ]
}

import assert from 'node:assert/strict';
import { ObjectSchema, MergeStrategy, ValidationStrategy } from '@eslint/object-schema';

// 1. ObjectSchema validates objects against schema definitions and rejects unexpected keys, missing required keys, and invalid types
const basicSchema = new ObjectSchema({
  name: {
    required: true,
    merge: 'replace',
    validate: 'string!'
  },
  age: {
    merge: 'overwrite',
    validate: 'number'
  },
  tags: {
    merge: 'assign',
    validate: 'array'
  },
  active: {
    merge: 'overwrite',
    validate: 'boolean'
  }
});

assert.equal(basicSchema.hasKey('name'), true);
assert.equal(basicSchema.hasKey('unknown'), false);

// Valid object passes
assert.doesNotThrow(() => {
  basicSchema.validate({
    name: 'sample',
    age: 25,
    tags: ['node', 'eslint'],
    active: true
  });
});

// Missing required key throws
assert.throws(
  () => {
    basicSchema.validate({ age: 25, tags: ['node'], active: true });
  },
  { message: 'Missing required key "name".' }
);

// Unexpected key throws
assert.throws(
  () => {
    basicSchema.validate({ name: 'sample', extraKey: true });
  },
  { message: 'Unexpected key "extraKey" found.' }
);

// Invalid type throws
assert.throws(
  () => {
    basicSchema.validate({ name: 'sample', age: 'not-a-number' });
  },
  { message: /Key "age": Expected a number\./ }
);

// 2. ObjectSchema enforces dependency relationships where a key requires other keys to be present
const dependentSchema = new ObjectSchema({
  host: {
    merge: 'replace',
    validate: 'string!'
  },
  port: {
    merge: 'replace',
    validate: 'number',
    requires: ['host']
  }
});

assert.doesNotThrow(() => {
  dependentSchema.validate({ host: 'localhost', port: 8080 });
});

assert.throws(
  () => {
    dependentSchema.validate({ port: 8080 });
  },
  { message: 'Key "port" requires keys "host".' }
);

// 3. ObjectSchema merges multiple objects using built-in overwrite, replace, and assign merge strategies
const mergeSchema = new ObjectSchema({
  title: {
    merge: 'overwrite',
    validate: 'string'
  },
  timeout: {
    merge: 'replace',
    validate: 'number'
  },
  headers: {
    merge: 'assign',
    validate: 'object'
  }
});

const baseConfig = {
  title: 'initial',
  timeout: 5000,
  headers: { 'Content-Type': 'application/json', 'X-Version': '1.0' }
};

const overrideConfig = {
  title: 'updated',
  headers: { 'X-Version': '2.0', Authorization: 'Bearer token' }
};

const merged = mergeSchema.merge(baseConfig, overrideConfig);
assert.equal(merged.title, 'updated');
assert.equal(merged.timeout, 5000);
assert.deepEqual(merged.headers, {
  'Content-Type': 'application/json',
  'X-Version': '2.0',
  Authorization: 'Bearer token'
});

// 4. ObjectSchema supports custom validation and merge functions, retaining previous values or omitting keys when merge returns undefined
const customSchema = new ObjectSchema({
  score: {
    validate(val) {
      if (val === 'omit') return;
      if (typeof val !== 'number' || val < 0 || val > 100) {
        throw new RangeError('Score must be a number between 0 and 100.');
      }
    },
    merge(first = 0, second) {
      if (second === 'omit') {
        return undefined; // undefined prevents setting or updating key
      }
      return typeof second === 'number' ? first + second : first;
    }
  }
});

assert.doesNotThrow(() => {
  customSchema.validate({ score: 95 });
});

assert.throws(
  () => {
    customSchema.validate({ score: 150 });
  },
  { message: /Score must be a number between 0 and 100\./ }
);

const scoreMerged = customSchema.merge({ score: 30 }, { score: 20 });
assert.equal(scoreMerged.score, 50);

// Merging with undefined return value omits new key on empty object
const scoreOmitted = customSchema.merge({}, { score: 'omit' });
assert.equal('score' in scoreOmitted, false);

// Merging with undefined return value retains existing value
const scoreRetained = customSchema.merge({ score: 50 }, { score: 'omit' });
assert.equal(scoreRetained.score, 50);

// 5. ObjectSchema validates and merges nested object structures using subschemas
const nestedSchema = new ObjectSchema({
  service: {
    merge: 'replace',
    validate: 'string!'
  },
  database: {
    schema: {
      host: {
        merge: 'replace',
        validate: 'string!'
      },
      port: {
        merge: 'overwrite',
        validate: 'number'
      }
    }
  }
});

assert.doesNotThrow(() => {
  nestedSchema.validate({
    service: 'auth',
    database: { host: 'db.internal', port: 5432 }
  });
});

assert.throws(
  () => {
    nestedSchema.validate({
      service: 'auth',
      database: { host: 12345, port: 5432 }
    });
  },
  { message: /Expected a non-empty string\./ }
);

const mergedNested = nestedSchema.merge(
  { service: 'auth', database: { host: 'db.internal', port: 5432 } },
  { service: 'auth', database: { port: 5433 } }
);
assert.deepEqual(mergedNested.database, { host: 'db.internal', port: 5433 });

// 6. ValidationStrategy and MergeStrategy provide static utility functions for primitive and complex data types
assert.doesNotThrow(() => {
  ValidationStrategy.string('valid');
  ValidationStrategy['string!']('non-empty');
  ValidationStrategy.number(42);
  ValidationStrategy.boolean(false);
  ValidationStrategy.array(['a', 'b']);
  ValidationStrategy.object({ key: 'val' });
  ValidationStrategy['object?'](null);
});

assert.throws(() => ValidationStrategy['string!'](''), { message: 'Expected a non-empty string.' });
assert.throws(() => ValidationStrategy.number('not a number'), { message: 'Expected a number.' });
assert.throws(() => ValidationStrategy.array({}), { message: 'Expected an array.' });

assert.equal(MergeStrategy.overwrite('first', 'second'), 'second');
assert.equal(MergeStrategy.replace('first', undefined), 'first');
assert.equal(MergeStrategy.replace('first', 'second'), 'second');
assert.deepEqual(MergeStrategy.assign({ a: 1, b: 2 }, { b: 3, c: 4 }), { a: 1, b: 3, c: 4 });