montycat 1.0.2

package/README.md

@@ -0,0 +1,20 @@
+# Montycat Node.js Client
+
+Montycat Node.js Client is the official JavaScript/TypeScript client for **Montycat**, a high-performance, distributed NoSQL store built on cutting-edge Data Mesh architecture. This package enables Node.js developers to easily connect, query, and manage data within Montycat’s decentralized, scalable environment.
+
+## Key Features
+- ⚡ **High Performance**: Leverages Montycat’s architecture for extremely fast reads and writes.
+- 🏆 **Best of Both Worlds**: Combines the flexibility of NoSQL with familiar SQL-like features.
+- 💾 **In-Memory & Persistent Storage**: Choose between ultra-fast in-memory operations or durable persistent storage — or mix both.
+- 🗂️ **Data Mesh Design**: Supports decentralized data ownership, allowing teams to manage their own domains.
+- 🔄 **Asynchronous Operations**: Built for non-blocking I/O with async/await, perfect for real-time and high-concurrency workloads.
+- 🛡️ **Robust & Stable**: Utilizes Node.js’s networking stack (net module) for reliable connections and secure data handling.
+- 📊 **Smart Data Governance**: Integrates governance features to ensure data integrity and compliance.
+- 🤝 **Simple API**: Designed for easy integration into Node.js applications with minimal setup.
+- 📚 **Well-Documented**: Clear and comprehensive documentation to get you up and running fast.
+
+Installation
+You can install the Node.js client for Montycat using `npm`:
+
+```bash
+npm install montycat

package/dist/classes/generic.d.ts

@@ -0,0 +1,162 @@
+import { inspect } from 'util';
+/**
+ * GenericKV class that provides a base for key-value store operations.
+ * It includes methods for inserting, updating, retrieving, and deleting keys and values.
+ */
+declare class GenericKV {
+    static store: string;
+    static command: string;
+    static persistent: boolean;
+    static keyspace: string;
+    static username: string;
+    static password: string;
+    keyspace: string;
+    username: string;
+    password: string;
+    constructor(options: {
+        keyspace: string;
+        username: string;
+        password: string;
+    });
+    static [inspect.custom](): string;
+    static connectEngine(engine: any): void;
+    /**
+     * Get value from a store
+     * @param key - The key for the value to retrieve.
+     * @param customKey - The custom key for the value to retrieve.
+     * @param withPointers - Whether to include pointers in the retrieved value.
+     * @return A promise that resolves with the retrieved value.
+     */
+    static getValue({ key, customKey, withPointers }?: {
+        key?: string;
+        customKey?: string | null;
+        withPointers?: boolean;
+    }): Promise<any>;
+    /**
+     * List all depending keys for a given key or custom key.
+     * @param key - The key for which to list depending keys.
+     * @param customKey - The custom key for which to list depending keys.
+     * @returns A promise that resolves with the list of depending keys.
+     * */
+    static listAllDependingKeys({ key, customKey }?: {
+        key?: string;
+        customKey?: string | null;
+    }): Promise<any>;
+    static listAllSchemasInKeyspace(): Promise<any>;
+    /**
+     * Deletes a key from the keyspace.
+     * @param key - The key to delete.
+     * @param customKey - The custom key to delete.
+     * @return A promise that resolves with the result of the deletion.
+     * */
+    static deleteKey({ key, customKey }?: {
+        key?: string;
+        customKey?: string | null;
+    }): Promise<any>;
+    /**
+     * Deletes a bulk of keys from the keyspace.
+     * @param bulkKeys - An array of keys to delete.
+     * @param bulkCustomKeys - An array of custom keys to delete.
+     * @return A promise that resolves with the result of the deletion.
+     * */
+    static deleteBulk({ bulkKeys, bulkCustomKeys }?: {
+        bulkKeys?: string[];
+        bulkCustomKeys?: string[];
+    }): Promise<any>;
+    /**
+     * Gets bulk values from the keyspace.
+     * @param bulkKeys - An array of keys to retrieve.
+     * @param bulkCustomKeys - An array of custom keys to retrieve.
+     * @param limitOutput - An object specifying the start and stop indices for limiting output.
+     * @param withPointers - Whether to include pointers in the retrieved values.
+     * @returns A promise that resolves with the retrieved keys.
+     */
+    static getBulk({ bulkKeys, bulkCustomKeys, limitOutput, withPointers }?: {
+        bulkKeys?: string[];
+        bulkCustomKeys?: string[];
+        limitOutput?: {
+            start: number;
+            stop: number;
+        };
+        withPointers?: boolean;
+    }): Promise<any>;
+    /**
+     * Updates a bulk of keys and values in the keyspace.
+     * @param bulkKeysValues - An object where keys are the keys to update and values are the new values.
+     * @param bulkCustomKeysValues - An object where custom keys are the keys to update and values are the new values.
+     * @return A promise that resolves with the result of the update.
+     */
+    static updateBulk({ bulkKeysValues, bulkCustomKeysValues }?: {
+        bulkKeysValues?: {
+            [key: string]: any;
+        };
+        bulkCustomKeysValues?: {
+            [key: string]: any;
+        };
+    }): Promise<any>;
+    /**
+     * Looks up keys based on search criteria.
+     * @param searchCriteria - An object containing the search criteria.
+     * @param limitOutput - An object specifying the start and stop indices for limiting output.
+     * @param schema - The schema to use for the lookup.
+     * @returns A promise that resolves with the result of the lookup.
+     */
+    static lookupKeysWhere({ searchCriteria, limitOutput, schema }?: {
+        searchCriteria?: {
+            [key: string]: any;
+        };
+        limitOutput?: {
+            start: number;
+            stop: number;
+        };
+        schema?: any;
+    }): Promise<any>;
+    /**
+     * Looks up values based on search criteria.
+     * @param searchCriteria - An object containing the search criteria.
+     * @param limitOutput - An object specifying the start and stop indices for limiting output.
+     * @param withPointers - Whether to include pointers in the retrieved values.
+     * @param schema - The schema to use for the lookup.
+     * @return A promise that resolves with the result of the lookup.
+     */
+    static lookupValuesWhere({ searchCriteria, limitOutput, withPointers, schema }?: {
+        searchCriteria?: {
+            [key: string]: any;
+        };
+        limitOutput?: {
+            start: number;
+            stop: number;
+        };
+        withPointers?: boolean;
+        schema?: any;
+    }): Promise<any>;
+    /**
+     * Gets the length of the keyspace.
+     * @returns A promise that resolves with the length of the keyspace.
+     */
+    static getLen(): Promise<any>;
+    /**
+     * Removes the keyspace from the store.
+     * @returns A promise that resolves with the result of the keyspace removal.
+     * */
+    static removeKeyspace(): Promise<any>;
+    /**
+     * Enforces a schema on the store.
+     * @param schema - The schema to enforce. Should be an instance of the Schema class.
+     * @throws TypeError if the schema is not an instance of Schema.
+     * @returns A promise that resolves with the result of the schema enforcement.
+     */
+    static enforceSchema(schema: any): Promise<any>;
+    /**
+     * Removes an enforced schema from the store.
+     * @param schema - The name of the schema to remove.
+     * @returns A promise that resolves with the result of the schema removal.
+     */
+    static removeEnforcedSchema(schema: any): Promise<any>;
+    /**
+     * Shows the properties of the store.
+     * @returns The current instance of GenericKV.
+     */
+    showStoreProperties(): this;
+}
+export default GenericKV;

package/dist/classes/generic.js

@@ -0,0 +1,274 @@
+import { convertCustomKey, convertCustomKeys, convertCustomKeysValues, convertToBinaryQuery, runQuery, } from '../functions/storeGenericFunctions.js';
+import { inspect } from 'util';
+/**
+ * GenericKV class that provides a base for key-value store operations.
+ * It includes methods for inserting, updating, retrieving, and deleting keys and values.
+ */
+class GenericKV {
+    static store = "";
+    static command = "";
+    static persistent = false;
+    static keyspace;
+    static username;
+    static password;
+    keyspace;
+    username;
+    password;
+    constructor(options) {
+        this.keyspace = options.keyspace;
+        this.username = options.username;
+        this.password = options.password;
+    }
+    static [inspect.custom]() {
+        return this.name;
+    }
+    static connectEngine(engine) {
+        Object.assign(this, engine);
+    }
+    /**
+     * Get value from a store
+     * @param key - The key for the value to retrieve.
+     * @param customKey - The custom key for the value to retrieve.
+     * @param withPointers - Whether to include pointers in the retrieved value.
+     * @return A promise that resolves with the retrieved value.
+     */
+    static async getValue({ key = "", customKey = null, withPointers = false } = {}) {
+        try {
+            if (customKey)
+                key = convertCustomKey(customKey);
+            if (!key) {
+                throw new Error("No key provided");
+            }
+            this.command = "get_value";
+            const query = convertToBinaryQuery(this, { key, withPointers });
+            return runQuery(this, query);
+        }
+        catch (err) {
+            throw err;
+        }
+    }
+    /**
+     * List all depending keys for a given key or custom key.
+     * @param key - The key for which to list depending keys.
+     * @param customKey - The custom key for which to list depending keys.
+     * @returns A promise that resolves with the list of depending keys.
+     * */
+    static async listAllDependingKeys({ key = "", customKey = null } = {}) {
+        try {
+            if (customKey)
+                key = convertCustomKey(customKey);
+            if (!key) {
+                throw new Error("No key provided");
+            }
+            this.command = "list_all_depending_keys";
+            const query = convertToBinaryQuery(this, { key });
+            return runQuery(this, query);
+        }
+        catch (err) {
+            throw err;
+        }
+    }
+    static async listAllSchemasInKeyspace() {
+        this.command = "list_all_schemas_in_keyspace";
+        const query = convertToBinaryQuery(this, {});
+        return runQuery(this, query);
+    }
+    /**
+     * Deletes a key from the keyspace.
+     * @param key - The key to delete.
+     * @param customKey - The custom key to delete.
+     * @return A promise that resolves with the result of the deletion.
+     * */
+    static async deleteKey({ key = "", customKey = null } = {}) {
+        try {
+            if (customKey)
+                key = convertCustomKey(customKey);
+            if (!key) {
+                throw new Error("No key provided");
+            }
+            this.command = "delete_key";
+            const query = convertToBinaryQuery(this, { key });
+            return runQuery(this, query);
+        }
+        catch (err) {
+            throw err;
+        }
+    }
+    /**
+     * Deletes a bulk of keys from the keyspace.
+     * @param bulkKeys - An array of keys to delete.
+     * @param bulkCustomKeys - An array of custom keys to delete.
+     * @return A promise that resolves with the result of the deletion.
+     * */
+    static async deleteBulk({ bulkKeys = [], bulkCustomKeys = [] } = {}) {
+        try {
+            if (bulkCustomKeys.length)
+                bulkKeys = bulkKeys.concat(convertCustomKeys(bulkCustomKeys));
+            if (!bulkKeys || bulkKeys.length === 0) {
+                throw new Error("No keys provided");
+            }
+            this.command = "delete_bulk";
+            const query = convertToBinaryQuery(this, { bulkKeys });
+            return runQuery(this, query);
+        }
+        catch (err) {
+            throw err;
+        }
+    }
+    /**
+     * Gets bulk values from the keyspace.
+     * @param bulkKeys - An array of keys to retrieve.
+     * @param bulkCustomKeys - An array of custom keys to retrieve.
+     * @param limitOutput - An object specifying the start and stop indices for limiting output.
+     * @param withPointers - Whether to include pointers in the retrieved values.
+     * @returns A promise that resolves with the retrieved keys.
+     */
+    static async getBulk({ bulkKeys = [], bulkCustomKeys = [], limitOutput = { start: 0, stop: 0 }, withPointers = false } = {}) {
+        try {
+            if (bulkCustomKeys.length)
+                bulkKeys = bulkKeys.concat(convertCustomKeys(bulkCustomKeys));
+            if (!bulkKeys || bulkKeys.length === 0) {
+                throw new Error("No keys provided");
+            }
+            this.command = "get_bulk";
+            const query = convertToBinaryQuery(this, { bulkKeys, limitOutput, withPointers });
+            return runQuery(this, query);
+        }
+        catch (err) {
+            throw err;
+        }
+    }
+    /**
+     * Updates a bulk of keys and values in the keyspace.
+     * @param bulkKeysValues - An object where keys are the keys to update and values are the new values.
+     * @param bulkCustomKeysValues - An object where custom keys are the keys to update and values are the new values.
+     * @return A promise that resolves with the result of the update.
+     */
+    static async updateBulk({ bulkKeysValues = {}, bulkCustomKeysValues = {} } = {}) {
+        try {
+            if (Object.keys(bulkCustomKeysValues).length) {
+                bulkKeysValues = { ...bulkKeysValues, ...convertCustomKeysValues(bulkCustomKeysValues) };
+            }
+            if (Object.keys(bulkKeysValues).length === 0) {
+                throw new Error("No keys provided");
+            }
+            this.command = "update_bulk";
+            const query = convertToBinaryQuery(this, { bulkKeysValues });
+            return runQuery(this, query);
+        }
+        catch (err) {
+            throw err;
+        }
+    }
+    /**
+     * Looks up keys based on search criteria.
+     * @param searchCriteria - An object containing the search criteria.
+     * @param limitOutput - An object specifying the start and stop indices for limiting output.
+     * @param schema - The schema to use for the lookup.
+     * @returns A promise that resolves with the result of the lookup.
+     */
+    static async lookupKeysWhere({ searchCriteria = {}, limitOutput = { start: 0, stop: 0 }, schema = null } = {}) {
+        try {
+            this.command = "lookup_keys";
+            const query = convertToBinaryQuery(this, { searchCriteria, limitOutput, schema });
+            return runQuery(this, query);
+        }
+        catch (err) {
+            throw err;
+        }
+    }
+    /**
+     * Looks up values based on search criteria.
+     * @param searchCriteria - An object containing the search criteria.
+     * @param limitOutput - An object specifying the start and stop indices for limiting output.
+     * @param withPointers - Whether to include pointers in the retrieved values.
+     * @param schema - The schema to use for the lookup.
+     * @return A promise that resolves with the result of the lookup.
+     */
+    static async lookupValuesWhere({ searchCriteria = {}, limitOutput = { start: 0, stop: 0 }, withPointers = false, schema = null } = {}) {
+        try {
+            this.command = "lookup_values";
+            const query = convertToBinaryQuery(this, { searchCriteria, limitOutput, withPointers, schema });
+            return runQuery(this, query);
+        }
+        catch (err) {
+            throw err;
+        }
+    }
+    /**
+     * Gets the length of the keyspace.
+     * @returns A promise that resolves with the length of the keyspace.
+     */
+    static async getLen() {
+        this.command = "get_len";
+        const query = convertToBinaryQuery(this, {});
+        return runQuery(this, query);
+    }
+    /**
+     * Removes the keyspace from the store.
+     * @returns A promise that resolves with the result of the keyspace removal.
+     * */
+    static async removeKeyspace() {
+        const query = {
+            raw: ["remove-keyspace", "store", this.store, "keyspace", this.keyspace],
+            credentials: [this.username, this.password],
+        };
+        return await runQuery(this, JSON.stringify(query));
+    }
+    // how to make it available for TS only ?
+    /**
+     * Enforces a schema on the store.
+     * @param schema - The schema to enforce. Should be an instance of the Schema class.
+     * @throws TypeError if the schema is not an instance of Schema.
+     * @returns A promise that resolves with the result of the schema enforcement.
+     */
+    static async enforceSchema(schema) {
+        function parseType(fieldType) {
+            switch (fieldType) {
+                case "String": return "String";
+                case "Number": return "Number";
+                case "Boolean": return "Boolean";
+                case "Array": return "Array";
+                case "Object": return "Object";
+                case "Pointer": return "Pointer";
+                case "Timestamp": return "Timestamp";
+                default: throw new TypeError(`Unsupported field type: ${fieldType}`);
+            }
+        }
+        let schemaTypes = {};
+        if (!schema.metadata) {
+            throw new TypeError("Schema must have metadata");
+        }
+        for (const [field, fieldType] of Object.entries(schema.metadata)) {
+            schemaTypes[field] = parseType(fieldType);
+        }
+        const query = {
+            raw: ["enforce-schema", "store", this.store, "keyspace", this.keyspace, "persistent", this.persistent ? "y" : "n", "schema_name", schema.name, "schema_content", `${JSON.stringify(schemaTypes)}`],
+            credentials: [this.username, this.password],
+        };
+        return await runQuery(this, JSON.stringify(query));
+    }
+    /**
+     * Removes an enforced schema from the store.
+     * @param schema - The name of the schema to remove.
+     * @returns A promise that resolves with the result of the schema removal.
+     */
+    static async removeEnforcedSchema(schema) {
+        if (!schema) {
+            throw new TypeError("Schema must be provided");
+        }
+        const query = {
+            raw: ["remove-enforced-schema", "store", this.store, "keyspace", this.keyspace, "persistent", this.persistent ? "y" : "n", "schema_name", schema.name],
+            credentials: [this.username, this.password],
+        };
+        return await runQuery(this, JSON.stringify(query));
+    }
+    /**
+     * Shows the properties of the store.
+     * @returns The current instance of GenericKV.
+     */
+    showStoreProperties() {
+        return this;
+    }
+}
+export default GenericKV;

package/dist/core/engine.d.ts

@@ -0,0 +1,113 @@
+import GenericKV from '../classes/generic.js';
+/** * Interface for engine configuration options.
+ * @interface
+ * */
+interface EngineConfig {
+    host?: string | null;
+    port?: number | null;
+    username?: string | null;
+    password?: string | null;
+    store?: string | null;
+}
+/** * Enum for valid permissions.
+ * @enum
+ * */
+declare enum ValidPermissions {
+    READ = "read",
+    WRITE = "write",
+    ALL = "all"
+}
+/**
+ * Represents the configuration and connection details for a communication engine.
+ * This class allows you to connect to a MontyCat server and perform operations such as creating stores, managing owners, and granting/revoking permissions.
+ * @class
+ * @param {EngineConfig} config - The configuration for the engine, including host, port, username, password, and store.
+ * @example
+ *
+ *  const engine = new Engine({
+ *    host: 'localhost',
+ *    port: 3000,
+ *    username: 'admin',
+ *    password: 'admin',
+ *    store: 'test_store',
+ *  });
+ *
+ */
+declare class Engine {
+    private host;
+    private port;
+    private username;
+    private password;
+    private store;
+    constructor({ host, port, username, password, store }?: EngineConfig);
+    /**
+     * Creates an Engine instance from a URI string in the format:
+     * montycat://host/port/username/password[/store]
+     */
+    static fromUri(uri: string): Engine;
+    /**
+     * Creates a store with the specified persistence option.
+     * @param {Object} options - Options for creating the store.
+     * @param {boolean} [options.persistent=false] - Whether to create a persistent store.
+     * @returns {Promise<unknown>} A promise that resolves with the result of the store creation.
+     */
+    createStore({ persistent }?: {
+        persistent?: boolean;
+    }): Promise<unknown>;
+    /**
+     * Removes a store with the specified persistence option.
+     * @param {Object} options - Options for removing the store.
+     * @param {boolean} [options.persistent=false] - Whether to remove a persistent store.
+     * @returns {Promise<unknown>} A promise that resolves with the result of the store removal.
+     */
+    removeStore({ persistent }?: {
+        persistent?: boolean;
+    }): Promise<unknown>;
+    /**
+     * Creates an owner with the specified username and password.
+     * @param {string} owner - The username of the owner to create.
+     * @param {string} password - The password for the owner.
+     * @returns {Promise<unknown>} A promise that resolves with the result of the owner creation.
+     */
+    createOwner(owner: string, password: string): Promise<unknown>;
+    removeOwner(owner: string): Promise<unknown>;
+    /**
+     * Lists all owners in the store.
+     * @returns {Promise<unknown>} A promise that resolves with the list of owners.
+     */
+    listOwners(): Promise<unknown>;
+    /**
+     * Grants a permission to an owner for specified keyspaces.
+     * @param {string} owner - The username of the owner to grant permission to.
+     * @param {ValidPermissions} permission - The permission to grant (read, write, all).
+     * @param {string | GenericKV[] | string[] | { keyspace: string }} [keyspaces] - The keyspaces to grant permission for.
+     * @returns {Promise<unknown>} A promise that resolves with the result of the grant operation.
+     */
+    grantTo(owner: string, permission: ValidPermissions, keyspaces?: string | GenericKV[] | string[] | {
+        keyspace: string;
+    }): Promise<unknown>;
+    /**
+     * Revokes a permission from an owner for specified keyspaces.
+     * @param {string} owner - The username of the owner to revoke permission from.
+     * @param {ValidPermissions} permission - The permission to revoke (read, write, all).
+     * @param {string | GenericKV[] | string[] | { keyspace: string }} [keyspaces] - The keyspaces to revoke permission for.
+     * @returns {Promise<unknown>} A promise that resolves with the result of the revoke operation.
+     */
+    revokeFrom(owner: string, permission: ValidPermissions, keyspaces?: string | string[] | GenericKV[] | {
+        keyspace: string;
+    }): Promise<unknown>;
+    /**
+     * Retrieves the structure of the store.
+     * @returns {Promise<unknown>} A promise that resolves with the structure of the store
+     * */
+    getStructureAvailable(): Promise<unknown>;
+}
+/**
+ * Sends a string to the specified host and port, and returns the parsed response.
+ * @param {string} host - The host to connect to.
+ * @param {number} port - The port to connect to.
+ * @param {string} string - The string to send.
+ * @returns {Promise<unknown>} A promise that resolves with the parsed response.
+ */
+declare function sendData(host: string, port: number, string: string): Promise<unknown>;
+export { Engine, EngineConfig, sendData, ValidPermissions };