sorla-db 1.1.0 → 1.2.0

package/index.d.ts

@@ -0,0 +1,89 @@
+// Type declarations for sorla-db
+
+export type Document = Record<string, unknown> & { _id?: unknown };
+
+export type ComparisonOperators = {
+    $eq?: unknown;
+    $ne?: unknown;
+    $gt?: unknown;
+    $gte?: unknown;
+    $lt?: unknown;
+    $lte?: unknown;
+    $in?: unknown[];
+    $nin?: unknown[];
+    $not?: ComparisonOperators;
+};
+
+/** A query: field conditions (value or operators, "a.b" paths allowed) and nested $and / $or / $nor. */
+export type Query = {
+    $and?: Query[];
+    $or?: Query[];
+    $nor?: Query[];
+    [field: string]: unknown;
+};
+
+export type Projection = Record<string, 0>;
+export type SortSpec = Record<string, 1 | -1>;
+
+export interface SortOptions {
+    /** Intl.Collator options plus the locale, e.g. { locale: 'pt-BR', sensitivity: 'base', numeric: true } */
+    collation?: Intl.CollatorOptions & { locale?: string };
+}
+
+export interface StoredDocument {
+    readonly _data: Document;
+    readonly [field: string]: unknown;
+}
+
+export declare class Cursor {
+    readonly length: number;
+    currIndex: number;
+    hasNext(): boolean;
+    next(): StoredDocument;
+    reset(): void;
+    /** Data of the first document, null when empty. */
+    first(): Document | null;
+    /** Data of the last document, null when empty. */
+    last(): Document | null;
+    /** Plain copies of the documents. */
+    toArray(): Document[];
+    sort(spec: SortSpec, options?: SortOptions): this;
+    projection(projection: Projection): void;
+    push(element: object): void;
+}
+
+export declare class Collection {
+    readonly first: Document;
+    readonly last: Document;
+    readonly all: StoredDocument[];
+    count(): number;
+    /** Inserts a copy of the document and returns its _id. */
+    insertOne(document: Document, callback?: (id: unknown) => void): unknown;
+    /** Validates every document first, then inserts them and returns their ids. */
+    insertMany(documents: Document[], callback?: (ids: unknown[]) => void): unknown[];
+    find(query: Query, projection?: Projection | null): Cursor;
+    /** Data of the first matching document, null when nothing matches. */
+    findOne(query: Query, projection?: Projection | null): Document | null;
+}
+
+export declare class Database {
+    readonly name: string;
+    createCollection(name: string, validationSchema?: unknown): void;
+    countCollections(): number;
+    [collection: string]: unknown;
+}
+
+declare class sorla {
+    constructor();
+    /** The selected database. Collections are properties of it: sorla.db.people */
+    readonly db: Database & Record<string, Collection>;
+    dbExists(name: string): boolean;
+    /** Position of the new database, or false when the name exists. */
+    createDb(name: string): number | false;
+    /** Selects a database, creating it when needed. */
+    useDb(name: string): void;
+    countDb(): number;
+}
+
+export { sorla };
+export default sorla;

package/index.mjs

@@ -0,0 +1,5 @@
+// ES module entry: import sorla from 'sorla-db'
+import sorla from './src/sorla.js';
+
+export { sorla };
+export default sorla;

package/package.json

@@ -1,11 +1,32 @@
 {
   "name": "sorla-db",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "A simple and temporary database focused to use in browser environment that will bring capabilities for other tools that will be launched as soon as possible.",
-  "main": "dist/sorla.min.js",
+  "main": "src/sorla.js",
+  "module": "index.mjs",
+  "types": "index.d.ts",
+  "unpkg": "dist/sorla.min.js",
+  "jsdelivr": "dist/sorla.min.js",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.mjs",
+      "require": "./src/sorla.js"
+    },
+    "./dist/sorla.min.js": "./dist/sorla.min.js",
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "!src/helper.js",
+    "dist",
+    "index.mjs",
+    "index.d.ts"
+  ],
   "scripts": {
+    "build": "node index.js",
     "mini": "node index.js",
-    "build": "webpack",
     "test": "jest"
   },
   "repository": {
@@ -38,5 +59,8 @@
     "jsdom-global": "^3.0.2",
     "mocha": "^10.2.0",
     "terser": "^5.27.0"
+  },
+  "engines": {
+    "node": ">=18"
   }
 }

package/src/documents/cursor.js

@@ -3,7 +3,6 @@
  * @description Cursor class is used to represent the cursor in the document, adding some extra capabilities to object.
  */
 
-const documents = require('../documents/document.js');
 
 class cursor {
     /**
@@ -45,7 +44,8 @@ class cursor {
      * @return array
      */
     toArray() {
-        return structuredClone(this._data);
+        // the documents are proxies, which structuredClone cannot copy: clone their data
+        return this._data.map(doc => structuredClone(doc._data));
     }
 
     /**
@@ -63,7 +63,7 @@ class cursor {
      * @return mixed
      */
     first() {
-        return this._data[0]._data;
+        return this._data.length ? this._data[0]._data : null;
     }
 
     /**
@@ -72,30 +72,45 @@ class cursor {
      * @return mixed
      */
     last() {
-        return this._data[this._data.length - 1];
+        return this._data.length ? this._data[this._data.length - 1]._data : null;
     }
 
     /**
      * @method sort
-     * @description Sort the cursor using collection
-     * @param json sortQuery
-     * @return void
+     * @description Sort the documents of the cursor, like MongoDB: {age: -1, name: 1}
+     * Values of different types follow MongoDB's order: missing and null, numbers, strings,
+     * objects, arrays, booleans, dates. Strings compare by code point unless a collation is given.
+     * @param json sortQuery field => 1 (ascending) or -1 (descending), "a.b" paths allowed
+     * @param json options {collation: {locale, sensitivity, numeric...}} (Intl.Collator options)
+     * @return cursor
      */
-    sort(sortQuery) {
-        const queryDoc = new documents(sortQuery);
+    sort(sortQuery, options = {}) {
+        if(sortQuery === null || typeof sortQuery !== 'object' || Array.isArray(sortQuery))
+            throw new Error('The sort query must be an object like {field: 1}');
+
+        const keys = Object.keys(sortQuery);
+        for(const key of keys)
+        {
+            if(sortQuery[key] !== 1 && sortQuery[key] !== -1)
+                throw new Error(`Sort direction of "${key}" must be 1 or -1`);
+        }
+
+        const collation = options.collation
+            ? new Intl.Collator(options.collation.locale, options.collation)
+            : null;
+
         this._data.sort((a, b) => {
-            for(const key of Object.keys(sortQuery))
+            for(const key of keys)
             {
-                const ascending = queryDoc[key] === 1;
-                if(a[key] > b[key])
-                    return ascending ? 1 : -1;
-
-                if(a[key] < b[key])
-                    return ascending ? -1 : 1;
+                const result = compareValues(a[key], b[key], collation);
+                if(result !== 0)
+                    return result * sortQuery[key];
             }
 
             return 0;
         });
+
+        return this;
     }
 
     /**
@@ -141,4 +156,53 @@ class cursor {
     }
 }
 
+/**
+ * Rank of a value in MongoDB's comparison order
+ * @param mixed value
+ * @return number
+ */
+function typeRank(value) {
+    if(value === undefined || value === null) return 0;
+    if(typeof value === 'number') return 1;
+    if(typeof value === 'string') return 2;
+    // toString instead of instanceof: Dates from another realm (iframes, workers, vm) still count
+    if(Object.prototype.toString.call(value) === '[object Date]') return 6;
+    if(Array.isArray(value)) return 4;
+    if(typeof value === 'object') return 3;
+    if(typeof value === 'boolean') return 5;
+    return 7;
+}
+
+/**
+ * Compares two field values for sorting
+ * @param mixed a
+ * @param mixed b
+ * @param Intl.Collator|null collation
+ * @return number -1, 0 or 1
+ */
+function compareValues(a, b, collation) {
+    const rankA = typeRank(a);
+    const rankB = typeRank(b);
+    if(rankA !== rankB) return rankA < rankB ? -1 : 1;
+
+    switch(rankA) {
+        case 0:
+            return 0;
+        case 2:
+            if(collation) return Math.sign(collation.compare(a, b));
+            break;
+        case 3:
+        case 4:
+            a = JSON.stringify(a);
+            b = JSON.stringify(b);
+            break;
+        case 6:
+            a = a.getTime();
+            b = b.getTime();
+            break;
+    }
+
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+
 module.exports = cursor;

package/src/documents/document.js

@@ -1,7 +1,10 @@
 const utils = require('../utils');
-const cursor = require('./cursor');
-const manipulation = require('../query_language/manipulation');
 
+/**
+ * A stored document. Fields read like a plain object, including "a.b" paths. Stored documents are
+ * read-only from the outside; find() returns copies (clone()) whose fields projection can remove.
+ * This module requires no other document or query module, which keeps the require graph acyclic.
+ */
 class documents
 {
     constructor(object)
@@ -9,24 +12,23 @@ class documents
         this._data = object;
         this._utils = new utils();
         this._cloned = false;
-        this._deleteReceiver = null;
 
         return new Proxy(this, {
-            deleteProperty: (target, prop, receiver) => {
-                if(target._cloned && target._deleteReceiver instanceof cursor)
+            deleteProperty: (target, prop) => {
+                if(target._cloned && prop in target._data)
                 {
-                    if(prop in target._data)
-                    {
-                        console.log('2', prop);
-                        delete target._data[prop];
-                        return true;
-                    }
-
-                    return false;
+                    delete target._data[prop];
+                    return true;
                 }
+
+                return false;
             },
 
             get: (target, prop) => {
+                // symbols (Symbol.toPrimitive, Symbol.iterator...) belong to the wrapper, not to the data
+                if(typeof prop !== 'string')
+                    return target[prop];
+
                 if(prop.indexOf('.') > -1)
                     return target._utils.getDotData(target._data, prop);
 
@@ -36,19 +38,15 @@ class documents
                 return target[prop];
             },
 
-            set: (target, prop, value, receiver) => {
-                if(!(prop in target._data) && !target.hasOwnProperty(prop))
-                    return false;
-
-                if(target.hasOwnProperty(prop) && ['_data', '_utils'].indexOf(prop) === -1){
-                    target[prop] = value;
+            set: (target, prop, value) => {
+                if(prop === '_cloned')
+                {
+                    target._cloned = value;
                     return true;
                 }
 
-                if(receiver instanceof manipulation || target._cloned && receiver instanceof cursor) {
-                    target._data[prop] = value;
-                    return true;
-                }
+                if(typeof prop === 'string' && prop in target._data)
+                    throw new Error(`Document fields are read-only ("${prop}"), change documents through the collection`);
 
                 return false;
             }
@@ -69,18 +67,16 @@ class documents
 
     /**
      * @method delete prop
-     * @description Delete a property from the document
+     * @description Delete a property from a copy returned by find() (used by projection)
      * @param string prop
-     * @param cursor receiver
      * @return boolean
      */
-    deleteProp(prop, receiver)
+    deleteProp(prop)
     {
-        this._deleteReceiver = receiver;
-        if(this._cloned)
-            return Reflect.deleteProperty(this, prop);
+        if(!this._cloned)
+            return false;
 
-        return false;
+        return Reflect.deleteProperty(this, prop);
     }
 }
 

package/src/query_language/manipulation.js

@@ -52,106 +52,143 @@ class manipulation {
     }
 
     /**
-     * Verify if exists some document that is not object
-     * @param array documents
+     * Whether a value is a document: an object that is not null nor an array
+     * @param mixed value
      * @return boolean
      */
-    _validateDocumentsType(documents)
+    _isDocument(value)
     {
-        const count = documents.reduce((acc, doc) => {
-            return typeof doc !== 'object' ? ++acc : acc;
-        }, 0);
-
-        return count;
+        return value !== null && typeof value === 'object' && !Array.isArray(value);
     }
 
     /**
-     * Verify if keys has prohibited characters
+     * Verify that no key, at any depth, has prohibited characters
      * @param object document
      * @return boolean
      */
     _validateKeys(document)
     {
-        const keys = Object.keys(document);
         const operators = new operatorsCheck();
-        for(let key of keys)
+        for(const key of Object.keys(document))
         {
-            const hasProhibitedCharacters = this._prohibitedCharacters.reduce((acc, char) => {
-                return key.indexOf(char) > -1 ? ++acc : acc;
-            }, 0);
-
-            if(hasProhibitedCharacters > 0 && !operators.isOperator(key))
+            const hasProhibitedCharacters = this._prohibitedCharacters.some(char => key.indexOf(char) > -1);
+            if(hasProhibitedCharacters && !operators.isOperator(key))
                 return false;
 
-            if(typeof document[key] === 'object')
-                return this._validateKeys(document[key]);
-
-            if(Array.isArray(document[key]))
+            const value = document[key];
+            const nested = Array.isArray(value) ? value : [value];
+            for(const item of nested)
             {
-                for(let value of document[key])
-                {
-                    if(typeof value === 'object')
-                        return this._validateKeys(value);
-                }
+                // null is a valid value, only objects have keys to check
+                if(item !== null && typeof item === 'object' && !this._validateKeys(item))
+                    return false;
             }
         }
 
         return true;
     }
 
+    /**
+     * Set of the _id values of the collection. It is rebuilt when its size no longer matches the
+     * documents, so removals done directly on the documents array are handled too.
+     * @return Set
+     */
+    _ids()
+    {
+        if(!this._idSet || this._idSet.size !== this._documents.length)
+            this._idSet = new Set(this._documents.map(doc => doc._data._id));
+
+        return this._idSet;
+    }
+
+    /**
+     * Copies a document, so the object given by the caller is never changed
+     * @param object document
+     * @return object
+     */
+    _copy(document)
+    {
+        try {
+            return structuredClone(document);
+        } catch(error) {
+            throw new Error('Documents can only contain cloneable values (no functions or DOM nodes)');
+        }
+    }
+
     /**
      * Inserts one document to the collection
      * @author Anderson Arruda < anderson@sysborg.com.br >
-     * @version 1.0.0
+     * @version 1.2.0
      * @param object document
-     * @param function callback - under construction
-     * @return void
+     * @param function callback - receives the inserted _id
+     * @return mixed the _id of the inserted document
     **/
     insertOne(document, callback) 
     {
-        if(typeof document !== 'object' || Array.isArray(document))
+        if(!this._isDocument(document))
             throw new Error('Invalid document type');
 
         if(!this._validateKeys(document))
             throw new Error('Invalid document keys');
 
-        if(typeof document._id === 'undefined')
+        const data = this._copy(document);
+        if(typeof data._id === 'undefined')
         {
-            let _idKey = '';
             do {
-                _idKey = this._generateKey();
-            } while(this._documents.find(doc => doc._id === document._id));
-
-            document._id = _idKey;
+                data._id = this._generateKey();
+            } while(this._ids().has(data._id));
+        }
+        else if(this._ids().has(data._id))
+        {
+            throw new Error(`Duplicate _id "${data._id}"`);
         }
 
-        if(!this._validate(document))
+        if(!this._validate(data))
             throw new Error('Invalid document');
 
-        this._documents.push(new documents(document));
+        this._documents.push(new documents(data));
+        this._ids().add(data._id);
 
         if(typeof callback === 'function')
-            callback();
+            callback(data._id);
+
+        return data._id;
     }
 
     /**
-     * Insert many documents
+     * Insert many documents. Every document is validated before the first one is inserted,
+     * so an invalid document never leaves the collection with only part of the batch.
      * @author Anderson Arruda < anderson@sysborg.com.br >
-     * @version 1.0.0
+     * @version 1.2.0
      * @param array documents 
-     * @param function callback 
-     * @return void
+     * @param function callback - receives the inserted ids
+     * @return array the _id of each inserted document
      */
     insertMany(documents, callback) {
-        console.info(this._validateDocumentsType(documents));
-        if(!Array.isArray(documents) || this._validateDocumentsType(documents) > 0)
+        if(!Array.isArray(documents) || !documents.every(document => this._isDocument(document)))
             throw new Error('Documents must be an array of objects');
 
-        for(let document of documents)
-            this.insertOne(document);
+        const given = new Set();
+        for(const document of documents)
+        {
+            if(!this._validateKeys(document))
+                throw new Error('Invalid document keys');
+
+            if(typeof document._id === 'undefined')
+                continue;
+
+            if(given.has(document._id) || this._ids().has(document._id))
+                throw new Error(`Duplicate _id "${document._id}"`);
+
+            given.add(document._id);
+        }
+
+        const ids = documents.map(document => this.insertOne(document));
 
         if(typeof callback === 'function')
-            callback();
+            callback(ids);
+
+        return ids;
     }
 
     //create index

package/src/utils.js

@@ -25,16 +25,17 @@ class utils
      */
     getDotData(data, field)
     {
-        let fields = field.split('.');
+        let value = data;
+        for(const part of field.split('.'))
+        {
+            // a missing step means the field does not exist (it used to return the parent object)
+            if(value === null || typeof value !== 'object' || !(part in value))
+                return undefined;
 
-        fields.forEach(field => {
-            if(typeof data[field] !== 'undefined')
-            {
-                data = data[field];
-            }
-        });
+            value = value[part];
+        }
 
-        return data;
+        return value;
     }
 }
 

package/Brainstorming.md

@@ -1,22 +0,0 @@
-For the first query version needs only to see if has some non logical operator or non logical comparison to resend to find as a recursive method.
-
-- Preparing sort of data using new capabilities
-- improving find behavior
-
-For comparison operators and deny operator like not
-adding nor https://www.mongodb.com/docs/manual/reference/operator/query/nor/
-
-https://www.mongodb.com/docs/manual/reference/operator/query-comparison/
-https://www.mongodb.com/docs/manual/reference/operator/query/expr/
-https://www.mongodb.com/docs/manual/reference/operator/query/regex/
-
-
-Preparing a bunch of misc tests to search data, add sort data and create test sortable data.
-
-//erros and improvements
-Bugs appears after resolving not, need to check and test why
-npm run test
-
-needs to improve projection to use cursor
-
-fix new bugs in test

package/debug-not.js

@@ -1,24 +0,0 @@
-const sorla = require('./src/sorla.js');
-const helper = require('./src/helper.js');
-
-const numberOfObjects = 20;
-const sdb = new sorla();
-sdb.createDb('test');
-sdb.useDb('test');
-
-sdb.db.createCollection('collection_test');
-
-const objects = helper.createFakeCollection(sdb, 'collection_test', numberOfObjects);
-const [itemIndex1, ] = helper.getRandomComparisonData(objects);
-
-const finded = sdb.db.collection_test.find({
-    uuid: {
-        $not: {
-            $eq: itemIndex1.uuid
-        }
-    }
- });
-
- console.log(finded.length, numberOfObjects);
-
-//console.log(finded);