montycat 1.0.2

package/dist/core/persistent.js

@@ -0,0 +1,136 @@
+import { runQuery, convertToBinaryQuery, convertCustomKey } from '../functions/storeGenericFunctions.js';
+import GenericKV from '../classes/generic.js';
+/**
+ * Persistent class that extends GenericKV for persistent keyspace operations.
+ * It provides methods for inserting, updating, and retrieving data in a persistent store.
+ */
+class Persistent extends GenericKV {
+    static persistent = true;
+    static distributed = false;
+    static cache = null;
+    static compression = false;
+    keyspace;
+    constructor(options) {
+        super(options);
+        this.keyspace = options.keyspace;
+    }
+    /**
+     * Inserts a value into the persistent store.
+     * @param value - The value to insert.
+     * @return A promise that resolves with the result of the insertion.
+     */
+    static async insertValue({ value = {} } = {}) {
+        this.command = "insert_value";
+        const query = convertToBinaryQuery(this, { value });
+        return runQuery(this, query);
+    }
+    /**
+     * Inserts a key-value pair into the persistent store.
+     * @param key - The key for the value.
+     * @param value - The value to insert.
+     * @return A promise that resolves with the result of the insertion.
+     */
+    static async insertCustomKey({ customKey }) {
+        if (!customKey) {
+            throw new Error("No key provided");
+        }
+        this.command = "insert_custom_key";
+        const query = convertToBinaryQuery(this, { key: convertCustomKey(customKey) });
+        return runQuery(this, query);
+    }
+    /**
+     * Inserts a custom key-value pair into the persistent store.
+     * @param customKey - The custom key for the value.
+     * @param value - The value to insert.
+     * @return A promise that resolves with the result of the insertion.
+     */
+    static async insertCustomKeyValue({ customKey, value = {} }) {
+        if (!customKey) {
+            throw new Error("No key provided");
+        }
+        this.command = "insert_custom_key_value";
+        const query = convertToBinaryQuery(this, { key: convertCustomKey(customKey), value });
+        return runQuery(this, query);
+    }
+    /**
+     * Updates a value in the persistent store.
+     * @param key - The key for the value to update.
+     * @param customKey - The custom key for the value to update.
+     * @param value - The new value to set.
+     * @return A promise that resolves with the result of the update.
+     */
+    static async updateValue({ key = "", customKey = null, value = {} } = {}) {
+        const effectiveKey = customKey ? convertCustomKey(customKey) : key;
+        if (!effectiveKey) {
+            throw new Error("No key provided");
+        }
+        this.command = "update_value";
+        const query = convertToBinaryQuery(this, { key: effectiveKey, value });
+        return runQuery(this, query);
+    }
+    /**
+     * Retrieves a value from the persistent store.
+     * @param key - The key for the value to retrieve.
+     * @param customKey - The custom key for the value to retrieve.
+     * @return A promise that resolves with the retrieved value.
+     */
+    static async insertBulk({ bulk = [] } = {}) {
+        if (!bulk || bulk.length === 0) {
+            throw new Error("No values provided");
+        }
+        this.command = "insert_bulk";
+        const query = convertToBinaryQuery(this, { bulkValues: bulk });
+        return runQuery(this, query);
+    }
+    /**
+     * Retrieves a value from the persistent store.
+     * @param key - The key for the value to retrieve.
+     * @param customKey - The custom key for the value to retrieve.
+     * @return A promise that resolves with the retrieved value.
+     */
+    static async getKeys({ limitOutput = { start: 0, stop: 0 } } = {}) {
+        this.command = "get_keys";
+        const query = convertToBinaryQuery(this, { limitOutput });
+        return runQuery(this, query);
+    }
+    /**
+     * Updates the cache and compression settings for the persistent store.
+     * @param cache - The cache settings to apply.
+     * @param compression - Whether to enable compression.
+     * @return A promise that resolves with the result of the update.
+     */
+    static async updateCacheAndCompression() {
+        const query = {
+            raw: [
+                "update-cache-compression", "store", this.store, "keyspace", this.keyspace, "persistent", "y",
+                "cache", this.cache ? this.cache : null, "compression", this.compression ? "y" : "n"
+            ],
+            credentials: [this.username, this.password],
+        };
+        return await runQuery(this, JSON.stringify(query));
+    }
+    /**
+     * Creates a keyspace in the persistent store.
+     * @return A promise that resolves with the result of the keyspace creation.
+     */
+    static async createKeyspace() {
+        const query = {
+            raw: [
+                "create-keyspace", "store", this.store, "keyspace", this.keyspace, "persistent", this.persistent ? "y" : "n",
+                "cache", this.cache ? this.cache : null, "compression", this.compression ? "y" : "n"
+            ],
+            credentials: [this.username, this.password],
+        };
+        return await runQuery(this, JSON.stringify(query));
+    }
+}
+;
+/**
+ * PersistentDistributed class that extends Persistent for distributed persistent keyspace operations.
+ * It provides methods for distributed operations in a persistent store.
+ */
+class PersistentDistributed extends Persistent {
+    static distributed = true;
+}
+;
+export { Persistent, PersistentDistributed };

package/dist/core/schema.d.ts

@@ -0,0 +1,93 @@
+import GenericKV from '../classes/generic.js';
+/** * Interface for schema properties
+ * @interface
+ */
+/** * Interface for pointer configuration
+ * @interface
+ */
+interface PointerConfig {
+    keyspace: {
+        keyspace: string;
+    } | GenericKV;
+    key?: string | number;
+    customKey?: string;
+}
+/** * Interface for timestamp configuration
+ * @interface
+ */
+interface TimestampConfig {
+    timestamp: string;
+}
+/** * Interface for timestamp range configuration
+ * @interface
+ */
+interface TimestampRangeConfig {
+    startTimestamp: string;
+    endTimestamp: string;
+}
+/**
+ * Schema class
+ * @class
+ * @param properties - The properties of the schema
+ * @property {Record<string, string>} metadata - The metadata object containing field types
+ * @returns The schema object
+ * @example
+ * const schema = new Schema({ username: 'user', location: 'city' });
+ *
+ * Metadata is used to define the types of properties to enforce in the schema.
+ * Types can be 'String', 'Number', 'Pointer', 'Timestamp', "Object", "Array".
+ *
+ * @throws {Error} If a required property is missing or not defined
+ * @throws {Error} If a property is not defined in the schema
+ * @throws {Error} If a pointer is not valid (missing keyspace or key)
+ */
+declare class Schema {
+    [key: string]: any;
+    static metadata: Record<string, string> | null;
+    constructor(properties: {
+        [key: string]: any;
+    });
+    validate(): void;
+    get className(): string;
+    serialize(): Schema;
+}
+/**
+ * Pointer class
+ * @class
+ * @param config - The pointer configuration
+ * @returns The pointer object
+ */
+declare class Pointer {
+    private key?;
+    private keyspace;
+    constructor({ keyspace, key, customKey }: PointerConfig);
+    setupPointer(): [string, string];
+}
+/**
+ * Timestamp class
+ * @class
+ * @param timestamp - The timestamp object
+ * @returns The timestamp object
+ * @example
+ * const timestamp = new Timestamp({ timestamp: Date.now() });
+ */
+declare class Timestamp {
+    timestamp: string;
+    constructor({ timestamp }: TimestampConfig);
+    static after: {
+        new (after: number | string): {
+            after_timestamp: number | string;
+        };
+    };
+    static before: {
+        new (before: number | string): {
+            before_timestamp: number | string;
+        };
+    };
+    static range: {
+        new ({ startTimestamp, endTimestamp }: TimestampRangeConfig): {
+            range_timestamp: [number | string, number | string];
+        };
+    };
+}
+export { Schema, Pointer, Timestamp };

package/dist/core/schema.js

@@ -0,0 +1,113 @@
+import { convertCustomKey } from '../functions/storeGenericFunctions.js';
+/**
+ * Schema class
+ * @class
+ * @param properties - The properties of the schema
+ * @property {Record<string, string>} metadata - The metadata object containing field types
+ * @returns The schema object
+ * @example
+ * const schema = new Schema({ username: 'user', location: 'city' });
+ *
+ * Metadata is used to define the types of properties to enforce in the schema.
+ * Types can be 'String', 'Number', 'Pointer', 'Timestamp', "Object", "Array".
+ *
+ * @throws {Error} If a required property is missing or not defined
+ * @throws {Error} If a property is not defined in the schema
+ * @throws {Error} If a pointer is not valid (missing keyspace or key)
+ */
+class Schema {
+    static metadata = null;
+    // how to check metadata type?
+    constructor(properties) {
+        Object.assign(this, properties);
+    }
+    validate() {
+        Object.keys(this).forEach((key) => {
+            if (this[key] === undefined) {
+                throw new Error(`Property ${key} is missing`);
+            }
+            if (!this.hasOwnProperty(key)) {
+                throw new Error(`Property ${key} is not defined`);
+            }
+        });
+    }
+    get className() {
+        return this.constructor.name;
+    }
+    serialize() {
+        if (Object.values(this).some((value) => value instanceof Pointer)) {
+            this.pointers = {};
+        }
+        if (Object.values(this).some((value) => value instanceof Timestamp)) {
+            this.timestamps = {};
+        }
+        this.schema = this.className;
+        this.validate();
+        Object.keys(this).forEach((key) => {
+            if (this[key] instanceof Pointer) {
+                this.pointers[key] = this[key].setupPointer();
+                delete this[key];
+            }
+            if (this[key] instanceof Timestamp) {
+                this.timestamps[key] = this[key].timestamp;
+                delete this[key];
+            }
+        });
+        return { ...this };
+    }
+}
+/**
+ * Pointer class
+ * @class
+ * @param config - The pointer configuration
+ * @returns The pointer object
+ */
+class Pointer {
+    key;
+    keyspace;
+    constructor({ keyspace, key = '', customKey = '' }) {
+        this.keyspace = keyspace.keyspace;
+        this.key = key ? key.toString() : customKey ? convertCustomKey(customKey) : undefined;
+    }
+    setupPointer() {
+        if (this.keyspace && this.key) {
+            return [this.keyspace, this.key];
+        }
+        else {
+            throw new Error('Pointer is not valid. Please provide a keyspace and a key.');
+        }
+    }
+}
+/**
+ * Timestamp class
+ * @class
+ * @param timestamp - The timestamp object
+ * @returns The timestamp object
+ * @example
+ * const timestamp = new Timestamp({ timestamp: Date.now() });
+ */
+class Timestamp {
+    timestamp;
+    constructor({ timestamp }) {
+        this.timestamp = timestamp;
+    }
+    static after = class After {
+        after_timestamp;
+        constructor(after) {
+            this.after_timestamp = after;
+        }
+    };
+    static before = class Before {
+        before_timestamp;
+        constructor(before) {
+            this.before_timestamp = before;
+        }
+    };
+    static range = class Range {
+        range_timestamp;
+        constructor({ startTimestamp, endTimestamp }) {
+            this.range_timestamp = [startTimestamp, endTimestamp];
+        }
+    };
+}
+export { Schema, Pointer, Timestamp };

package/dist/core/store.d.ts

@@ -0,0 +1,13 @@
+import { InMemory, InMemoryDistributed } from './inmemory.js';
+import { Persistent, PersistentDistributed } from './persistent.js';
+/**
+ * Keyspace class that provides access to different keyspace implementations.
+ * It serves as a factory for creating instances of InMemory and Persistent keyspaces.
+ */
+declare class Keyspace {
+    static InMemory: typeof InMemory;
+    static Persistent: typeof Persistent;
+    static InMemoryDistributed: typeof InMemoryDistributed;
+    static PersistentDistributed: typeof PersistentDistributed;
+}
+export default Keyspace;

package/dist/core/store.js

@@ -0,0 +1,13 @@
+import { InMemory, InMemoryDistributed } from './inmemory.js';
+import { Persistent, PersistentDistributed } from './persistent.js';
+/**
+ * Keyspace class that provides access to different keyspace implementations.
+ * It serves as a factory for creating instances of InMemory and Persistent keyspaces.
+ */
+class Keyspace {
+    static InMemory = InMemory;
+    static Persistent = Persistent;
+    static InMemoryDistributed = InMemoryDistributed;
+    static PersistentDistributed = PersistentDistributed;
+}
+export default Keyspace;

package/dist/functions/storeGenericFunctions.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Utility functions for handling custom keys and values in a generic store.
+ * These functions include converting custom keys, processing bulk keys and values,
+ * and converting values to a binary query format.
+ */
+declare function convertCustomKey(key: string): string;
+/** * Converts an array of custom keys to their hashed string representations.
+ * @param keys - An array of keys, which can be strings or numbers.
+ * @returns An array of hashed string representations of the keys.
+ * */
+declare function convertCustomKeys(keys: string[]): string[];
+/**
+ * Converts an object of custom keys and values to their hashed string representations.
+ * @param keysValues - An object where keys can be strings or numbers, and values can be any type.
+ * @returns An object with hashed string keys and original values.
+ */
+declare function convertCustomKeysValues(keysValues: {
+    [key: string]: any;
+}): {
+    [key: string]: any;
+};
+/**
+ * Processes bulk keys and values, converting any Timestamp or Pointer instances
+ * to their appropriate string representations and hashing the keys.
+ * @param bulkKeysValues - An object containing bulk keys and values.
+ * @returns An object with processed keys and values.
+ */
+declare function processBulkKeysValues(bulkKeysValues: {
+    [key: string]: any;
+}): {
+    [key: string]: any;
+};
+/**
+ * Converts a class instance to a binary query string.
+ * @param cls - The class instance containing store properties.
+ * @param options - An object containing various options for the query.
+ * @returns A JSON string representing the binary query.
+ * */
+declare function convertToBinaryQuery(cls: any, options?: {
+    [key: string]: any;
+}): string;
+/**
+ * Runs a query against the store using the provided class instance.
+ * @param cls - The class instance containing store properties.
+ * @param query - The query string to execute.
+ * @returns A promise that resolves with the result of the query.
+ */
+declare function runQuery(cls: any, query: string): Promise<unknown>;
+/**
+ * Displays the properties of a store class instance.
+ * @param cls - The class instance containing store properties.
+ */
+declare function showStoreProperties(cls: any): void;
+export { convertCustomKey, convertCustomKeys, convertCustomKeysValues, convertToBinaryQuery, runQuery, showStoreProperties, processBulkKeysValues };

package/dist/functions/storeGenericFunctions.js

@@ -0,0 +1,160 @@
+import xxhash from 'xxhashjs';
+import { sendData } from '../core/engine.js';
+import { Timestamp, Pointer } from '../core/schema.js';
+/**
+ * Utility functions for handling custom keys and values in a generic store.
+ * These functions include converting custom keys, processing bulk keys and values,
+ * and converting values to a binary query format.
+ */
+function convertCustomKey(key) {
+    return xxhash.h32().update(key.toString()).digest().toNumber().toString();
+}
+/** * Converts an array of custom keys to their hashed string representations.
+ * @param keys - An array of keys, which can be strings or numbers.
+ * @returns An array of hashed string representations of the keys.
+ * */
+function convertCustomKeys(keys) {
+    return keys.map(convertCustomKey);
+}
+/**
+ * Converts an object of custom keys and values to their hashed string representations.
+ * @param keysValues - An object where keys can be strings or numbers, and values can be any type.
+ * @returns An object with hashed string keys and original values.
+ */
+function convertCustomKeysValues(keysValues) {
+    return Object.fromEntries(Object.entries(keysValues).map(([key, value]) => [convertCustomKey(key), value]));
+}
+/**
+ * Processes bulk keys and values, converting any Timestamp or Pointer instances
+ * to their appropriate string representations and hashing the keys.
+ * @param bulkKeysValues - An object containing bulk keys and values.
+ * @returns An object with processed keys and values.
+ */
+function processBulkKeysValues(bulkKeysValues) {
+    const bulkKeysValuesProcessed = {};
+    Object.keys(bulkKeysValues).forEach((key) => {
+        const entry = bulkKeysValues[key];
+        if (entry instanceof Object) {
+            const inner = entry;
+            Object.keys(inner).forEach((prop) => {
+                const value = inner[prop];
+                if (value instanceof Timestamp) {
+                    inner[prop] = value.timestamp;
+                }
+            });
+            if (entry instanceof Pointer) {
+                bulkKeysValues[key] = entry.setupPointer();
+            }
+            const processedKey = !isNaN(Number(key)) ? key : convertCustomKey(key);
+            bulkKeysValuesProcessed[processedKey] = JSON.stringify(bulkKeysValues[key]);
+        }
+    });
+    return bulkKeysValuesProcessed;
+}
+/**
+ * Converts a class instance to a binary query string.
+ * @param cls - The class instance containing store properties.
+ * @param options - An object containing various options for the query.
+ * @returns A JSON string representing the binary query.
+ * */
+function convertToBinaryQuery(cls, options = {}) {
+    const { key = null, value = {}, expireSec = 0, bulkValues = [], bulkKeys = [], bulkKeysValues = {}, searchCriteria = {}, limitOutput = { start: 0, stop: 0 }, withPointers = false, schema = null, } = options;
+    const { processedValue, foundSchema } = processValue(value);
+    const { processedBulkValues, uniqueSchema } = processBulkValues(bulkValues);
+    const bulkKeysValuesProcessed = processBulkKeysValues(bulkKeysValues);
+    return JSON.stringify({
+        username: cls.username,
+        password: cls.password,
+        namespace: cls.namespace,
+        store: cls.store,
+        keyspace: cls.keyspace,
+        persistent: cls.persistent,
+        distributed: cls.distributed,
+        limit_output: limitOutput,
+        key,
+        value: JSON.stringify(processedValue),
+        command: cls.command,
+        expire: expireSec,
+        bulk_values: processedBulkValues.map(v => JSON.stringify(v)),
+        bulk_keys: bulkKeys,
+        bulk_keys_values: bulkKeysValuesProcessed,
+        search_criteria: JSON.stringify(searchCriteria),
+        with_pointers: withPointers,
+        schema: foundSchema ? foundSchema : uniqueSchema ? uniqueSchema : schema,
+    });
+}
+/**
+ * Processes a single value, converting any Timestamp or Pointer instances
+ * to their appropriate string representations.
+ * @param value - The value to process, which can be any type.
+ * @returns An object containing the processed value and the found schema, if any.
+ */
+function processValue(value) {
+    let foundSchema = null;
+    if (value) {
+        if (value instanceof Object) {
+            if (value.hasOwnProperty('schema')) {
+                foundSchema = value['schema'];
+                delete value['schema'];
+            }
+            for (const prop in value) {
+                if (value[prop] instanceof Timestamp) {
+                    value[prop] = value[prop].timestamp; // Convert Timestamp to ISO string
+                }
+                if (value[prop] instanceof Pointer) {
+                    value[prop] = value[prop].setupPointer(); // Serialize Pointer
+                }
+            }
+        }
+        return { processedValue: value, foundSchema };
+    }
+    return { processedValue: value, foundSchema };
+}
+/** * Processes an array of bulk values, converting any Timestamp or Pointer instances
+ * to their appropriate string representations and ensuring all values have the same schema.
+ * @param bulkValues - An array of values to process.
+ * @returns An object containing the processed bulk values and the unique schema, if any.
+ */
+function processBulkValues(bulkValues) {
+    let arrayWithValues = [];
+    let uniqueSchemas = new Set();
+    if (bulkValues.length > 0) {
+        bulkValues.forEach((val, i) => {
+            const { processedValue, foundSchema } = processValue(val);
+            if (foundSchema) {
+                if (uniqueSchemas.size > 1) {
+                    throw new Error("Bulk values must have the same schema");
+                }
+                else {
+                    uniqueSchemas.add(foundSchema);
+                }
+            }
+            arrayWithValues.push(processedValue);
+        });
+    }
+    return { processedBulkValues: arrayWithValues, uniqueSchema: uniqueSchemas.size > 0 ? uniqueSchemas.values().next().value : null };
+}
+/**
+ * Runs a query against the store using the provided class instance.
+ * @param cls - The class instance containing store properties.
+ * @param query - The query string to execute.
+ * @returns A promise that resolves with the result of the query.
+ */
+async function runQuery(cls, query) {
+    return sendData(cls.host, cls.port, query);
+}
+/**
+ * Displays the properties of a store class instance.
+ * @param cls - The class instance containing store properties.
+ */
+function showStoreProperties(cls) {
+    console.log(`Store Name: ${cls.store}\n` +
+        `Store Namespace: ${cls.namespace}\n` +
+        `Persistent: ${cls.persistent}\n` +
+        `Distributed: ${cls.distributed}\n` +
+        `Host: ${cls.host}\n` +
+        `Port: ${cls.port}\n` +
+        `Username: ${cls.username}\n` +
+        `Password: ${cls.password}\n`);
+}
+export { convertCustomKey, convertCustomKeys, convertCustomKeysValues, convertToBinaryQuery, runQuery, showStoreProperties, processBulkKeysValues };

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+import { Engine, ValidPermissions } from "./core/engine.js";
+import Keyspace from "./core/store.js";
+import { Pointer, Timestamp, Schema } from "./core/schema.js";
+export { Engine, ValidPermissions, Keyspace, Pointer, Timestamp, Schema };

package/dist/index.js

@@ -0,0 +1,4 @@
+import { Engine, ValidPermissions } from "./core/engine.js";
+import Keyspace from "./core/store.js";
+import { Pointer, Timestamp, Schema } from "./core/schema.js";
+export { Engine, ValidPermissions, Keyspace, Pointer, Timestamp, Schema };

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "montycat",
+  "version": "1.0.2",
+  "description": "A Node.js client for MontyCat, NoSQL store utilizing Data Mesh architecture.",
+  "type": "module",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsc --watch"
+  },
+  "keywords": [],
+  "devDependencies": {
+    "@types/json-bigint": "^1.0.4",
+    "@types/node": "^24.1.0",
+    "@types/xxhashjs": "^0.2.4",
+    "typescript": "^5.9.2"
+  },
+  "author": "MontyGovernance",
+  "license": "MIT",
+  "dependencies": {
+    "json-bigint": "^1.0.0",
+    "xxhash": "^0.3.0",
+    "xxhash-wasm": "^1.0.2",
+    "xxhashjs": "^0.2.2"
+  }
+}

package/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleResolution": "node",
+    "outDir": "./dist",
+    "declaration": true,
+    "declarationDir": "./dist",
+    "emitDeclarationOnly": false,
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}