adapt-schemas 1.0.0

package/README.md

@@ -0,0 +1,292 @@
+# adapt-schemas
+
+A standalone JSON Schema library for the Adapt framework stack. Load schemas from plugin folders via glob patterns, validate JSON data, and extract defaults including `_globals` from course schemas.
+
+## Installation
+
+```bash
+npm install adapt-schemas
+```
+
+## Quick Start
+
+```javascript
+import Schemas from 'adapt-schemas'
+
+// Create and initialize the library
+const library = new Schemas()
+await library.init()
+
+// Load schemas from plugin directories
+await library.loadSchemas('**/schema/*.schema.json', {
+  cwd: './plugins',
+  ignore: ['**/node_modules/**']
+})
+
+// Validate data against a schema
+const validatedData = await library.validate('course', {
+  title: 'My Course'
+})
+
+// Get _globals defaults from the course schema
+const globals = await library.getGlobalsDefaults('course')
+```
+
+## API Reference
+
+### Schemas
+
+#### Constructor Options
+
+```javascript
+const library = new Schemas({
+  enableCache: true,              // Enable schema build caching (default: true)
+  xssWhitelist: {},               // Custom XSS whitelist tags/attributes
+  xssWhitelistOverride: false,    // Replace defaults instead of extending
+  formatOverrides: {},            // Custom string format RegExp patterns
+  directoryReplacements: {        // Replacements for isDirectory keyword
+    '$ROOT': '/app',
+    '$DATA': '/app/data'
+  }
+})
+```
+
+#### Methods
+
+##### `init()`
+Initializes the library and loads the base schema.
+
+```javascript
+await library.init()
+```
+
+##### `loadSchemas(patterns, options)`
+Loads schemas from directories matching glob patterns.
+
+```javascript
+await library.loadSchemas('**/schema/*.schema.json', {
+  cwd: './plugins',           // Base directory for patterns
+  ignore: ['**/excluded/**']  // Patterns to exclude
+})
+
+// Multiple patterns
+await library.loadSchemas([
+  'core/**/schema/*.schema.json',
+  'plugins/**/schema/*.schema.json'
+], { ignore: ['**/node_modules/**'] })
+```
+
+##### `registerSchema(filePath, options)`
+Registers a single schema file.
+
+```javascript
+await library.registerSchema('/path/to/schema.json', {
+  replace: false  // Replace existing schema with same name
+})
+```
+
+##### `getSchema(schemaName, options)`
+Retrieves and builds a schema by name.
+
+```javascript
+const schema = await library.getSchema('course', {
+  useCache: true,        // Use cached build if available
+  compile: true,         // Compile the schema
+  applyExtensions: true  // Apply $patch extensions
+})
+```
+
+##### `getBuiltSchema(schemaName)`
+Returns the built schema object.
+
+```javascript
+const schemaObj = await library.getBuiltSchema('course')
+console.log(schemaObj.properties)
+```
+
+##### `validate(schemaName, data, options)`
+Validates data against a named schema.
+
+```javascript
+const validated = await library.validate('course', inputData, {
+  useDefaults: true,     // Apply schema defaults (default: true)
+  ignoreRequired: false  // Ignore required field errors
+})
+```
+
+##### `getSchemaDefaults(schemaName)`
+Returns all defaults as a structured object.
+
+```javascript
+const defaults = await library.getSchemaDefaults('course')
+// { title: 'Untitled', _globals: { ... } }
+```
+
+##### `getGlobalsDefaults(schemaName)`
+Extracts `_globals` defaults from a schema.
+
+```javascript
+const globals = await library.getGlobalsDefaults('course')
+// { _accessibility: { _isEnabled: true, ... }, _extensions: { ... } }
+```
+
+##### `getSchemaNames()`
+Returns list of all registered schema names.
+
+```javascript
+const names = library.getSchemaNames()
+// ['base', 'course', 'content', 'component', ...]
+```
+
+##### `getSchemaInfo()`
+Returns information about all registered schemas.
+
+```javascript
+const info = library.getSchemaInfo()
+// { course: { filePath: '...', extensions: [...], isPatch: false } }
+```
+
+##### `extendSchema(baseSchemaName, extSchemaName)`
+Manually extends a schema with another.
+
+```javascript
+library.extendSchema('course', 'my-course-extension')
+```
+
+##### `addKeyword(definition)`
+Adds a custom AJV keyword.
+
+```javascript
+library.addKeyword({
+  keyword: 'isPositive',
+  type: 'number',
+  validate: (schema, data) => data > 0
+})
+```
+
+##### `addStringFormats(formats)`
+Adds custom string format validators.
+
+```javascript
+library.addStringFormats({
+  'phone': /^\+?[\d\s-]+$/
+})
+```
+
+### Events
+
+The library extends EventEmitter and emits the following events:
+
+```javascript
+library.on('initialized', () => { })
+library.on('reset', () => { })
+library.on('schemasLoaded', (schemaNames) => { })
+library.on('schemaRegistered', (name, filePath) => { })
+library.on('schemaDeregistered', (name) => { })
+library.on('schemaExtended', (baseName, extName) => { })
+library.on('warning', (message) => { })
+```
+
+## Schema Format
+
+### Basic Schema with Inheritance
+
+Schemas use `$merge` to inherit from a parent schema:
+
+```json
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$anchor": "content",
+  "$merge": {
+    "source": { "$ref": "base" },
+    "with": {
+      "properties": {
+        "title": {
+          "type": "string",
+          "default": ""
+        },
+        "body": {
+          "type": "string",
+          "default": ""
+        }
+      },
+      "required": ["title"]
+    }
+  }
+}
+```
+
+### Patch Schema (Extensions)
+
+Use `$patch` to extend an existing schema without creating a new one:
+
+```json
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$anchor": "course-trickle-extension",
+  "$patch": {
+    "source": { "$ref": "course" },
+    "with": {
+      "properties": {
+        "_globals": {
+          "type": "object",
+          "properties": {
+            "_trickle": {
+              "type": "object",
+              "properties": {
+                "incompleteContent": {
+                  "type": "string",
+                  "default": "There is incomplete content above"
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+## Custom Keywords
+
+The library includes these custom AJV keywords:
+
+| Keyword | Description | Example |
+|---------|-------------|---------|
+| `isBytes` | Parses byte strings | `"1MB"` → `1048576` |
+| `isDate` | Parses date strings | `"2024-01-01"` → `Date` |
+| `isTimeMs` | Parses duration strings | `"7d"` → `604800000` |
+| `isDirectory` | Resolves path tokens | `"$ROOT/data"` → `"/app/data"` |
+| `isObjectId` | Marks ObjectId fields | No transformation |
+
+## Error Handling
+
+The library throws `SchemaError` with the following codes:
+
+| Code | Description |
+|------|-------------|
+| `INVALID_PARAMS` | Invalid method parameters |
+| `SCHEMA_EXISTS` | Schema with same name already registered |
+| `SCHEMA_LOAD_FAILED` | Failed to read/parse schema file |
+| `INVALID_SCHEMA` | Schema fails JSON Schema validation |
+| `MISSING_SCHEMA` | Requested schema not found |
+| `VALIDATION_FAILED` | Data fails schema validation |
+| `MODIFY_PROTECTED_ATTR` | Attempt to modify internal/read-only field |
+
+```javascript
+import { SchemaError } from 'adapt-schemas'
+
+try {
+  await library.validate('course', data)
+} catch (e) {
+  if (e instanceof SchemaError) {
+    console.log(e.code)    // 'VALIDATION_FAILED'
+    console.log(e.data)    // { schemaName, errors, data }
+  }
+}
+```
+
+## License
+
+MIT

package/index.js

@@ -0,0 +1,7 @@
+import Schemas, { SchemaError } from './lib/Schemas.js'
+import Schema from './lib/Schema.js'
+import Keywords from './lib/Keywords.js'
+import XSSDefaults from './lib/XSSDefaults.js'
+
+export { Schemas, Schema, SchemaError, Keywords, XSSDefaults }
+export default Schemas

package/lib/Keywords.js

@@ -0,0 +1,98 @@
+import bytes from 'bytes'
+import ms from 'ms'
+import path from 'path'
+
+/**
+ * Custom JSON schema keywords for AJV
+ */
+class Keywords {
+  /**
+   * Returns all custom keywords
+   * @param {Object} directoryReplacements Replacements for isDirectory (e.g. { '$ROOT': '/app' })
+   * @returns {Object[]} Array of AJV keyword definitions
+   */
+  static all(directoryReplacements = {}) {
+    const keywords = {
+      /**
+       * Parses byte string values (e.g., "1MB" -> 1048576)
+       */
+      isBytes: function () {
+        return (value, { parentData, parentDataProperty }) => {
+          try {
+            parentData[parentDataProperty] = bytes.parse(value)
+            return true
+          } catch (e) {
+            return false
+          }
+        }
+      },
+
+      /**
+       * Parses date string values into Date objects
+       */
+      isDate: function () {
+        return (value, { parentData, parentDataProperty }) => {
+          try {
+            parentData[parentDataProperty] = new Date(value)
+            return true
+          } catch (e) {
+            return false
+          }
+        }
+      },
+
+      /**
+       * Resolves directory path tokens ($ROOT, $DATA, $TEMP, etc.)
+       */
+      isDirectory: function () {
+        const doReplace = value => {
+          const replacements = Object.entries(directoryReplacements)
+          return replacements.reduce((m, [k, v]) => {
+            return m.startsWith(k) ? path.resolve(v, m.replace(k, '').slice(1)) : m
+          }, value)
+        }
+        return (value, { parentData, parentDataProperty }) => {
+          try {
+            parentData[parentDataProperty] = doReplace(value)
+          } catch (e) {
+            // Keep original value on error
+          }
+          return true
+        }
+      },
+
+      /**
+       * Parses time duration strings into milliseconds (e.g., "7d" -> 604800000)
+       */
+      isTimeMs: function () {
+        return (value, { parentData, parentDataProperty }) => {
+          try {
+            parentData[parentDataProperty] = ms(value)
+            return true
+          } catch (e) {
+            return false
+          }
+        }
+      },
+
+      /**
+       * Marker for ObjectId fields (no transformation, just marks the field)
+       */
+      isObjectId: function () {
+        return () => true
+      }
+    }
+
+    return Object.entries(keywords).map(([keyword, compile]) => {
+      return {
+        keyword,
+        type: 'string',
+        modifying: true,
+        schemaType: 'boolean',
+        compile
+      }
+    })
+  }
+}
+
+export default Keywords