@versionzero/schema 1.0.0

package/src/core-library/processors/ipv4-constraint.js

@@ -0,0 +1,188 @@
+import { ConstraintError, ResolverError } from '../../errors.js';
+
+const IPV4_REGEX = /^((25[0-5]|(2[0-4]|1\d|[1-9]|)\d)\.?\b){4}$/;
+
+/**
+ * Parse a dotted-decimal IPv4 string into a 32-bit unsigned integer.
+ * @param {string} ip
+ * @returns {number}
+ */
+function ipToUint32(ip) {
+  const [a, b, c, d] = ip.split('.').map(Number);
+  return ((a << 24) | (b << 16) | (c << 8) | d) >>> 0;
+}
+
+/**
+ * Parse a CIDR string (e.g. '192.168.1.0/24') into network and mask as uint32.
+ * @param {string} cidr
+ * @returns {{ network: number, mask: number }}
+ */
+function parseCIDR(cidr) {
+  const [ip, bitsStr] = cidr.split('/');
+  const bits = Number(bitsStr);
+  if (!IPV4_REGEX.test(ip) || !Number.isInteger(bits) || bits < 0 || bits > 32) {
+    throw new ResolverError(`Invalid CIDR notation: ${cidr}`);
+  }
+  const mask = bits === 0 ? 0 : (~0 << (32 - bits)) >>> 0;
+  const network = ipToUint32(ip) & mask;
+  return { network, mask };
+}
+
+/**
+ * Check whether an IPv4 uint32 falls within a CIDR range.
+ * @param {number} ip
+ * @param {{ network: number, mask: number }} cidr
+ * @returns {boolean}
+ */
+function isInCIDR(ip, cidr) {
+  return (ip & cidr.mask) === cidr.network;
+}
+
+/** @type {Record<string, { network: number, mask: number }[]>} */
+const NAMED_RANGES = {
+  rfc1918: [
+    parseCIDR('10.0.0.0/8'),
+    parseCIDR('172.16.0.0/12'),
+    parseCIDR('192.168.0.0/16'),
+  ],
+  loopback: [
+    parseCIDR('127.0.0.0/8'),
+  ],
+  'link-local': [
+    parseCIDR('169.254.0.0/16'),
+  ],
+  rfc6598: [
+    parseCIDR('100.64.0.0/10'),
+  ],
+  multicast: [
+    parseCIDR('224.0.0.0/4'),
+  ],
+};
+
+NAMED_RANGES['non-routable'] = [
+  ...NAMED_RANGES.rfc1918,
+  ...NAMED_RANGES.loopback,
+  ...NAMED_RANGES['link-local'],
+  ...NAMED_RANGES.rfc6598,
+];
+
+/**
+ * Resolve an `in` parameter value to an array of CIDR ranges.
+ * Accepts a named range (e.g. 'rfc1918') or a CIDR string (e.g. '10.0.0.0/8').
+ * @param {string} spec
+ * @returns {{ network: number, mask: number }[]}
+ */
+function resolveRange(spec) {
+  const named = NAMED_RANGES[spec.toLowerCase()];
+  if (named) return named;
+  if (spec.includes('/')) return [parseCIDR(spec)];
+  throw new ResolverError(`Unknown IPv4 range: "${spec}" (expected CIDR or one of: ${Object.keys(NAMED_RANGES).join(', ')})`);
+}
+
+/**
+ * ## $ipv4
+ *
+ * Validates that a string is a valid IPv4 address in dotted-decimal notation.
+ *
+ * ### Parameters
+ * - `in` (string, optional): Network range to validate against. Accepts CIDR
+ *   notation (e.g. `'192.168.1.0/24'`) or a named range: `rfc1918`, `loopback`,
+ *   `link-local`, `rfc6598`, `multicast`, `non-routable`.
+ * - `min` (string, optional): Minimum IPv4 address (inclusive).
+ * - `max` (string, optional): Maximum IPv4 address (inclusive).
+ * - `format` (string, optional): Output format — `'integer'` emits the address
+ *   as a uint32. Default passes through the original dotted-decimal string.
+ *
+ * Use either `in` OR `min`/`max`, not both.
+ *
+ * ### Example
+ * ```js
+ * // Format-only validation
+ * new Schema('string').validator('$ipv4')
+ *
+ * // CIDR range (positional `in`)
+ * new Schema('string').validator({$ipv4: '192.168.1.0/24'})
+ *
+ * // Named range
+ * new Schema('string').validator({$ipv4: 'rfc1918'})
+ *
+ * // Explicit min/max
+ * new Schema('string').validator({$ipv4: {min: '192.168.1.1', max: '192.168.1.254'}})
+ *
+ * // Output as uint32
+ * new Schema('string').validator({$ipv4: {in: 'rfc1918', format: 'integer'}})
+ * ```
+ *
+ * @type {import("../../value-processor/value-processor.js").ValueProcessorDefinition}
+ */
+export const IPV4_CONSTRAINT = {
+  keyword: 'ipv4',
+
+  parameters: [
+    { parameter: 'in',     default: undefined, type: 'string' },
+    { parameter: 'min',    default: undefined, type: 'string' },
+    { parameter: 'max',    default: undefined, type: 'string' },
+    { parameter: 'format', default: undefined, type: 'string' },
+  ],
+
+  process: (value, _target, _location, options) => {
+    if (!IPV4_REGEX.test(value)) {
+      throw new ConstraintError('Invalid IPv4 address');
+    }
+
+    const { in: inRange, min, max, format } = options?.args ?? {};
+
+    // mutual exclusivity check
+    if (inRange !== undefined && (min !== undefined || max !== undefined)) {
+      throw new ResolverError('$ipv4: "in" and "min"/"max" are mutually exclusive');
+    }
+
+    // validate min/max are valid IPv4 if provided
+    if (min !== undefined && !IPV4_REGEX.test(min)) {
+      throw new ResolverError(`$ipv4: invalid "min" address: ${min}`);
+    }
+    if (max !== undefined && !IPV4_REGEX.test(max)) {
+      throw new ResolverError(`$ipv4: invalid "max" address: ${max}`);
+    }
+
+    const ip = ipToUint32(value);
+
+    if (inRange !== undefined) {
+      const ranges = resolveRange(inRange);
+      if (!ranges.some(cidr => isInCIDR(ip, cidr))) {
+        throw new ConstraintError(`IPv4 address not in range "${inRange}"`);
+      }
+    }
+
+    if (min !== undefined && ip < ipToUint32(min)) {
+      throw new ConstraintError(`IPv4 address below minimum ${min}`);
+    }
+    if (max !== undefined && ip > ipToUint32(max)) {
+      throw new ConstraintError(`IPv4 address above maximum ${max}`);
+    }
+
+    if (format === 'integer') {
+      return ip;
+    }
+
+    return value;
+  },
+
+  describe: (args) => {
+    if (!args) return undefined;
+
+    const inProcessor = (Array.isArray(args) ? args[0] : args.in);
+    const minProcessor = (Array.isArray(args) ? args[1] : args.min);
+    const maxProcessor = (Array.isArray(args) ? args[2] : args.max);
+
+    const inVal = inProcessor?.description;
+    const min = minProcessor?.description;
+    const max = maxProcessor?.description;
+
+    if (inVal !== undefined) return `in ${inVal}`;
+    if (min !== undefined && max !== undefined) return `${min}–${max}`;
+    if (min !== undefined) return `≥${min}`;
+    if (max !== undefined) return `≤${max}`;
+    return undefined;
+  }
+};

package/src/core-library/processors/ipv6-constraint.js

@@ -0,0 +1,205 @@
+import { ConstraintError, ResolverError } from '../../errors.js';
+
+const IPV6_REGEX = /^(([0-9a-fA-F]{1,4}:){7,7}[0-9a-fA-F]{1,4}|([0-9a-fA-F]{1,4}:){1,7}:|([0-9a-fA-F]{1,4}:){1,6}:[0-9a-fA-F]{1,4}|([0-9a-fA-F]{1,4}:){1,5}(:[0-9a-fA-F]{1,4}){1,2}|([0-9a-fA-F]{1,4}:){1,4}(:[0-9a-fA-F]{1,4}){1,3}|([0-9a-fA-F]{1,4}:){1,3}(:[0-9a-fA-F]{1,4}){1,4}|([0-9a-fA-F]{1,4}:){1,2}(:[0-9a-fA-F]{1,4}){1,5}|[0-9a-fA-F]{1,4}:((:[0-9a-fA-F]{1,4}){1,6})|:((:[0-9a-fA-F]{1,4}){1,7}|:)|fe80:(:[0-9a-fA-F]{0,4}){0,4}%[0-9a-zA-Z]{1,}|::(ffff(:0{1,4}){0,1}:){0,1}((25[0-5]|(2[0-4]|1{0,1}[0-9]){0,1}[0-9])\.){3,3}(25[0-5]|(2[0-4]|1{0,1}[0-9]){0,1}[0-9])|([0-9a-fA-F]{1,4}:){1,4}:((25[0-5]|(2[0-4]|1{0,1}[0-9]){0,1}[0-9])\.){3,3}(25[0-5]|(2[0-4]|1{0,1}[0-9]){0,1}[0-9]))$/;
+
+const IPV4_TAIL_REGEX = /(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/;
+
+/**
+ * Expand an IPv6 string (possibly compressed, possibly with zone id or IPv4 tail)
+ * into exactly 8 16-bit groups as a BigInt.
+ * @param {string} ip
+ * @returns {bigint}
+ */
+function ipv6ToBigInt(ip) {
+  // strip zone identifier (e.g. %eth0)
+  let addr = ip.replace(/%.*$/, '');
+
+  // handle IPv4-mapped tail: convert dotted-decimal to two hex groups
+  const v4Match = IPV4_TAIL_REGEX.exec(addr);
+  if (v4Match) {
+    const [a, b, c, d] = [v4Match[1], v4Match[2], v4Match[3], v4Match[4]].map(Number);
+    const hi = ((a << 8) | b).toString(16);
+    const lo = ((c << 8) | d).toString(16);
+    addr = addr.slice(0, v4Match.index) + `${hi}:${lo}`;
+  }
+
+  // expand :: shorthand
+  if (addr.includes('::')) {
+    const [left, right] = addr.split('::');
+    const leftGroups = left ? left.split(':') : [];
+    const rightGroups = right ? right.split(':') : [];
+    const missing = 8 - leftGroups.length - rightGroups.length;
+    const fill = Array(missing).fill('0');
+    addr = [...leftGroups, ...fill, ...rightGroups].join(':');
+  }
+
+  const groups = addr.split(':');
+  let result = 0n;
+  for (const group of groups) {
+    result = (result << 16n) | BigInt(parseInt(group, 16));
+  }
+  return result;
+}
+
+/**
+ * Parse an IPv6 CIDR string into network and mask as BigInt.
+ * @param {string} cidr
+ * @returns {{ network: bigint, mask: bigint }}
+ */
+function parseCIDR(cidr) {
+  const slashIdx = cidr.lastIndexOf('/');
+  if (slashIdx === -1) {
+    throw new ResolverError(`Invalid IPv6 CIDR notation: ${cidr}`);
+  }
+  const ip = cidr.slice(0, slashIdx);
+  const bits = Number(cidr.slice(slashIdx + 1));
+  if (!IPV6_REGEX.test(ip) || !Number.isInteger(bits) || bits < 0 || bits > 128) {
+    throw new ResolverError(`Invalid IPv6 CIDR notation: ${cidr}`);
+  }
+  const mask = bits === 0 ? 0n : ((1n << 128n) - 1n) << BigInt(128 - bits);
+  const network = ipv6ToBigInt(ip) & mask;
+  return { network, mask };
+}
+
+/**
+ * Check whether an IPv6 BigInt falls within a CIDR range.
+ * @param {bigint} ip
+ * @param {{ network: bigint, mask: bigint }} cidr
+ * @returns {boolean}
+ */
+function isInCIDR(ip, cidr) {
+  return (ip & cidr.mask) === cidr.network;
+}
+
+/** @type {Record<string, { network: bigint, mask: bigint }[]>} */
+const NAMED_RANGES = {
+  loopback: [
+    parseCIDR('::1/128'),
+  ],
+  'link-local': [
+    parseCIDR('fe80::/10'),
+  ],
+  'unique-local': [
+    parseCIDR('fc00::/7'),
+  ],
+  multicast: [
+    parseCIDR('ff00::/8'),
+  ],
+};
+
+NAMED_RANGES['non-routable'] = [
+  ...NAMED_RANGES.loopback,
+  ...NAMED_RANGES['link-local'],
+  ...NAMED_RANGES['unique-local'],
+];
+
+/**
+ * Resolve an `in` parameter value to an array of CIDR ranges.
+ * Accepts a named range or a CIDR string.
+ * @param {string} spec
+ * @returns {{ network: bigint, mask: bigint }[]}
+ */
+function resolveRange(spec) {
+  const named = NAMED_RANGES[spec.toLowerCase()];
+  if (named) return named;
+  if (spec.includes('/')) return [parseCIDR(spec)];
+  throw new ResolverError(`Unknown IPv6 range: "${spec}" (expected CIDR or one of: ${Object.keys(NAMED_RANGES).join(', ')})`);
+}
+
+/**
+ * ## $ipv6
+ *
+ * Validates that a string is a properly formatted IPv6 address. Supports all standard
+ * notation formats including full, compressed (::), link-local with zone identifiers,
+ * and IPv4-mapped addresses.
+ *
+ * ### Parameters
+ * - `in` (string, optional): Network range to validate against. Accepts CIDR
+ *   notation (e.g. `'fe80::/10'`) or a named range: `loopback`, `link-local`,
+ *   `unique-local`, `multicast`, `non-routable`.
+ * - `min` (string, optional): Minimum IPv6 address (inclusive).
+ * - `max` (string, optional): Maximum IPv6 address (inclusive).
+ *
+ * Use either `in` OR `min`/`max`, not both.
+ *
+ * ### Example
+ * ```js
+ * // Format-only validation
+ * new Schema('string').validator('$ipv6')
+ *
+ * // CIDR range (positional `in`)
+ * new Schema('string').validator({$ipv6: '2001:db8::/32'})
+ *
+ * // Named range
+ * new Schema('string').validator({$ipv6: 'unique-local'})
+ *
+ * // Explicit min/max
+ * new Schema('string').validator({$ipv6: {min: '2001:db8::1', max: '2001:db8::ffff'}})
+ * ```
+ *
+ * @type {import("../../value-processor/value-processor.js").ValueProcessorDefinition}
+ */
+export const IPV6_CONSTRAINT = {
+  keyword: 'ipv6',
+
+  parameters: [
+    { parameter: 'in',  default: undefined, type: 'string' },
+    { parameter: 'min', default: undefined, type: 'string' },
+    { parameter: 'max', default: undefined, type: 'string' },
+  ],
+
+  process: (value, _target, _location, options) => {
+    if (!IPV6_REGEX.test(value)) {
+      throw new ConstraintError('Invalid IPv6 address');
+    }
+
+    const { in: inRange, min, max } = options?.args ?? {};
+
+    if (inRange !== undefined && (min !== undefined || max !== undefined)) {
+      throw new ResolverError('$ipv6: "in" and "min"/"max" are mutually exclusive');
+    }
+
+    if (min !== undefined && !IPV6_REGEX.test(min)) {
+      throw new ResolverError(`$ipv6: invalid "min" address: ${min}`);
+    }
+    if (max !== undefined && !IPV6_REGEX.test(max)) {
+      throw new ResolverError(`$ipv6: invalid "max" address: ${max}`);
+    }
+
+    const ip = ipv6ToBigInt(value);
+
+    if (inRange !== undefined) {
+      const ranges = resolveRange(inRange);
+      if (!ranges.some(cidr => isInCIDR(ip, cidr))) {
+        throw new ConstraintError(`IPv6 address not in range "${inRange}"`);
+      }
+    }
+
+    if (min !== undefined && ip < ipv6ToBigInt(min)) {
+      throw new ConstraintError(`IPv6 address below minimum ${min}`);
+    }
+    if (max !== undefined && ip > ipv6ToBigInt(max)) {
+      throw new ConstraintError(`IPv6 address above maximum ${max}`);
+    }
+
+    return value;
+  },
+
+  describe: (args) => {
+    if (!args) return undefined;
+
+    const inProcessor = (Array.isArray(args) ? args[0] : args.in);
+    const minProcessor = (Array.isArray(args) ? args[1] : args.min);
+    const maxProcessor = (Array.isArray(args) ? args[2] : args.max);
+
+    const inVal = inProcessor?.description;
+    const min = minProcessor?.description;
+    const max = maxProcessor?.description;
+
+    if (inVal !== undefined) return `in ${inVal}`;
+    if (min !== undefined && max !== undefined) return `${min}–${max}`;
+    if (min !== undefined) return `≥${min}`;
+    if (max !== undefined) return `≤${max}`;
+    return undefined;
+  }
+};

package/src/core-library/processors/is-array-constraint.js

@@ -0,0 +1,21 @@
+import { ConstraintError } from '../../errors.js';
+
+/**
+ * ## $is-array
+ *
+ * Validates that the input is a valid array.
+ *
+ * See `$array` for looser array handling that accepts values that can be normalized as arrays.
+ *
+ * @type {import("../../value-processor/value-processor.js").ValueProcessorDefinition}
+ */
+export const IS_ARRAY_CONSTRAINT = {
+  keyword: 'is-array',
+  process: (value, _, location) => {
+    if (!Array.isArray(value)) {
+      throw new ConstraintError('Must be an array');
+    }
+    return value;
+  },
+  description: ''
+};

package/src/core-library/processors/is-date-constraint.js

@@ -0,0 +1,22 @@
+import { ConstraintError } from '../../errors.js';
+import { formatValue } from '../../helpers/format.js';
+
+/**
+ * ## $is-date
+ *
+ * Validates that the input is a valid date.
+ *
+ * See `$date` for looser date handling that accepts values that can be normalized as dates.
+ *
+ * @type {import("../../value-processor/value-processor.js").ValueProcessorDefinition}
+ */
+export const IS_DATE_CONSTRAINT = {
+  keyword: 'is-date',
+  process: (value) => {
+    if (value instanceof Date && !isNaN(value.getTime())) {
+      return value;
+    }
+    throw new ConstraintError(`Invalid date: ${formatValue(value)}`)
+  },
+  description: ''
+};

package/src/core-library/processors/is-number-constraint.js

@@ -0,0 +1,21 @@
+import { ConstraintError } from '../../errors.js';
+
+/**
+ * ## $is-number
+ *
+ * Validates that the input is a valid number.
+ *
+ * See `$number` for looser number validation that accepts values that can be normalized as numbers.
+ *
+ * @type {import("../../value-processor/value-processor.js").ValueProcessorDefinition}
+ */
+export const IS_NUMBER_CONSTRAINT = {
+  keyword: 'is-number',
+  process: (value) => {
+    if (typeof value !== 'number' || Number.isNaN(value) || !Number.isFinite(value)) {
+      throw new ConstraintError('Must be a number');
+    }
+    return value;
+  },
+  description: ''
+};

package/src/core-library/processors/is-object-constraint.js

@@ -0,0 +1,21 @@
+import { ConstraintError } from '../../errors.js';
+
+/**
+ * ## $is-object
+ *
+ * Validates that the input is a valid object (and not null!)
+ *
+ * See `$object` for looser object handling that accepts values that can be normalized as objects.
+ *
+ * @type {import("../../value-processor/value-processor.js").ValueProcessorDefinition}
+ */
+export const IS_OBJECT_CONSTRAINT = {
+  keyword: 'is-object',
+  process: (value, _, location) => {
+    if (typeof value === 'object' && value !== null) {
+      return value;
+    }
+    throw new ConstraintError('Must be an object');
+  },
+  description: ''
+};

package/src/core-library/processors/is-string-constraint.js

@@ -0,0 +1,21 @@
+import { ConstraintError } from '../../errors.js';
+
+/**
+ * ## $is-string
+ *
+ * Validates that the input is a valid string.
+ *
+ * See `$string` for looser validation that accepts values that can be normalized as strings.
+ *
+ * @type {import("../../value-processor/value-processor.js").ValueProcessorDefinition}
+ */
+export const IS_STRING_CONSTRAINT = {
+  keyword: 'is-string',
+  process: (value) => {
+    if (typeof value === 'string') {
+      return value;
+    }
+    throw new ConstraintError('Must be a string');
+  },
+  description: ''
+};

package/src/core-library/processors/join-operator.js

@@ -0,0 +1,41 @@
+/**
+ * ## $join
+ *
+ * Join the input array elements into a string using the provided separator.
+ *
+ * ### Parameters
+ * - `separator` (string, required): The value to use for joining
+ *
+ * If the input is not an array, it is treated as a single element.
+ * Follows the behavior of JavaScript's Array.prototype.join()
+ *
+ * ### Example
+ * ```js
+ * // Join array elements with a comma (default)
+ * new Schema('array').transformer('$join')
+ * // ['a', 'b', 'c'] → 'a,b,c'
+ *
+ * // Join with a custom separator
+ * new Schema('array').transformer({$join: {separator: ' | '}})
+ * // ['admin', 'read', 'write'] → 'admin | read | write'
+ *
+ * // Split then rejoin with normalized separators
+ * new Schema('string').normalizer([{$split: {separator: /[,;]/}}, {$each: '$trim'}])
+ *   .transformer({$join: {separator: ', '}})
+ * ```
+ *
+ * @type {import("../../value-processor/value-processor.js").ValueProcessorDefinition}*
+ */
+export const JOIN_OPERATOR = {
+  keyword: 'join',
+  parameters: [ { parameter: 'separator', default: ',' } ],
+
+  process: (value, _target, _location, options) => {
+    const separator = options.args?.['separator'];
+
+    if (!Array.isArray(value)) {
+      return `${value}`;
+    }
+    return value.join(separator);
+  }
+}

package/src/core-library/processors/json-constraint.js

@@ -0,0 +1,22 @@
+import { ConstraintError } from '../../errors.js';
+
+/**
+ * ## $json
+ *
+ * Validates that a string contains valid JSON that can be parsed by `JSON.parse()`.
+ * The processor does not modify the input - it only validates that the string is
+ * syntactically correct JSON.
+ *
+ * @type {import("../../value-processor/value-processor.js").ValueProcessorDefinition}
+ */
+export const JSON_CONSTRAINT = {
+  keyword: 'json',
+  process: (value) => {
+    try {
+      JSON.parse(value);
+      return value;
+    } catch {
+      throw new ConstraintError('Invalid JSON format');
+    }
+  }
+};

package/src/core-library/processors/json-decode-operator.js

@@ -0,0 +1,25 @@
+import { ConstraintError } from '../../errors.js';
+import { formatValue } from '../../helpers/format.js';
+
+/**
+ * ## $json-decode
+ *
+ * Parses a JSON string into a value.
+ * Throws if the input is not a string or is not valid JSON.
+ *
+ * @type {import('../../value-processor/value-processor.js').ValueProcessorDefinition}
+ */
+export const JSON_DECODE_OPERATOR = {
+  keyword: 'json-decode',
+  process: (value, _target, location) => {
+    if (typeof value !== 'string') {
+      throw new ConstraintError(`$json-decode requires a string, got ${formatValue(value)}`, {location});
+    }
+    try {
+      return JSON.parse(value);
+    }
+    catch (error) {
+      throw new ConstraintError(`$json-decode: invalid JSON — ${error.message}`, {location, cause: error});
+    }
+  }
+};

package/src/core-library/processors/json-encode-operator.js

@@ -0,0 +1,35 @@
+/**
+ * ## $json-encode
+ *
+ * Serializes any value to a JSON string.
+ *
+ * ### Parameters
+ * - `indent` (number, optional, default `0`): Indentation spaces for pretty-printing. `0` produces compact output.
+ *
+ * ### Example
+ * ```js
+ * // Serialize an object to a compact JSON string
+ * new Schema('object').transformer('$json-encode')
+ * // {a: 1} → '{"a":1}'
+ *
+ * // Pretty-print with 2-space indentation
+ * new Schema('object').transformer({'$json-encode': {indent: 2}})
+ * // {a: 1} → '{\n  "a": 1\n}'
+ *
+ * // Encode a nested payload field for storage
+ * new Schema('object', {
+ *   payload: new Schema('object').transformer('$json-encode'),
+ * })
+ * ```
+ *
+ * @type {import('../../value-processor/value-processor.js').ValueProcessorDefinition}
+ */
+export const JSON_ENCODE_OPERATOR = {
+  keyword: 'json-encode',
+  parameters: [ { parameter: 'indent', default: 0 } ],
+
+  process: (value, _target, _location, options) => {
+    const indent = options.args?.['indent'] || 0;
+    return JSON.stringify(value, null, indent || undefined);
+  }
+};

package/src/core-library/processors/kebab-case-operator.js

@@ -0,0 +1,23 @@
+import { toKebabCase } from '../../helpers/case.js';
+
+/**
+ * ## $kebab-case
+ *
+ * Converts a string to kebab-case format (lowercase words separated by hyphens).
+ * Safe to use in normalize phase (non-throwing).
+ *
+ * **Input/Output Examples**:
+ * - `"HelloWorld"` → `"hello-world"`
+ * - `"API_KEY_NAME"` → `"api-key-name"`
+ * - `"some text here"` → `"some-text-here"`
+ * - `"camelCase"` → `"camel-case"`
+ * - `"already-kebab"` → `"already-kebab"`
+ *
+ * @type {import("../../value-processor/value-processor.js").ValueProcessorDefinition}
+ */
+export const KEBAB_CASE_OPERATOR = {
+  keyword: 'kebab-case',
+  process: (value) => {
+    return toKebabCase(String(value));
+  }
+};

package/src/core-library/processors/keys-operator.js

@@ -0,0 +1,20 @@
+import { ConstraintError } from '../../errors.js';
+import { formatValue } from '../../helpers/format.js';
+
+/**
+ * ## $keys
+ *
+ * Returns the enumerable own property keys of an object as an array of strings.
+ * Throws if the input is not a plain object.
+ *
+ * @type {import('../../value-processor/value-processor.js').ValueProcessorDefinition}
+ */
+export const KEYS_OPERATOR = {
+  keyword: 'keys',
+  process: (value, _target, location) => {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+      throw new ConstraintError(`$keys requires a plain object, got ${formatValue(value)}`, {location});
+    }
+    return Object.keys(value);
+  }
+};