minions-sdk 0.1.0

package/dist/validation/index.js

@@ -0,0 +1,173 @@
+/**
+ * @module minions-sdk/validation
+ * Field validation engine for the Minions system.
+ * Validates minion field values against their MinionType schema.
+ */
+const EMAIL_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+const ISO8601_RE = /^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2}))?$/;
+/**
+ * Validate a single field value against its definition.
+ * @param value - The value to validate
+ * @param field - The field definition to validate against
+ * @returns Array of validation errors (empty if valid)
+ */
+export function validateField(value, field) {
+    const errors = [];
+    const isAbsent = value === undefined || value === null || value === '';
+    // Required check
+    if (field.required && isAbsent) {
+        errors.push({ field: field.name, message: `Field "${field.name}" is required`, value });
+        return errors;
+    }
+    // If not present and not required, skip further validation
+    if (isAbsent)
+        return errors;
+    // Type-specific validation
+    const typeErrors = validateFieldType(value, field);
+    errors.push(...typeErrors);
+    return errors;
+}
+/**
+ * Validate a value matches the expected field type and constraints.
+ */
+function validateFieldType(value, field) {
+    const errors = [];
+    const { name, type, options, validation } = field;
+    const typeValidators = {
+        string: () => {
+            if (typeof value !== 'string') {
+                errors.push({ field: name, message: `Expected string, got ${typeof value}`, value });
+                return;
+            }
+            applyStringConstraints(value, name, validation, errors);
+        },
+        textarea: () => {
+            if (typeof value !== 'string') {
+                errors.push({ field: name, message: `Expected string, got ${typeof value}`, value });
+                return;
+            }
+            applyStringConstraints(value, name, validation, errors);
+        },
+        number: () => {
+            if (typeof value !== 'number' || Number.isNaN(value)) {
+                errors.push({ field: name, message: `Expected number, got ${typeof value}`, value });
+                return;
+            }
+            if (validation?.min !== undefined && value < validation.min) {
+                errors.push({ field: name, message: `Value must be >= ${validation.min}`, value });
+            }
+            if (validation?.max !== undefined && value > validation.max) {
+                errors.push({ field: name, message: `Value must be <= ${validation.max}`, value });
+            }
+        },
+        boolean: () => {
+            if (typeof value !== 'boolean') {
+                errors.push({ field: name, message: `Expected boolean, got ${typeof value}`, value });
+            }
+        },
+        date: () => {
+            if (typeof value !== 'string' || !ISO8601_RE.test(value)) {
+                errors.push({ field: name, message: `Expected valid ISO 8601 date string`, value });
+            }
+        },
+        select: () => {
+            if (typeof value !== 'string') {
+                errors.push({ field: name, message: `Expected string for select, got ${typeof value}`, value });
+                return;
+            }
+            if (options && !options.includes(value)) {
+                errors.push({ field: name, message: `Value must be one of: ${options.join(', ')}`, value });
+            }
+        },
+        'multi-select': () => {
+            if (!Array.isArray(value)) {
+                errors.push({ field: name, message: `Expected array for multi-select, got ${typeof value}`, value });
+                return;
+            }
+            if (options) {
+                for (const item of value) {
+                    if (!options.includes(item)) {
+                        errors.push({ field: name, message: `Invalid option: ${item}. Must be one of: ${options.join(', ')}`, value: item });
+                    }
+                }
+            }
+        },
+        url: () => {
+            if (typeof value !== 'string') {
+                errors.push({ field: name, message: `Expected valid URL (http/https)`, value });
+                return;
+            }
+            try {
+                const parsed = new URL(value);
+                if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+                    errors.push({ field: name, message: `Expected valid URL (http/https)`, value });
+                }
+            }
+            catch {
+                errors.push({ field: name, message: `Expected valid URL (http/https)`, value });
+            }
+        },
+        email: () => {
+            if (typeof value !== 'string' || !EMAIL_RE.test(value)) {
+                errors.push({ field: name, message: `Expected valid email address`, value });
+            }
+        },
+        tags: () => {
+            if (!Array.isArray(value)) {
+                errors.push({ field: name, message: `Expected array for tags, got ${typeof value}`, value });
+                return;
+            }
+            for (const tag of value) {
+                if (typeof tag !== 'string') {
+                    errors.push({ field: name, message: `Tag values must be strings`, value: tag });
+                }
+            }
+        },
+        json: () => {
+            if (typeof value !== 'object' && typeof value !== 'string' && typeof value !== 'number' && typeof value !== 'boolean') {
+                errors.push({ field: name, message: `Expected valid JSON value`, value });
+            }
+        },
+        array: () => {
+            if (!Array.isArray(value)) {
+                errors.push({ field: name, message: `Expected array, got ${typeof value}`, value });
+            }
+        },
+    };
+    const validator = typeValidators[type];
+    if (validator) {
+        validator();
+    }
+    else {
+        errors.push({ field: name, message: `Unknown field type: ${type}`, value });
+    }
+    return errors;
+}
+function applyStringConstraints(value, fieldName, validation, errors) {
+    if (!validation)
+        return;
+    if (validation.minLength !== undefined && value.length < validation.minLength) {
+        errors.push({ field: fieldName, message: `Must be at least ${validation.minLength} characters`, value });
+    }
+    if (validation.maxLength !== undefined && value.length > validation.maxLength) {
+        errors.push({ field: fieldName, message: `Must be at most ${validation.maxLength} characters`, value });
+    }
+    if (validation.pattern !== undefined && !new RegExp(validation.pattern).test(value)) {
+        errors.push({ field: fieldName, message: `Must match pattern: ${validation.pattern}`, value });
+    }
+}
+/**
+ * Validate all fields of a minion against a MinionType schema.
+ * @param fields - The minion's field values
+ * @param schema - The field definitions from the MinionType
+ * @returns Validation result with any errors
+ */
+export function validateFields(fields, schema) {
+    const errors = [];
+    for (const fieldDef of schema) {
+        const value = fields[fieldDef.name];
+        errors.push(...validateField(value, fieldDef));
+    }
+    return { valid: errors.length === 0, errors };
+}
+//# sourceMappingURL=index.js.map

package/dist/validation/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/validation/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "minions-sdk",
+  "version": "0.1.0",
+  "description": "Framework-agnostic core library for the Minions structured object system",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mxn2020/minions"
+  },
+  "homepage": "https://github.com/mxn2020/minions",
+  "keywords": [
+    "ai",
+    "agents",
+    "structured-objects",
+    "schema",
+    "minions"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "devDependencies": {
+    "typescript": "^5.3.3",
+    "vitest": "^1.6.1",
+    "typedoc": "^0.28.0",
+    "typedoc-plugin-markdown": "^4.4.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "tsc --noEmit",
+    "docs": "typedoc"
+  }
+}