turbo-schema 0.1.0

package/index.js

@@ -0,0 +1,218 @@
+// index.js:
+
+"use strict";
+
+const UUID =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+class ValidationError extends Error {
+  constructor(errors) {
+    const message = errors.length
+      ? `Schema validation failed: ${errors.join(", ")}`
+      : "Schema validation failed";
+
+    super(message);
+
+    this.name = "ValidationError";
+
+    // backward compatibility
+    this.errors = errors;
+
+    // structured version
+    this.details = errors.map((msg) => {
+      const [field, ...rest] = msg.split(" ");
+      return {
+        field,
+        message: rest.join(" "),
+      };
+    });
+  }
+}
+
+class Schema {
+  constructor(def = {}) {
+    if (!def || typeof def !== "object" || Array.isArray(def)) {
+      throw new TypeError("Schema must be an object");
+    }
+    this.def = def;
+  }
+
+  validate(
+    data = {},
+    { partial = false, coerce = true, stripUnknown = true } = {},
+  ) {
+    const out = {};
+    const errors = [];
+
+    for (const [k, c] of Object.entries(this.def)) {
+      let v = data[k];
+      const exists = Object.hasOwn(data, k);
+
+      if (partial && !exists) continue;
+
+      // default values
+      if (v == null && c.default !== undefined) {
+        v = typeof c.default === "function" ? c.default() : c.default;
+      }
+
+      // required check
+      if (c.required && v == null) {
+        errors.push(`${k} required`);
+        continue;
+      }
+
+      if (v == null) continue;
+
+      // envvar special case (ignore input value)
+      if (c.type === "envvar") {
+        const envName = c.varname;
+
+        if (!envName) {
+          errors.push(`${k} missing varname`);
+          continue;
+        }
+
+        v = process.env[envName];
+
+        if (v == null) {
+          errors.push(`${k} missing env var ${envName}`);
+          continue;
+        }
+      }
+
+      // coercion
+      if (coerce) v = this._coerce(v, c.type, c);
+
+      // type check
+      const typeErr = this._type(k, v, c.type);
+      if (typeErr) {
+        errors.push(typeErr);
+        continue;
+      }
+
+      // enum check
+      if (c.enum && !c.enum.includes(v)) {
+        errors.push(`${k} invalid enum`);
+        continue;
+      }
+
+      // pattern check
+      if (c.pattern) {
+        const ok =
+          c.pattern instanceof RegExp
+            ? c.pattern.test(v)
+            : typeof c.pattern.test === "function" && c.pattern.test(v);
+
+        if (!ok) {
+          errors.push(`${k} pattern mismatch`);
+          continue;
+        }
+      }
+
+      // min / max
+      if (c.min != null && v < c.min) {
+        errors.push(`${k} too small`);
+        continue;
+      }
+
+      if (c.max != null && v > c.max) {
+        errors.push(`${k} too large`);
+        continue;
+      }
+
+      out[k] = v;
+    }
+
+    // unknown fields
+    if (!stripUnknown) {
+      for (const k in data) {
+        if (!Object.hasOwn(this.def, k)) {
+          out[k] = data[k];
+        }
+      }
+    }
+
+    if (errors.length) {
+      throw new ValidationError(errors);
+    }
+
+    return out;
+  }
+
+  isValid(d, o) {
+    try {
+      this.validate(d, o);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  fields() {
+    return Object.keys(this.def);
+  }
+
+  // ---------------- internal ----------------
+
+  _coerce(v, t, c) {
+    switch (t) {
+      case "string":
+        return String(v);
+
+      case "integer":
+        return Number.isInteger(+v) ? +v : v;
+
+      case "number":
+        return Number.isFinite(+v) ? +v : v;
+
+      case "boolean":
+        return v === "true" ? true : v === "false" ? false : v;
+
+      case "date":
+        return v instanceof Date ? v.toISOString().slice(0, 10) : String(v);
+
+      case "datetime":
+        return v instanceof Date ? v : new Date(v);
+
+      case "envvar":
+        return v;
+
+      default:
+        return v;
+    }
+  }
+
+  _type(k, v, t) {
+    switch (t) {
+      case "string":
+        return typeof v === "string" ? null : `${k} must be string`;
+
+      case "integer":
+        return Number.isInteger(v) ? null : `${k} must be integer`;
+
+      case "number":
+        return typeof v === "number" ? null : `${k} must be number`;
+
+      case "boolean":
+        return typeof v === "boolean" ? null : `${k} must be boolean`;
+
+      case "uuid":
+        return UUID.test(v) ? null : `${k} invalid uuid`;
+
+      case "array":
+        return Array.isArray(v) ? null : `${k} must be array`;
+
+      case "object":
+        return v && typeof v === "object" && !Array.isArray(v)
+          ? null
+          : `${k} must be object`;
+
+      case "envvar":
+        return v != null ? null : `${k} missing env value`;
+
+      default:
+        return null;
+    }
+  }
+}
+
+module.exports = { Schema, ValidationError };

package/package.json

@@ -0,0 +1,31 @@
+{
+  "type": "commonjs",
+  "name": "turbo-schema",
+  "version": "0.1.0",
+  "description": "Light weight object validation schema",
+  "main": "index.js",
+  "keywords": [
+    "light",
+    "weight",
+    "object",
+    "schema",
+    "validate",
+    "validation"
+  ],
+  "homepage": "https://github.com/miketerry-org/turbo-schema#readme",
+  "bugs": {
+    "url": "https://github.com/miketerry-org/turbo-schema/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/miketerry-org/turbo-schema.git"
+  },
+  "license": "MIT",
+  "author": "Mike Terry",
+  "scripts": {
+    "test": "node --test",
+    "test:watch": "node --test --watch",
+    "test:coverage": "node --test --experimental-test-coverage",
+    "test:only": "node --test --test-only"
+  }
+}

package/readme.md

@@ -0,0 +1,452 @@
+# Turbo Schema
+
+A lightweight, dependency-free schema validation library for Node.js.
+
+Turbo Schema validates JavaScript objects against a declarative schema definition. It supports type coercion, default values, required fields, enumerations, regular expression validation, numeric ranges, UUID validation, and configurable handling of unknown properties.
+
+## Features
+
+- Zero dependencies
+- Declarative object schemas
+- Type validation
+- Optional type coercion
+- Default values
+- Required fields
+- Enum validation
+- Pattern (RegExp) validation
+- Minimum and maximum value validation
+- UUID validation
+- Partial validation for updates
+- Optional removal of unknown properties
+- Structured validation errors
+
+---
+
+## Installation
+
+```bash
+npm install turbo-schema
+```
+
+---
+
+## Basic Usage
+
+```javascript
+const { Schema } = require("turbo-schema");
+
+const userSchema = new Schema({
+  id: {
+    type: "uuid",
+    required: true,
+  },
+
+  name: {
+    type: "string",
+    required: true,
+  },
+
+  age: {
+    type: "integer",
+    min: 18,
+  },
+
+  active: {
+    type: "boolean",
+    default: true,
+  },
+});
+
+const user = userSchema.validate({
+  id: "550e8400-e29b-41d4-a716-446655440000",
+  name: "Alice",
+  age: "25",
+});
+
+console.log(user);
+```
+
+Output:
+
+```javascript
+{
+  id: "550e8400-e29b-41d4-a716-446655440000",
+  name: "Alice",
+  age: 25,
+  active: true
+}
+```
+
+---
+
+# Schema Definition
+
+A schema consists of an object whose keys represent field names and whose values define validation rules.
+
+Example:
+
+```javascript
+const schema = new Schema({
+  username: {
+    type: "string",
+    required: true,
+  },
+});
+```
+
+---
+
+## Field Properties
+
+| Property   | Type           | Description                                            |
+| ---------- | -------------- | ------------------------------------------------------ |
+| `type`     | String         | Expected data type                                     |
+| `required` | Boolean        | Field must be present                                  |
+| `default`  | Any / Function | Default value if missing or `null`                     |
+| `enum`     | Array          | List of allowed values                                 |
+| `pattern`  | RegExp         | Regular expression or any object implementing `test()` |
+| `min`      | Number         | Minimum numeric value                                  |
+| `max`      | Number         | Maximum numeric value                                  |
+
+---
+
+## Supported Types
+
+| Type       | Description                |
+| ---------- | -------------------------- |
+| `string`   | String value               |
+| `integer`  | Integer number             |
+| `number`   | Floating point or integer  |
+| `boolean`  | Boolean value              |
+| `uuid`     | UUID string                |
+| `array`    | JavaScript array           |
+| `object`   | Plain JavaScript object    |
+| `date`     | Date string (`YYYY-MM-DD`) |
+| `datetime` | JavaScript `Date` object   |
+
+---
+
+# Validation
+
+```javascript
+const validated = schema.validate(data);
+```
+
+Returns a new validated object.
+
+If validation fails, a `ValidationError` is thrown.
+
+---
+
+# Validation Options
+
+```javascript
+schema.validate(data, {
+  partial: false,
+  coerce: true,
+  stripUnknown: true,
+});
+```
+
+## partial
+
+Default: `false`
+
+When `true`, fields that are missing from the input object are ignored instead of being validated.
+
+Useful for PATCH requests or partial updates.
+
+```javascript
+schema.validate(update, {
+  partial: true,
+});
+```
+
+---
+
+## coerce
+
+Default: `true`
+
+Automatically converts values into the expected type when possible.
+
+Example:
+
+Input:
+
+```javascript
+{
+  age: "42";
+}
+```
+
+Output:
+
+```javascript
+{
+  age: 42;
+}
+```
+
+Disable coercion:
+
+```javascript
+schema.validate(data, {
+  coerce: false,
+});
+```
+
+---
+
+## stripUnknown
+
+Default: `true`
+
+Controls how properties not defined in the schema are handled.
+
+Input:
+
+```javascript
+{
+  name: "Alice",
+  admin: true
+}
+```
+
+Schema:
+
+```javascript
+const schema = new Schema({
+  name: {
+    type: "string",
+  },
+});
+```
+
+With the default setting:
+
+```javascript
+{
+  name: "Alice";
+}
+```
+
+To preserve unknown properties:
+
+```javascript
+schema.validate(data, {
+  stripUnknown: false,
+});
+```
+
+Result:
+
+```javascript
+{
+  name: "Alice",
+  admin: true
+}
+```
+
+---
+
+# Default Values
+
+Defaults are applied when a property is `null` or `undefined`.
+
+Static default:
+
+```javascript
+count: {
+  type: "integer",
+  default: 0
+}
+```
+
+Function default:
+
+```javascript
+created: {
+  type: "datetime",
+  default: () => new Date()
+}
+```
+
+---
+
+# Required Fields
+
+```javascript
+email: {
+  type: "string",
+  required: true
+}
+```
+
+Missing required fields generate validation errors.
+
+---
+
+# Enumerations
+
+```javascript
+status: {
+  enum: ["active", "inactive", "pending"];
+}
+```
+
+Only values contained in the array are accepted.
+
+---
+
+# Pattern Validation
+
+```javascript
+zip: {
+  type: "string",
+  pattern: /^\d{5}$/
+}
+```
+
+Any object implementing a `test()` method may also be supplied.
+
+---
+
+# Numeric Ranges
+
+```javascript
+age: {
+  type: "integer",
+  min: 18,
+  max: 120
+}
+```
+
+---
+
+# UUID Validation
+
+```javascript
+id: {
+  type: "uuid";
+}
+```
+
+UUID values are validated using a built-in regular expression.
+
+---
+
+# Validation Errors
+
+Validation failures throw a `ValidationError`.
+
+```javascript
+try {
+  schema.validate(data);
+} catch (err) {
+  console.error(err.message);
+}
+```
+
+Example:
+
+```
+Schema validation failed: age too small, email required
+```
+
+---
+
+## ValidationError Properties
+
+### message
+
+A human-readable summary of the validation failures.
+
+Example:
+
+```
+Schema validation failed: age too small, email required
+```
+
+---
+
+### errors
+
+An array of validation messages.
+
+```javascript
+["age too small", "email required"];
+```
+
+---
+
+### details
+
+A structured version of each validation error.
+
+```javascript
+[
+  {
+    field: "age",
+    message: "too small",
+  },
+  {
+    field: "email",
+    message: "required",
+  },
+];
+```
+
+---
+
+# isValid()
+
+Returns `true` if validation succeeds, otherwise `false`.
+
+```javascript
+if (schema.isValid(data)) {
+  console.log("Valid");
+}
+```
+
+Equivalent to calling `validate()` and catching any `ValidationError`.
+
+---
+
+# fields()
+
+Returns an array of field names defined by the schema.
+
+```javascript
+schema.fields();
+```
+
+Example:
+
+```javascript
+["id", "name", "email"];
+```
+
+---
+
+# Type Coercion
+
+When coercion is enabled (the default), Turbo Schema performs the following conversions where possible.
+
+| Type       | Example               |
+| ---------- | --------------------- |
+| `string`   | `123 → "123"`         |
+| `integer`  | `"42" → 42`           |
+| `number`   | `"3.14" → 3.14`       |
+| `boolean`  | `"true" → true`       |
+| `boolean`  | `"false" → false`     |
+| `date`     | `Date → "YYYY-MM-DD"` |
+| `datetime` | ISO string → `Date`   |
+
+If a value cannot be coerced, the original value is retained and normal validation determines whether it is valid.
+
+---
+
+# License
+
+MIT