@xeplr/schema-handler 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Xeplr
+
+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/index.js

@@ -0,0 +1,33 @@
+var types = require('./lib/types');
+var errors = require('./lib/errors');
+var validate = require('./lib/validate');
+var inference = require('./lib/inference');
+var mapping = require('./lib/mapping');
+var templating = require('./lib/templating');
+
+module.exports = {
+  // Types
+  TYPES: types.TYPES,
+  CHECKERS: types.CHECKERS,
+  check: types.check,
+
+  // Errors
+  ValidationError: errors.ValidationError,
+
+  // Validation
+  applySchema: validate.applySchema,
+
+  // Inference (learn / dynamic schema updates)
+  inferType: inference.inferType,
+  schemaFromObject: inference.schemaFromObject,
+  mergeSchemas: inference.mergeSchemas,
+  schemasEqual: inference.schemasEqual,
+
+  // Mapping (dotted paths + resolve)
+  getPath: mapping.getPath,
+  resolveMapping: mapping.resolveMapping,
+
+  // Templating ({name} interpolation)
+  interpolate: templating.interpolate,
+  interpolateAll: templating.interpolateAll
+};

package/lib/errors.js

@@ -0,0 +1,11 @@
+// Structured validation failure. `details` is an array of per-field messages
+// so the caller can render field-level UI errors, not just one blob.
+class ValidationError extends Error {
+  constructor(message, details) {
+    super(message);
+    this.name = 'ValidationError';
+    this.details = details || [];
+  }
+}
+
+module.exports = { ValidationError: ValidationError };

package/lib/inference.js

@@ -0,0 +1,41 @@
+// Derive a schema (or schema fragment) from an actual value at runtime.
+// Powers "learn missing fields" and "dynamic" modes for output schemas.
+
+function inferType(v) {
+  if (v === null || v === undefined) return 'null';
+  if (Array.isArray(v)) return 'array';
+  if (v instanceof Date) return 'date';
+  return typeof v;
+}
+
+// Given an object, return { key: {type} } for each own key.
+function schemaFromObject(obj) {
+  var out = {};
+  if (!obj || typeof obj !== 'object') return out;
+  var keys = Object.keys(obj);
+  for (var i = 0; i < keys.length; i++) out[keys[i]] = { type: inferType(obj[keys[i]]) };
+  return out;
+}
+
+// Merge fresh into current keeping every key already in current (learn mode).
+function mergeSchemas(current, fresh) {
+  current = current || {};
+  fresh = fresh || {};
+  var next = Object.assign({}, current);
+  var keys = Object.keys(fresh);
+  for (var i = 0; i < keys.length; i++) {
+    if (!next[keys[i]]) next[keys[i]] = fresh[keys[i]];
+  }
+  return next;
+}
+
+function schemasEqual(a, b) {
+  return JSON.stringify(a || {}) === JSON.stringify(b || {});
+}
+
+module.exports = {
+  inferType: inferType,
+  schemaFromObject: schemaFromObject,
+  mergeSchemas: mergeSchemas,
+  schemasEqual: schemasEqual
+};

package/lib/mapping.js

@@ -0,0 +1,23 @@
+// Resolve a mapping — { targetName: 'source.dotted.path' } — against a source
+// object. Returns { targetName: value }. Missing paths yield `undefined`.
+
+function getPath(obj, path) {
+  if (obj == null || !path) return undefined;
+  var parts = String(path).split('.');
+  var cur = obj;
+  for (var i = 0; i < parts.length; i++) {
+    if (cur == null) return undefined;
+    cur = cur[parts[i]];
+  }
+  return cur;
+}
+
+function resolveMapping(mapping, source) {
+  var out = {};
+  if (!mapping) return out;
+  var keys = Object.keys(mapping);
+  for (var i = 0; i < keys.length; i++) out[keys[i]] = getPath(source, mapping[keys[i]]);
+  return out;
+}
+
+module.exports = { resolveMapping: resolveMapping, getPath: getPath };

package/lib/templating.js

@@ -0,0 +1,38 @@
+// Simple placeholder interpolation. `{name}` and `{a.b.c}` are resolved
+// against `context` via dotted paths. Unknown paths render as empty string.
+// Use `{{` and `}}` for literal braces.
+
+var { getPath } = require('./mapping');
+
+var OPEN_SENTINEL = '
';
+var CLOSE_SENTINEL = '';
+
+function interpolate(template, context) {
+  if (template == null) return '';
+  var str = String(template)
+    .split('{{').join(OPEN_SENTINEL)
+    .split('}}').join(CLOSE_SENTINEL);
+  str = str.replace(/\{([^{}]+)\}/g, function(_, path) {
+    var v = getPath(context, path.trim());
+    if (v === undefined || v === null) return '';
+    return typeof v === 'object' ? JSON.stringify(v) : String(v);
+  });
+  return str.split(OPEN_SENTINEL).join('{').split(CLOSE_SENTINEL).join('}');
+}
+
+// Recursively interpolate all string values in a structure. Objects and
+// arrays are walked; primitives other than strings are returned as-is.
+function interpolateAll(value, context) {
+  if (value == null) return value;
+  if (typeof value === 'string') return interpolate(value, context);
+  if (Array.isArray(value)) return value.map(function(v) { return interpolateAll(v, context); });
+  if (typeof value === 'object') {
+    var out = {};
+    var keys = Object.keys(value);
+    for (var i = 0; i < keys.length; i++) out[keys[i]] = interpolateAll(value[keys[i]], context);
+    return out;
+  }
+  return value;
+}
+
+module.exports = { interpolate: interpolate, interpolateAll: interpolateAll };

package/lib/types.js

@@ -0,0 +1,20 @@
+// The one canonical set of supported types + runtime type predicates.
+// Used by validate.js (input checking) and inference.js (typeof-based inference).
+
+var TYPES = ['string', 'number', 'boolean', 'date', 'object', 'array'];
+
+var CHECKERS = {
+  string:  function(v) { return typeof v === 'string'; },
+  number:  function(v) { return typeof v === 'number' && !isNaN(v); },
+  boolean: function(v) { return typeof v === 'boolean'; },
+  date:    function(v) { return v instanceof Date || (typeof v === 'string' && !isNaN(Date.parse(v))); },
+  object:  function(v) { return v !== null && typeof v === 'object' && !Array.isArray(v) && !(v instanceof Date); },
+  array:   function(v) { return Array.isArray(v); }
+};
+
+function check(type, value) {
+  var fn = CHECKERS[type];
+  return fn ? fn(value) : true; // unknown type → don't reject
+}
+
+module.exports = { TYPES: TYPES, CHECKERS: CHECKERS, check: check };

package/lib/validate.js

@@ -0,0 +1,44 @@
+var { check } = require('./types');
+var { ValidationError } = require('./errors');
+
+/**
+ * Apply a schema (array of field definitions) to a values object.
+ * Returns a copy of `values` with defaults filled in.
+ * Throws ValidationError listing every problem.
+ *
+ * Field:  { name, type, required, default, description, order }
+ * Values: { [name]: value }
+ * Label:  free-form string used in error messages, e.g. 'config' | 'input' | 'params'
+ */
+function applySchema(schema, values, label) {
+  values = values || {};
+  label = label || 'field';
+  var out = {};
+  var errors = [];
+
+  if (!Array.isArray(schema)) return Object.assign({}, values);
+
+  for (var i = 0; i < schema.length; i++) {
+    var field = schema[i];
+    if (!field || !field.name) continue;
+
+    var val = values[field.name];
+    var missing = val === undefined || val === null;
+
+    if (missing && field.default !== undefined) { out[field.name] = field.default; continue; }
+    if (missing) {
+      if (field.required) errors.push('Missing required ' + label + ' field: ' + field.name);
+      continue;
+    }
+    if (field.type && !check(field.type, val)) {
+      errors.push(label + ' field "' + field.name + '" expected type ' + field.type + ', got ' + typeof val);
+      continue;
+    }
+    out[field.name] = val;
+  }
+
+  if (errors.length) throw new ValidationError(errors.join('; '), errors);
+  return out;
+}
+
+module.exports = { applySchema: applySchema };

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@xeplr/schema-handler",
+  "version": "1.0.1",
+  "description": "Field-schema primitive: define, validate, infer, map, and template values across schemas",
+  "main": "index.js",
+  "files": [
+    "index.js",
+    "lib/"
+  ],
+  "keywords": [
+    "schema",
+    "validation",
+    "mapping",
+    "templating",
+    "form"
+  ],
+  "author": "xeplr",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Xeplr/xeplr-schema-handler"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {}
+}