sorla-db 1.2.0 → 1.4.0

package/src/query_language/update.js

@@ -0,0 +1,167 @@
+/**
+ * Update operators: $set, $unset, $inc, $push and $pull, with "a.b" paths.
+ * Updates are applied to a copy of the document, so a failing operator never leaves it half updated.
+ */
+const UPDATE_OPERATORS = ['$set', '$unset', '$inc', '$push', '$pull'];
+
+const isPlainObject = value => value !== null && typeof value === 'object' && !Array.isArray(value)
+    && Object.prototype.toString.call(value) === '[object Object]';
+
+function splitPath(path)
+{
+    if(typeof path !== 'string' || path === '' || path.split('.').some(part => part === ''))
+        throw new Error(`Invalid field path "${path}"`);
+
+    if(path === '_id' || path.startsWith('_id.'))
+        throw new Error('The _id field cannot be updated');
+
+    return path.split('.');
+}
+
+function getPath(data, parts)
+{
+    let value = data;
+    for(const part of parts)
+    {
+        if(value === null || typeof value !== 'object' || !(part in value))
+            return undefined;
+
+        value = value[part];
+    }
+    return value;
+}
+
+/**
+ * Parent object of a path, creating missing objects on the way
+ */
+function parentOf(data, parts, create)
+{
+    let target = data;
+    for(const part of parts.slice(0, -1))
+    {
+        if(!(part in target))
+        {
+            if(!create) return null;
+            target[part] = {};
+        }
+
+        if(target[part] === null || typeof target[part] !== 'object')
+            throw new Error(`Cannot create the field "${parts.join('.')}": "${part}" is not an object`);
+
+        target = target[part];
+    }
+    return target;
+}
+
+/**
+ * Validates an update document
+ * @param object update
+ * @return void
+ */
+function validateUpdate(update)
+{
+    if(!isPlainObject(update))
+        throw new Error('The update must be an object like {$set: {field: value}}');
+
+    const keys = Object.keys(update);
+    if(!keys.length)
+        throw new Error('The update must contain at least one operator');
+
+    for(const key of keys)
+    {
+        if(!key.startsWith('$'))
+            throw new Error(`The update can only contain operators, use replaceOne() to replace a document (found "${key}")`);
+
+        if(!UPDATE_OPERATORS.includes(key))
+            throw new Error(`Unknown update operator ${key}`);
+
+        if(!isPlainObject(update[key]))
+            throw new Error(`The ${key} operator must be an object like {${key}: {field: value}}`);
+    }
+}
+
+/**
+ * Applies an update to a copy of the data
+ * @param object data stored document data
+ * @param object update
+ * @param object helpers {copy(value), validateKeys(object), operators}
+ * @return object the updated copy
+ */
+function applyUpdate(data, update, helpers)
+{
+    validateUpdate(update);
+    const result = helpers.copy(data);
+
+    for(const [path, value] of Object.entries(update.$set ?? {}))
+    {
+        const parts = splitPath(path);
+        if(value !== null && typeof value === 'object' && !helpers.validateKeys(Array.isArray(value) ? { value } : value))
+            throw new Error('Invalid document keys');
+
+        parentOf(result, parts, true)[parts.at(-1)] = helpers.copy(value);
+    }
+
+    for(const path of Object.keys(update.$unset ?? {}))
+    {
+        const parts = splitPath(path);
+        const parent = parentOf(result, parts, false);
+        if(parent && !Array.isArray(parent))
+            delete parent[parts.at(-1)];
+    }
+
+    for(const [path, amount] of Object.entries(update.$inc ?? {}))
+    {
+        const parts = splitPath(path);
+        if(typeof amount !== 'number' || !Number.isFinite(amount))
+            throw new Error(`$inc needs a number for "${path}"`);
+
+        const current = getPath(result, parts);
+        if(current !== undefined && typeof current !== 'number')
+            throw new Error(`Cannot $inc "${path}": it is not a number`);
+
+        parentOf(result, parts, true)[parts.at(-1)] = (current ?? 0) + amount;
+    }
+
+    for(const [path, value] of Object.entries(update.$push ?? {}))
+    {
+        const parts = splitPath(path);
+        const current = getPath(result, parts);
+        if(current !== undefined && !Array.isArray(current))
+            throw new Error(`Cannot $push to "${path}": it is not an array`);
+
+        const items = isPlainObject(value) && Array.isArray(value.$each) ? value.$each : [value];
+        for(const item of items)
+        {
+            if(item !== null && typeof item === 'object' && !helpers.validateKeys(Array.isArray(item) ? { item } : item))
+                throw new Error('Invalid document keys');
+        }
+        parentOf(result, parts, true)[parts.at(-1)] = [...(current ?? []), ...items.map(helpers.copy)];
+    }
+
+    for(const [path, condition] of Object.entries(update.$pull ?? {}))
+    {
+        const parts = splitPath(path);
+        const current = getPath(result, parts);
+        if(current === undefined)
+            continue;
+
+        if(!Array.isArray(current))
+            throw new Error(`Cannot $pull from "${path}": it is not an array`);
+
+        const { operators } = helpers;
+        const matches = item => {
+            if(operators.isRegExp(condition) || operators.isOperatorObject(condition))
+                return operators.matchesCondition(item, condition);
+
+            if(isPlainObject(condition))
+                return isPlainObject(item) && operators.matches(item, condition);
+
+            return item === condition;
+        };
+        parentOf(result, parts, false)[parts.at(-1)] = current.filter(item => !matches(item));
+    }
+
+    return result;
+}
+
+module.exports = { applyUpdate, validateUpdate, UPDATE_OPERATORS };

package/src/schema/schema.js

@@ -0,0 +1,306 @@
+/**
+ * Document validation with a subset of JSON Schema.
+ *
+ *   {
+ *     type: 'object',
+ *     required: ['name', 'email'],
+ *     additionalProperties: false,
+ *     properties: {
+ *       name: { type: 'string', minLength: 2, maxLength: 80 },
+ *       email: { type: 'string', format: 'email' },
+ *       age: { type: ['integer', 'null'], minimum: 0 },
+ *       role: { enum: ['admin', 'user'], default: 'user' },
+ *       tags: { type: 'array', items: { type: 'string' }, uniqueItems: true },
+ *       address: { type: 'object', properties: { zip: { type: 'string', pattern: '^\\d{5}-\\d{3}$' } } }
+ *     }
+ *   }
+ *
+ * Extension: type 'date' accepts Date objects (like MongoDB's bsonType 'date').
+ * A function schema is also accepted: doc => true | 'message' | ['message', ...] | false.
+ */
+const TYPES = ['string', 'number', 'integer', 'boolean', 'object', 'array', 'null', 'date'];
+const FORMATS = ['email', 'date', 'date-time', 'uri'];
+const KEYWORDS = new Set([
+    'type', 'properties', 'required', 'additionalProperties', 'items', 'enum', 'const', 'default',
+    'minimum', 'maximum', 'exclusiveMinimum', 'exclusiveMaximum', 'minLength', 'maxLength', 'pattern',
+    'format', 'minItems', 'maxItems', 'uniqueItems', 'title', 'description', '$schema', '$id', 'examples'
+]);
+
+class ValidationError extends Error
+{
+    /**
+     * @param array errors [{path, rule, message}]
+     */
+    constructor(errors)
+    {
+        const first = errors[0];
+        super(errors.length === 1
+            ? `Invalid document: ${first.message}`
+            : `Invalid document: ${first.message} (and ${errors.length - 1} more)`);
+        this.name = 'ValidationError';
+        this.errors = errors;
+    }
+}
+
+const isPlainObject = value => Object.prototype.toString.call(value) === '[object Object]';
+const isDate = value => Object.prototype.toString.call(value) === '[object Date]';
+
+function typeOf(value)
+{
+    if(value === null) return 'null';
+    if(Array.isArray(value)) return 'array';
+    if(isDate(value)) return 'date';
+    if(typeof value === 'number') return Number.isInteger(value) ? 'integer' : 'number';
+    if(isPlainObject(value)) return 'object';
+    return typeof value;
+}
+
+function matchesType(value, type)
+{
+    const actual = typeOf(value);
+    if(type === 'number') return actual === 'number' || actual === 'integer';
+    return actual === type;
+}
+
+const FORMAT_TESTS = {
+    email: value => /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value),
+    date: value => {
+        const match = /^(\d{4})-(\d{2})-(\d{2})$/.exec(value);
+        if(!match) return false;
+        const date = new Date(Date.UTC(+match[1], +match[2] - 1, +match[3]));
+        return date.getUTCMonth() === +match[2] - 1 && date.getUTCDate() === +match[3];
+    },
+    'date-time': value => /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(:\d{2}(\.\d+)?)?(Z|[+-]\d{2}:\d{2})?$/.test(value) && !isNaN(Date.parse(value)),
+    uri: value => {
+        try {
+            return Boolean(new URL(value).protocol);
+        } catch(error) {
+            return false;
+        }
+    }
+};
+
+/**
+ * Checks the schema itself, so typos fail when the schema is set instead of being ignored
+ * @param object schema
+ * @param string path
+ * @return void
+ */
+function checkSchema(schema, path = 'schema')
+{
+    if(!isPlainObject(schema))
+        throw new Error(`${path} must be an object`);
+
+    for(const key of Object.keys(schema))
+    {
+        if(!KEYWORDS.has(key))
+            throw new Error(`${path}: unknown keyword "${key}"`);
+    }
+
+    const types = schema.type === undefined ? [] : Array.isArray(schema.type) ? schema.type : [schema.type];
+    for(const type of types)
+    {
+        if(!TYPES.includes(type))
+            throw new Error(`${path}: unknown type "${type}" (use ${TYPES.join(', ')})`);
+    }
+
+    if(schema.format !== undefined && !FORMATS.includes(schema.format))
+        throw new Error(`${path}: unknown format "${schema.format}" (use ${FORMATS.join(', ')})`);
+
+    if(schema.required !== undefined && (!Array.isArray(schema.required) || schema.required.some(name => typeof name !== 'string')))
+        throw new Error(`${path}: required must be an array of field names`);
+
+    if(schema.enum !== undefined && !Array.isArray(schema.enum))
+        throw new Error(`${path}: enum must be an array`);
+
+    if(schema.pattern !== undefined)
+    {
+        try {
+            new RegExp(schema.pattern);
+        } catch(error) {
+            throw new Error(`${path}: invalid pattern (${error.message})`);
+        }
+    }
+
+    for(const key of ['minimum', 'maximum', 'exclusiveMinimum', 'exclusiveMaximum', 'minLength', 'maxLength', 'minItems', 'maxItems'])
+    {
+        if(schema[key] !== undefined && (typeof schema[key] !== 'number' || !Number.isFinite(schema[key])))
+            throw new Error(`${path}: ${key} must be a number`);
+    }
+
+    if(schema.properties !== undefined)
+    {
+        if(!isPlainObject(schema.properties))
+            throw new Error(`${path}: properties must be an object`);
+
+        for(const [name, child] of Object.entries(schema.properties))
+            checkSchema(child, `${path}.properties.${name}`);
+    }
+
+    if(schema.additionalProperties !== undefined && typeof schema.additionalProperties !== 'boolean')
+        checkSchema(schema.additionalProperties, `${path}.additionalProperties`);
+
+    if(schema.items !== undefined)
+        checkSchema(schema.items, `${path}.items`);
+}
+
+const describe = value => {
+    if(typeof value === 'string') return JSON.stringify(value.length > 40 ? `${value.slice(0, 40)}…` : value);
+    if(isDate(value)) return value.toISOString();
+    return JSON.stringify(value);
+};
+
+const same = (a, b) => {
+    if(isDate(a) && isDate(b)) return a.getTime() === b.getTime();
+    return JSON.stringify(a) === JSON.stringify(b);
+};
+
+/**
+ * Validates a value against a schema
+ * @param mixed value
+ * @param object schema
+ * @param string path field path for error messages ('' for the document)
+ * @param array errors collected errors
+ * @return array errors
+ */
+function validateValue(value, schema, path = '', errors = [])
+{
+    const label = path || 'document';
+    const add = (rule, message) => errors.push({ path, rule, message: `${label} ${message}` });
+
+    if(schema.type !== undefined)
+    {
+        const types = Array.isArray(schema.type) ? schema.type : [schema.type];
+        if(!types.some(type => matchesType(value, type)))
+        {
+            add('type', `must be ${types.join(' or ')} (got ${typeOf(value)})`);
+            return errors;
+        }
+    }
+
+    if(schema.enum !== undefined && !schema.enum.some(option => same(option, value)))
+        add('enum', `must be one of ${schema.enum.map(describe).join(', ')}`);
+
+    if(schema.const !== undefined && !same(schema.const, value))
+        add('const', `must be ${describe(schema.const)}`);
+
+    if(typeof value === 'number')
+    {
+        if(schema.minimum !== undefined && value < schema.minimum) add('minimum', `must be >= ${schema.minimum}`);
+        if(schema.maximum !== undefined && value > schema.maximum) add('maximum', `must be <= ${schema.maximum}`);
+        if(schema.exclusiveMinimum !== undefined && value <= schema.exclusiveMinimum) add('exclusiveMinimum', `must be > ${schema.exclusiveMinimum}`);
+        if(schema.exclusiveMaximum !== undefined && value >= schema.exclusiveMaximum) add('exclusiveMaximum', `must be < ${schema.exclusiveMaximum}`);
+    }
+
+    if(typeof value === 'string')
+    {
+        // count characters, not UTF-16 units, so emoji and accents count once
+        const length = [...value].length;
+        if(schema.minLength !== undefined && length < schema.minLength) add('minLength', `must have at least ${schema.minLength} characters`);
+        if(schema.maxLength !== undefined && length > schema.maxLength) add('maxLength', `must have at most ${schema.maxLength} characters`);
+        if(schema.pattern !== undefined && !new RegExp(schema.pattern, 'u').test(value)) add('pattern', `must match ${schema.pattern}`);
+        if(schema.format !== undefined && !FORMAT_TESTS[schema.format](value)) add('format', `must be a valid ${schema.format}`);
+    }
+
+    if(Array.isArray(value))
+    {
+        if(schema.minItems !== undefined && value.length < schema.minItems) add('minItems', `must have at least ${schema.minItems} items`);
+        if(schema.maxItems !== undefined && value.length > schema.maxItems) add('maxItems', `must have at most ${schema.maxItems} items`);
+        if(schema.uniqueItems && new Set(value.map(item => JSON.stringify(item))).size !== value.length) add('uniqueItems', 'must not have repeated items');
+        if(schema.items !== undefined)
+            value.forEach((item, index) => validateValue(item, schema.items, `${path}[${index}]`, errors));
+    }
+
+    if(isPlainObject(value))
+    {
+        const properties = schema.properties ?? {};
+        const child = name => path ? `${path}.${name}` : name;
+
+        for(const name of schema.required ?? [])
+        {
+            if(value[name] === undefined)
+                errors.push({ path: child(name), rule: 'required', message: `${child(name)} is required` });
+        }
+
+        for(const [name, fieldValue] of Object.entries(value))
+        {
+            if(fieldValue === undefined)
+                continue;
+
+            if(properties[name] !== undefined)
+            {
+                validateValue(fieldValue, properties[name], child(name), errors);
+            }
+            else if(!(path === '' && name === '_id'))
+            {
+                // _id is always allowed on documents
+                if(schema.additionalProperties === false)
+                    errors.push({ path: child(name), rule: 'additionalProperties', message: `${child(name)} is not allowed` });
+                else if(isPlainObject(schema.additionalProperties))
+                    validateValue(fieldValue, schema.additionalProperties, child(name), errors);
+            }
+        }
+    }
+
+    return errors;
+}
+
+/**
+ * Fills missing fields that declare a default (recursively for objects present in the document)
+ * @param mixed value
+ * @param object schema
+ * @param function copy
+ * @return void
+ */
+function applyDefaults(value, schema, copy)
+{
+    if(!isPlainObject(value) || !isPlainObject(schema.properties))
+        return;
+
+    for(const [name, child] of Object.entries(schema.properties))
+    {
+        if(value[name] === undefined && child.default !== undefined)
+            value[name] = copy(child.default);
+
+        if(value[name] !== undefined)
+            applyDefaults(value[name], child, copy);
+    }
+}
+
+/**
+ * Compiles a schema (JSON Schema subset or a function) into a validator
+ * @param object|function schema
+ * @return object {validate(doc): errors, applyDefaults(doc, copy), source}
+ */
+function compileSchema(schema)
+{
+    if(typeof schema === 'function')
+    {
+        return {
+            source: schema,
+            applyDefaults: () => {},
+            validate: doc => {
+                const result = schema(doc);
+                if(result === true || result === undefined || result === null) return [];
+                if(result === false) return [{ path: '', rule: 'custom', message: 'document is invalid' }];
+                const messages = Array.isArray(result) ? result : [result];
+                return messages.map(message => typeof message === 'string'
+                    ? { path: '', rule: 'custom', message }
+                    : { path: '', rule: 'custom', ...message });
+            }
+        };
+    }
+
+    const root = { type: 'object', ...schema };
+    checkSchema(root);
+    if(root.type !== 'object')
+        throw new Error('schema: a document schema must be of type "object"');
+
+    return {
+        source: schema,
+        validate: doc => validateValue(doc, root),
+        applyDefaults: (doc, copy) => applyDefaults(doc, root, copy)
+    };
+}
+
+module.exports = { compileSchema, ValidationError, validateValue, checkSchema };

package/src/sorla.js

@@ -1,4 +1,5 @@
 const database = require('./dbs/database.js');
+const { ValidationError } = require('./schema/schema.js');
 
 class sorla{
     /**
@@ -103,6 +104,33 @@ class sorla{
         return this._dbs.length;
     }
 
+    /**
+     * Names of the databases, in creation order
+     * @return array
+     */
+    listDatabases()
+    {
+        return this._dbs.map(db => db.name);
+    }
+
+    /**
+     * Removes a database and its collections; when it was selected, no database stays selected
+     * @param string name
+     * @return boolean false when it did not exist
+     */
+    dropDb(name)
+    {
+        const pos = this._findDbIndex(name);
+        if(pos === -1)
+            return false;
+
+        if(this._selectedDb === this._dbs[pos])
+            this._selectedDb = null;
+
+        this._dbs.splice(pos, 1);
+        return true;
+    }
+
     /**
      * Return selected db
      * @author Anderson Arruda < anderson@sysborg.com.br >
@@ -116,6 +144,9 @@ class sorla{
     }
 }
 
+// thrown when a document does not satisfy the collection schema: error.errors = [{path, rule, message}]
+sorla.ValidationError = ValidationError;
+
 module.exports = sorla;
 if(typeof window !== 'undefined')
 {