sorla-db 1.1.0 → 1.3.0

package/index.d.ts

@@ -0,0 +1,157 @@
+// 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[];
+    $exists?: boolean;
+    $regex?: string | RegExp;
+    /** Flags for $regex: i, m, s */
+    $options?: string;
+    $not?: ComparisonOperators | RegExp;
+};
+
+/** 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;
+};
+
+/** Exclusion ({ email: 0 }) or inclusion ({ name: 1 }); only _id can mix both. */
+export type Projection = Record<string, 0 | 1>;
+
+export type UpdateFilter = {
+    $set?: Record<string, unknown>;
+    $unset?: Record<string, unknown>;
+    $inc?: Record<string, number>;
+    $push?: Record<string, unknown | { $each: unknown[] }>;
+    $pull?: Record<string, unknown>;
+};
+
+export interface UpdateOptions {
+    /** Insert a document built from the filter when nothing matches. */
+    upsert?: boolean;
+}
+
+export interface UpdateResult {
+    matchedCount: number;
+    modifiedCount: number;
+    upsertedId: unknown | null;
+}
+
+export interface DeleteResult {
+    deletedCount: number;
+}
+
+export type ChangeType = 'insert' | 'update' | 'replace' | 'delete';
+
+export interface ChangeEvent {
+    type: ChangeType;
+    ids: unknown[];
+    /** Copies of the documents (after the change; the removed ones for delete). */
+    documents: Document[];
+    /** Copies of the documents before an update or replace. */
+    previous?: Document[];
+}
+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;
+    skip(count: number): this;
+    /** 0 means no limit. */
+    limit(count: number): this;
+    projection(projection: Projection): this;
+    push(element: object): void;
+}
+
+export declare class Collection {
+    readonly first: Document;
+    readonly last: Document;
+    readonly all: StoredDocument[];
+    /** All documents, or the ones matching the query. */
+    count(query?: Query): 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;
+    updateOne(filter: Query, update: UpdateFilter, options?: UpdateOptions): UpdateResult;
+    updateMany(filter: Query, update: UpdateFilter, options?: UpdateOptions): UpdateResult;
+    /** Replaces the document, keeping its _id. */
+    replaceOne(filter: Query, replacement: Document, options?: UpdateOptions): UpdateResult;
+    deleteOne(filter: Query): DeleteResult;
+    /** deleteMany({}) empties the collection. */
+    deleteMany(filter: Query): DeleteResult;
+    /** Returns a function that unsubscribes. "change" receives every type. */
+    on(event: ChangeType | 'change', listener: (event: ChangeEvent) => void): () => void;
+    once(event: ChangeType | 'change', listener: (event: ChangeEvent) => void): () => void;
+    off(event: ChangeType | 'change', listener?: (event: ChangeEvent) => void): void;
+}
+
+export interface DatabaseStats {
+    name: string;
+    documents: number;
+    collections: Array<{ name: string; documents: number }>;
+}
+
+export declare class Database {
+    readonly name: string;
+    createCollection(name: string, validationSchema?: unknown): void;
+    countCollections(): number;
+    listCollections(): string[];
+    /** Any collection by name, also when the name shadows a method. */
+    getCollection(name: string): Collection | undefined;
+    dropCollection(name: string): boolean;
+    getStats(): DatabaseStats;
+    [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;
+    listDatabases(): string[];
+    /** When the dropped database was selected, db becomes null. */
+    dropDb(name: string): boolean;
+}
+
+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.3.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/dbs/database.js

@@ -67,6 +67,54 @@ class database
     {
         return this._collectionCount;
     }
+
+    /**
+     * Names of the collections, in creation order
+     * @return array
+     */
+    listCollections()
+    {
+        return Object.keys(this._collections);
+    }
+
+    /**
+     * A collection by name, also when the name is not a valid property (or shadows a method)
+     * @param string name
+     * @return collection|undefined
+     */
+    getCollection(name)
+    {
+        return this._collections.hasOwnProperty(name) ? this._collections[name] : undefined;
+    }
+
+    /**
+     * Removes a collection and its documents
+     * @param string name
+     * @return boolean false when it did not exist
+     */
+    dropCollection(name)
+    {
+        if(!this._collections.hasOwnProperty(name))
+            return false;
+
+        delete this._collections[name];
+        this._collectionCount--;
+        return true;
+    }
+
+    /**
+     * Number of documents per collection
+     * @return object {name, documents, collections: [{name, documents}]}
+     */
+    getStats()
+    {
+        const collections = this.listCollections().map(name => ({ name, documents: this._collections[name].count() }));
+        return {
+            name: this._name,
+            documents: collections.reduce((total, item) => total + item.documents, 0),
+            collections
+        };
+    }
 }
 
 module.exports = database;

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;
     }
 
     /**
@@ -108,23 +123,75 @@ class cursor {
     }
 
     /**
-     * Projection of the cursor
+     * Projection of the cursor, like MongoDB:
+     *   {email: 0}           every field except email
+     *   {name: 1, age: 1}    only name and age, plus _id unless {_id: 0}
+     * Inclusion and exclusion cannot be mixed, except for _id. Top level fields only.
      * @param json projection
      * @return cursor
      */
     projection(projection) {
         if(projection === null || typeof projection !== 'object')
-            return;
+            return this;
+
+        const fields = Object.keys(projection);
+        for(const field of fields)
+        {
+            if(projection[field] !== 0 && projection[field] !== 1)
+                throw new Error(`Projection of "${field}" must be 0 or 1`);
+
+            if(field.includes('.'))
+                throw new Error(`Projection supports top level fields only ("${field}")`);
+        }
+
+        const included = fields.filter(field => projection[field] === 1 && field !== '_id');
+        const excluded = fields.filter(field => projection[field] === 0 && field !== '_id');
+        if(included.length && excluded.length)
+            throw new Error('Projection cannot mix inclusion and exclusion (except for _id)');
+
+        const keep = new Set(included);
+        if(projection._id !== 0) keep.add('_id');
 
-        const self = this;
         this._data.forEach(doc => {
-            for(const attribute of Object.keys(projection))
-            {
-                if(projection[attribute] === 0) {
-                    doc.deleteProp(attribute, self);
-                }
-            }
+            const remove = included.length
+                ? Object.keys(doc._data).filter(field => !keep.has(field))
+                : [...excluded, ...(projection._id === 0 ? ['_id'] : [])];
+
+            for(const field of remove)
+                doc.deleteProp(field);
         });
+
+        return this;
+    }
+
+    /**
+     * Skips the first documents (apply after sort, like MongoDB applies it)
+     * @param int count
+     * @return cursor
+     */
+    skip(count) {
+        if(!Number.isInteger(count) || count < 0)
+            throw new Error('skip() needs a non negative integer');
+
+        this._data = this._data.slice(count);
+        this.currIndex = 0;
+        return this;
+    }
+
+    /**
+     * Keeps at most `count` documents; 0 means no limit, like MongoDB
+     * @param int count
+     * @return cursor
+     */
+    limit(count) {
+        if(!Number.isInteger(count) || count < 0)
+            throw new Error('limit() needs a non negative integer');
+
+        if(count > 0)
+            this._data = this._data.slice(0, count);
+
+        this.currIndex = 0;
+        return this;
     }
 
     /**
@@ -141,4 +208,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/events.js

@@ -0,0 +1,69 @@
+/**
+ * Minimal event emitter for collections: insert, update, replace, delete and change (all of them).
+ * A failing listener never breaks the write that triggered it; its error is rethrown asynchronously.
+ */
+class emitter
+{
+    constructor()
+    {
+        this._listeners = new Map();
+    }
+
+    /**
+     * @param string event
+     * @param function listener receives the event payload
+     * @return function unsubscribe
+     */
+    on(event, listener)
+    {
+        if(typeof listener !== 'function')
+            throw new Error('The listener must be a function');
+
+        if(!this._listeners.has(event))
+            this._listeners.set(event, new Set());
+
+        this._listeners.get(event).add(listener);
+        return () => this.off(event, listener);
+    }
+
+    once(event, listener)
+    {
+        const off = this.on(event, payload => {
+            off();
+            listener(payload);
+        });
+        return off;
+    }
+
+    off(event, listener)
+    {
+        if(typeof listener === 'undefined')
+            this._listeners.delete(event);
+        else
+            this._listeners.get(event)?.delete(listener);
+    }
+
+    /**
+     * Emits the event and a generic "change" event with the same payload plus its type
+     * @param string type
+     * @param object payload
+     * @return void
+     */
+    _emitChange(type, payload)
+    {
+        const event = { type, ...payload };
+        for(const name of [type, 'change'])
+        {
+            for(const listener of [...(this._listeners.get(name) ?? [])])
+            {
+                try {
+                    listener(event);
+                } catch(error) {
+                    setTimeout(() => { throw error; });
+                }
+            }
+        }
+    }
+}
+
+module.exports = emitter;