@versionzero/schema 1.0.0

package/src/helpers/deep.js

@@ -0,0 +1,280 @@
+
+import { isObject, isPlainObject } from './object.js';
+
+/**
+ * @param {object} target
+ * @param {...object} sources
+ * @returns {object}
+ */
+export function deepMerge(target, ...sources) {
+  if (!sources.length) {
+    return target;
+  }
+
+  const source = sources.shift();
+
+  if (isObject(target) && isObject(source)) {
+    for (const key in source) {
+      if (isPlainObject(source[key])) {
+        if (!target[key]) {
+          Object.assign(target, {[key]: {}});
+        }
+        deepMerge(target[key], source[key]);
+      }
+      else {
+        Object.assign(target, {[key]: source[key]});
+      }
+    }
+  }
+
+  return deepMerge(target, ...sources);
+}
+
+/**
+ * deep comparison
+ * @param {any} a
+ * @param {any} b
+ * @returns {boolean}
+ * @internal
+ */
+export function deepEquals(a, b) {
+  if (a === b) {
+    return true;
+  }
+  if (a == null || b == null) {
+    return false;
+  }
+  if (typeof a !== typeof b) {
+    return false;
+  }
+
+  if (Array.isArray(a) && Array.isArray(b)) {
+    if (a.length !== b.length) {
+      return false;
+    }
+    for (let i = 0; i < a.length; ++i) {
+      if (!deepEquals(a[i], b[i])) {
+        return false;
+      }
+    }
+    return true;
+  }
+
+  if (typeof a === 'object' && typeof b === 'object') {
+    if (Array.isArray(a) || Array.isArray(b)) {
+      return false;
+    }
+    const keys = Object.keys(a);
+    if (keys.length !== Object.keys(b).length) {
+      return false;
+    }
+    for (const k of keys) {
+      if (!b.hasOwnProperty(k) || !deepEquals(a[k], b[k])) {
+        return false;
+      }
+    }
+    return true;
+  }
+
+  return false;
+}
+
+/**
+ * @param {object|undefined}target
+ * @param {string} path
+ * @param {any} value
+ * @returns {object}
+ */
+export function deepAssign(target, path, value) {
+  if (path === '' && target) {
+    throw new Error('Top level path but target is already set');
+  }
+  if (path === '') {
+    if (Array.isArray(value)) {
+      return [...value];
+    }
+    else if (isPlainObject(value)) {
+      return {...value};
+    }
+    return value;
+  }
+  // Handle edge cases
+  if (!path || typeof path !== 'string') {
+    throw new Error('Path must be a non-empty string');
+  }
+
+  // Split the path by dots and filter out empty segments
+  const segments = path.split('.').filter(segment => segment !== '');
+
+  if (segments.length === 0) {
+    throw new Error('Path must contain at least one valid segment');
+  }
+
+  if (target !== null && target !== undefined && typeof target !== 'object') {
+    throw new Error('Target must be an object, an array, or null/undefined');
+  }
+
+  // Auto-synthesize target if null
+  if (target === null || target === undefined) {
+    const firstSegment = segments[0];
+    const isFirstArrayIndex = /^\d+$/.test(firstSegment);
+    target = isFirstArrayIndex ? [] : {};
+  }
+
+  let current = target;
+
+  // Navigate to the parent of the target property
+  for (let i = 0; i < segments.length - 1; i++) {
+    const segment = segments[i];
+    const nextSegment = segments[i + 1];
+
+    // Check if current segment is an array index
+    const isArrayIndex = /^\d+$/.test(segment);
+    const nextIsArrayIndex = /^\d+$/.test(nextSegment);
+
+    if (isArrayIndex) {
+      const index = parseInt(segment, 10);
+
+      // Ensure current is an array
+      if (!Array.isArray(current)) {
+        throw new Error(
+          `Expected array at path segment '${segments.slice(0, i).join('.')}', but found ${typeof current}`);
+      }
+
+      // Extend array if necessary
+      while (current.length <= index) {
+        current.push(undefined);
+      }
+
+      // Create the next level if it doesn't exist
+      if (current[index] === undefined || current[index] === null) {
+        current[index] = nextIsArrayIndex ? [] : {};
+      }
+
+      current = current[index];
+    }
+    else {
+      // Handle object property
+      if (current[segment] === undefined || current[segment] === null) {
+        current[segment] = nextIsArrayIndex ? [] : {};
+      }
+
+      current = current[segment];
+    }
+  }
+
+  // Set the final value
+  const finalSegment = segments[segments.length - 1];
+  const isFinalArrayIndex = /^\d+$/.test(finalSegment);
+
+  if (isFinalArrayIndex) {
+    const index = parseInt(finalSegment, 10);
+
+    // Ensure current is an array
+    if (!Array.isArray(current)) {
+      throw new Error(
+        `Expected array at path segment '${segments.slice(0, -1).join('.')}', but found ${typeof current}`);
+    }
+
+    // Extend array if necessary
+    while (current.length <= index) {
+      current.push(undefined);
+    }
+
+    current[index] = value;
+  }
+  else {
+    current[finalSegment] = value;
+  }
+
+  return target;
+}
+
+/**
+ *
+ * @param {object} object
+ * @param {string} path
+ * @returns {undefined|any}
+ */
+export function deepValue(object, path) {
+  if (path === '') {
+    return object;
+  }
+
+  // Handle null/undefined object
+  if (!object || typeof object !== 'object') {
+    return undefined;
+  }
+
+
+  // Handle empty or invalid path
+  if (typeof path !== 'string') {
+    return undefined;
+  }
+
+  // Split the path and filter out empty strings
+  const keys = path.split('.').filter(key => key.length > 0);
+
+  // If no valid keys, return undefined
+  if (keys.length === 0) {
+    return undefined;
+  }
+
+  // Traverse the object following the path
+  let current = object;
+  for (const key of keys) {
+    // Check if current is null/undefined or not an object
+    if (!current || typeof current !== 'object') {
+      return undefined;
+    }
+
+    // Move to the next level
+    if (/^\d+$/.test(key)) {
+      current = current[Number(key)]
+    }
+    else {
+      current = current[key];
+    }
+  }
+
+  return current;
+}
+
+/**
+ * @param {any} value
+ * @returns {any}
+ */
+export function deepPrune(value) {
+  if (value === null || value === undefined) {
+    return undefined;
+  }
+  if (isPlainObject(value)) {
+    for (const key of Object.keys(value)) {
+      if (deepPrune(value[key]) === undefined) {
+        delete value[key];
+      }
+    }
+    return Object.keys(value).length ? value : undefined;
+  }
+  else if (Array.isArray(value)) {
+    for (let i = value.length - 1; i >= 0; i--) {
+      const v = deepPrune(value[i]);
+      if (v === undefined) {
+        if (i === value.length - 1) {
+          value.pop();
+        }
+        else {
+          delete value[i];
+        }
+      }
+      else if (v !== value[i]) {
+        // avoid reassigning unless actually changed (e.g. proxy)
+        value[i] = v;
+      }
+    }
+    return value.length ? value : undefined;
+  }
+  else {
+    return value;
+  }
+}

package/src/helpers/format.js

@@ -0,0 +1,121 @@
+import { CompiledSchema } from "../compiled-schema.js";
+import { stringify } from './stringify.js';
+import { isPlainObject } from './object.js';
+
+/**
+ *
+ * @param {CompiledSchema} schema
+ * @returns {string}
+ * @package
+ */
+export function formatArgumentType(schema) {
+
+  if (schema.metadata.valueDescription) {
+    return schema.metadata.valueDescription;
+  }
+
+  let argumentTypeString;
+  if (schema.isArray && schema.hasChildren) {
+    const props = Array.from(schema.propertyEntries)
+                        .sort((a, b) => {
+                          if (a[0] === '*') return 1;
+                          if (b[0] === '*') return -1;
+                          return a[0].localeCompare(b[0], undefined, {numeric: true});
+                        })
+                        .map(e => e[1]);
+
+
+    argumentTypeString = props.map(s =>
+    {
+      let propFormat = formatArgumentType(s)
+      if (!s.required && (propFormat.length > 2) && propFormat.charAt(0) === '[' && propFormat.charAt(propFormat.length - 1) === ']') {
+        propFormat = propFormat.slice(1, propFormat.length - 1);
+      }
+      return propFormat;
+    }).join(', ')
+
+    if (schema.hasWildcard) {
+      argumentTypeString += '...';
+    }
+
+    if (schema.metadata.validatorDescription) {
+      if (argumentTypeString && !argumentTypeString.includes(schema.metadata.validatorDescription)) {
+        argumentTypeString += ` {${schema.metadata.validatorDescription}}`;
+      }
+    }
+  }
+  else {
+    if (Array.isArray(schema.options.values) && schema.options.values.length > 0) {
+      argumentTypeString = schema.options.values.map(v => `${typeof v === 'string'? `"${v}"` : stringify(v)}`)
+                                 .sort((a, b) => a.localeCompare(b, undefined, {numeric: true})).join('|');
+    }
+    else {
+      argumentTypeString = schema.metadata.valueName ?? (schema.isArray? '' : schema.options.type);
+
+      if (schema.metadata.validatorDescription) {
+        if (!argumentTypeString || (argumentTypeString === schema.options.type)) {
+          argumentTypeString = schema.metadata.validatorDescription;  // overwrite basic "type names"
+        }
+        else {
+          argumentTypeString = `${argumentTypeString} {${schema.metadata.validatorDescription}}`;
+        }
+      }
+    }
+    if (argumentTypeString === undefined) {
+      argumentTypeString = 'value';
+    }
+    if (schema.isArray && !argumentTypeString.includes('...')) {
+      argumentTypeString += '...';
+    }
+  }
+  return argumentTypeString;
+}
+
+const DELIMITED = /^[^A-Za-z0-9_].+[^A-Za-z0-9_]$/;
+
+/**
+ * @param {any} value
+ * @param {object} [options]
+ * @returns {string}
+ */
+export function formatValue(value, options = {}) {
+  const {delimiterOpen = '«', delimiterClose = '»', maxLength = 40} = options;
+
+  try {
+    if (value === null) {
+      return `${delimiterOpen}null${delimiterClose}`;
+    }
+    else if (value === undefined) {
+      return `${delimiterOpen}undefined${delimiterClose}`;
+    }
+    let valueString;
+    if (typeof value === 'function' && value.name) {
+      valueString = `${delimiterOpen}${value.name}()${delimiterClose}`;
+    }
+    else if (typeof value === 'object' && !isPlainObject(value) && value.constructor?.name) {
+      valueString = `${delimiterOpen}${value.constructor.name}${delimiterClose}`;
+    }
+    else {
+      // get our stringified json  of the value
+      valueString = stringify(value, {delimiterOpen, delimiterClose});
+    }
+    if (typeof value !== 'string'
+        && ((valueString.startsWith('"') && valueString.endsWith('"'))
+            || (valueString.startsWith("'") && valueString.endsWith("'")))) {
+      // if what we got back has quotes but the original wasn't a string, remove them.
+      valueString = valueString.slice(1, -1);
+    }
+    if (!DELIMITED.test(valueString)) {
+      valueString = `${delimiterOpen}${valueString}${delimiterClose}`;
+    }
+    if (valueString.length > 40) {
+      // everything should be delimited here.  grab the final char so we can reattach it.
+      const finalChar = valueString.charAt(valueString.length - 1);
+      valueString = valueString.slice(0, 40) + `...${finalChar}`;
+    }
+    return valueString;
+  }
+  catch (error) {
+    return '�'
+  }
+}

package/src/helpers/has-string-properties.js

@@ -0,0 +1,30 @@
+import { CompiledSchema } from "../compiled-schema.js";
+
+const IMPLIES_ARRAY = /^[\d*]/
+/**
+ * @param {import("../types.js").ISchema} schema
+ * @returns {boolean}
+ */
+export function hasStringProperties(schema) {
+
+  const propertyEntries = (schema instanceof CompiledSchema)? schema.propertyEntries : Object.entries(schema.properties ?? {});
+
+  for (const [k] of propertyEntries) {
+    if (!IMPLIES_ARRAY.test(k)) {
+      return true;
+    }
+  }
+
+  const unionSchemaEntries = (schema instanceof CompiledSchema)? schema.unionSchemaEntries : Object.entries(schema.unionSchemas ?? {});
+
+  for (const [_uk,us] of unionSchemaEntries) {
+    if (hasStringProperties(us)) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+
+

package/src/helpers/index.js

@@ -0,0 +1,16 @@
+// Copyright 2026 Version Zero | github.com/argh
+// SPDX-License-Identifier: Apache-2.0
+
+export { toCamelCase, toPascalCase, toConstantCase, toKebabCase, toCapitalize, toTitleCase } from './case.js';
+export { debug } from './debug-sink.js';
+export { deepMerge, deepEquals, deepAssign, deepValue, deepPrune } from './deep.js';
+export { formatArgumentType, formatValue } from './format.js';
+export { hasStringProperties } from './has-string-properties.js';
+export { isPlainObject, isObject, isEmpty, isPrimitive, isConstructor, isConstructible, isNativeClass, map } from './object.js';
+export { parseDate } from './parse-date.js';
+export { behead, propertyName } from './path.js';
+export { parseRegExp } from './regex.js';
+export { stringify, parse } from './stringify.js';
+export { toData } from './to-data.js';
+export { isTruthyKeyword, isFalseyKeyword, isTruthy, isFalsey } from './truthy.js';
+export { parseDataSize, formatDataSize } from './data-size.js';

package/src/helpers/object.js

@@ -0,0 +1,115 @@
+/**
+ * @param {any} obj
+ * @returns {boolean}
+ */
+export function isPlainObject(obj) {
+  if (obj == null || typeof obj !== 'object') {
+    return false;
+  }
+
+  const proto = Object.getPrototypeOf(obj);
+  return proto === Object.prototype || proto === null;
+}
+
+/**
+ * @param {any} item
+ * @returns {boolean}
+ */
+export function isObject(item) {
+  // todo - should we allow 'function'?
+  return item && typeof item === 'object' && !Array.isArray(item);
+}
+
+/**
+ * @param {any} value
+ * @returns {boolean}
+ */
+export function isEmpty(value) {
+  return value === undefined || value === null
+         || (Array.isArray(value) && value.length === 0)
+         || (isPlainObject(value) && Object.keys(value).length === 0)
+}
+
+/**
+ * @param {any} item
+ * @returns {boolean}
+ */
+export function isPrimitive(item) {
+  if (item === undefined || item === null) {
+    return false; // these values have special meaning for this library and are thus not assignable primitives!
+  }
+  const type = typeof item;
+  return type !== 'object' && type !== 'function';
+}
+
+/**
+ * @param {any} f
+ * @returns {boolean}
+ * @deprecated - usually want isConstructible instead
+ */
+export function isConstructor(f) {
+  if (typeof f !== 'function') {
+    return false;
+  }
+  if (f.prototype?.constructor === f) {
+    return true;
+  }
+  try {
+    class test
+      extends f {}    // oops, turns out that simple functions can be extended (!)
+  }
+  catch (err) {
+    return false;
+  }
+  return true;
+}
+
+/**
+ * @param {any} f
+ * @returns {boolean}
+ */
+export function isConstructible(f) {
+  if (typeof f !== 'function') {
+    return false;
+  }
+
+  try {
+    Reflect.construct(Function, [], f);
+    return true;
+  }
+  catch {
+    return false;
+  }
+}
+
+/**
+ * Returns true for ES class syntax (`class Foo {}`) and native builtin
+ * constructors (`Map`, `Set`, `Error`, etc.) — i.e. functions that are
+ * meant to be used with `new` and should not be invoked as plain callbacks.
+ * @param {any} f
+ * @returns {boolean}
+ */
+export function isNativeClass(f) {
+  if (typeof f !== 'function') return false;
+  const str = Function.prototype.toString.call(f);
+  return /^class\s/.test(str) ||
+         (/\[native code\]/.test(str) && f.prototype?.constructor === f);
+}
+
+/**
+ *
+ * @param {object|any[]|any} collection
+ * @param {(value:any) => any} callback
+ * @returns {object|any[]}
+ */
+export function map(collection, callback) {
+  if (Array.isArray(collection)) {
+    return collection.map(callback);
+  }
+  else if (isPlainObject(collection)) {
+    return Object.fromEntries(Object.entries(collection).map(([k, v]) => [k, callback(v)]))
+  }
+  else {
+    return [callback(collection)];
+  }
+}

package/src/helpers/parse-date.js

@@ -0,0 +1,75 @@
+import { TransformError } from '../errors.js';
+
+/**
+ * @package
+ * @param {string|number|Date} value
+ * @returns {Date}
+ */
+export function parseDate(value) {
+  if (value === 'now') {
+    return new Date();
+  }
+
+  if (typeof value === 'string') {
+    // Handle relative time deltas: +24h, -1d, etc.
+    const deltaMatch = value.match(/^([+-])(\d+(?:\.\d+)?)(ms|s|m|h|d|w)$/);
+    if (deltaMatch) {
+      const [, sign, amount, unit] = deltaMatch;
+      const multiplier = sign === '+' ? 1 : -1;
+      const num = parseFloat(amount) * multiplier;
+
+      const unitMs = {
+        ms: 1,
+        s: 1000,
+        m: 60 * 1000,
+        h: 60 * 60 * 1000,
+        d: 24 * 60 * 60 * 1000,
+        w: 7 * 24 * 60 * 60 * 1000
+      };
+
+      return new Date(Date.now() + (num * unitMs[unit]));
+    }
+
+    // Check if it's a numeric string (timestamp)
+    const numericValue = parseFloat(value);
+    if (!isNaN(numericValue) && isFinite(numericValue) && /^\d+(\.\d+)?$/.test(value.trim())) {
+      // Treat as numeric timestamp, apply same seconds/milliseconds logic
+      let timestamp = numericValue;
+      if (numericValue > 0 && numericValue < 2524608000 && numericValue < 1000000000000) {
+        timestamp = numericValue * 1000;
+      }
+      const date = new Date(timestamp);
+      if (isNaN(date.getTime())) {
+        throw new TransformError(`Invalid date: ${value}`);
+      }
+      return date;
+    }
+
+    // Fall back to standard Date parsing for ISO strings, etc.
+    const date = new Date(value);
+    if (isNaN(date.getTime())) {
+      throw new TransformError(`Invalid date: ${value}`);
+    }
+    return date;
+  }
+
+  if (typeof value === 'number') {
+    // Auto-detect seconds vs. milliseconds for reasonable ranges
+    // (If it's close to the epoch when interpreted as milliseconds, it's probably seconds.)
+    const date = new Date(Math.abs(value) < 200000000 ? value * 1000 : value)
+
+    if (isNaN(date.getTime())) {
+      throw new TransformError(`Invalid date: ${value}`);
+    }
+    return date;
+  }
+
+  if (value instanceof Date) {
+    if (isNaN(value.getTime())) {
+      throw new TransformError(`Invalid date: ${value}`);
+    }
+    return new Date(value.getTime()); // defensive copy
+  }
+
+  throw new TransformError(`Invalid date: ${value} (${typeof value})`);
+}

package/src/helpers/path.js

@@ -0,0 +1,28 @@
+/**
+ * Split off the first section of a path
+ *
+ * @param {string} path
+ * @returns {[string,string|undefined]}
+ */
+export function behead(path) {
+  if (path === '') {
+    return ['', undefined];
+  }
+  const dot = path.indexOf('.');
+
+  return (dot === -1) ? [path, ''] : [path.slice(0, dot), path.slice(dot + 1)];
+}
+
+/**
+ * Extract the last part of the path
+ * @param {string} path
+ * @returns {string}
+ */
+export function propertyName(path) {
+  const dot = path.lastIndexOf('.');
+
+  if (dot === -1) {
+    return path;
+  }
+  return path.slice(dot + 1);
+}

package/src/helpers/regex.js

@@ -0,0 +1,18 @@
+import { SchemaError } from '../errors.js';
+
+/**
+ * Parse delimited regexp strings
+ *
+ * @param {string|RegExp} rx
+ * @returns {RegExp|undefined}
+ */
+export function parseRegExp(rx) {
+  if (rx instanceof RegExp) {
+    return rx;
+  }
+  if (typeof rx === 'string' && rx.startsWith('/') && rx.lastIndexOf('/') > 0) {
+      const lastSlash = rx.lastIndexOf('/');
+      return new RegExp(rx.slice(1, lastSlash), rx.slice(lastSlash + 1));
+  }
+  throw new SchemaError('Unable to parse RegExp', {value: rx})
+}