@nekodb/client 1.0.0

package/connection/manager.js

@@ -0,0 +1,135 @@
+class ConnectionManager {
+    #connections;
+    #activeId;
+    #healthChecks;
+    #maxConnections;
+
+    constructor(maxConnections = 5) {
+        this.#connections = new Map();
+        this.#activeId = null;
+        this.#healthChecks = new Map();
+        this.#maxConnections = maxConnections;
+    }
+
+    add(id, nekoDBInstance) {
+        if (this.#connections.size >= this.#maxConnections) {
+            throw new Error(`Max connections (${this.#maxConnections}) reached`);
+        }
+        this.#connections.set(id, {
+            db: nekoDBInstance,
+            addedAt: new Date(),
+            lastUsed: new Date(),
+        });
+        if (!this.#activeId) this.#activeId = id;
+        return this;
+    }
+
+    remove(id) {
+        const entry = this.#connections.get(id);
+        if (entry) {
+            try { entry.db.close(); } catch { }
+            this.#connections.delete(id);
+            if (this.#activeId === id) {
+                const keys = [...this.#connections.keys()];
+                this.#activeId = keys.length > 0 ? keys[0] : null;
+            }
+        }
+        return this;
+    }
+
+    get(id) {
+        const entry = this.#connections.get(id);
+        if (entry) {
+            entry.lastUsed = new Date();
+            return entry.db;
+        }
+        return null;
+    }
+
+    active() {
+        if (!this.#activeId) return null;
+        return this.get(this.#activeId);
+    }
+
+    setActive(id) {
+        if (!this.#connections.has(id)) {
+            throw new Error(`Connection "${id}" not found`);
+        }
+        this.#activeId = id;
+        return this;
+    }
+
+    get activeId() { return this.#activeId; }
+
+    has(id) {
+        return this.#connections.has(id);
+    }
+
+    list() {
+        const result = [];
+        for (const [id, entry] of this.#connections) {
+            result.push({
+                id,
+                connected: entry.db.connected,
+                addedAt: entry.addedAt,
+                lastUsed: entry.lastUsed,
+                isActive: id === this.#activeId,
+            });
+        }
+        return result;
+    }
+
+    get size() {
+        return this.#connections.size;
+    }
+
+    getHealthy() {
+        const healthy = [];
+        for (const [id, entry] of this.#connections) {
+            if (entry.db.connected) healthy.push(id);
+        }
+        return healthy;
+    }
+
+    getUnhealthy() {
+        const unhealthy = [];
+        for (const [id, entry] of this.#connections) {
+            if (!entry.db.connected) unhealthy.push(id);
+        }
+        return unhealthy;
+    }
+
+    switchToHealthy() {
+        const healthy = this.getHealthy();
+        if (healthy.length === 0) return false;
+        if (healthy.includes(this.#activeId)) return true;
+        this.#activeId = healthy[0];
+        return true;
+    }
+
+    async closeAll() {
+        for (const [id, entry] of this.#connections) {
+            try { entry.db.close(); } catch { }
+        }
+        this.#connections.clear();
+        this.#activeId = null;
+    }
+
+    getStats() {
+        let connected = 0;
+        let disconnected = 0;
+        for (const [, entry] of this.#connections) {
+            if (entry.db.connected) connected++;
+            else disconnected++;
+        }
+        return {
+            total: this.#connections.size,
+            connected,
+            disconnected,
+            activeId: this.#activeId,
+            maxConnections: this.#maxConnections,
+        };
+    }
+}
+
+module.exports = { ConnectionManager };

package/connection/status.js

@@ -0,0 +1,17 @@
+const ConnectionStatus = {
+    DISCONNECTED: 'disconnected',
+    CONNECTING: 'connecting',
+    CONNECTED: 'connected',
+};
+
+class ConnectionHealth {
+    static check(instance) {
+        if (!instance) return ConnectionStatus.DISCONNECTED;
+        return instance.connected ? ConnectionStatus.CONNECTED : ConnectionStatus.DISCONNECTED;
+    }
+}
+
+module.exports = {
+    ConnectionStatus,
+    ConnectionHealth,
+};

package/errors/base.js

@@ -0,0 +1,19 @@
+class NekoError extends Error {
+    constructor(message, code) {
+        super(message);
+        this.name = 'NekoError';
+        this.code = code || 'UNKNOWN';
+        this.timestamp = new Date();
+    }
+
+    toJSON() {
+        return {
+            name: this.name,
+            code: this.code,
+            message: this.message,
+            timestamp: this.timestamp,
+        };
+    }
+}
+
+module.exports = { NekoError };

package/errors/classifier.js

@@ -0,0 +1,15 @@
+const { NekoError } = require('./base');
+const { AuthError, NotFoundError } = require('./database');
+
+function classify(raw) {
+    if (typeof raw === 'string') {
+        const msg = raw.trim();
+        if (msg === 'invalid-credentials') return new AuthError();
+        if (msg === 'not-found') return new NotFoundError();
+        if (msg.startsWith('blocked:')) return new NekoError(msg, 'BLOCKED');
+        if (msg === 'invalid-json') return new NekoError('Invalid JSON payload', 'INVALID_PAYLOAD');
+    }
+    return null;
+}
+
+module.exports = { classify };

package/errors/database.js

@@ -0,0 +1,63 @@
+const { NekoError } = require('./base');
+
+class AuthError extends NekoError {
+    constructor(message) {
+        super(message || 'Authentication failed', 'AUTH_ERROR');
+        this.name = 'AuthError';
+    }
+}
+
+class NotFoundError extends NekoError {
+    constructor(collection, documentId) {
+        super(`Document not found: ${collection}/${documentId}`, 'NOT_FOUND');
+        this.name = 'NotFoundError';
+        this.collection = collection;
+        this.documentId = documentId;
+    }
+}
+
+class ValidationError extends NekoError {
+    #errors;
+
+    constructor(message, errors) {
+        super(message || 'Validation failed', 'VALIDATION_ERROR');
+        this.name = 'ValidationError';
+        this.#errors = errors || [];
+    }
+
+    get errors() { return [...this.#errors]; }
+
+    toJSON() {
+        return { ...super.toJSON(), errors: this.#errors };
+    }
+}
+
+class BulkOperationError extends NekoError {
+    #results;
+
+    constructor(message, results) {
+        super(message || 'Bulk operation partially failed', 'BULK_ERROR');
+        this.name = 'BulkOperationError';
+        this.#results = results || [];
+    }
+
+    get results() { return [...this.#results]; }
+    get successCount() { return this.#results.filter(r => r.success).length; }
+    get failCount() { return this.#results.filter(r => !r.success).length; }
+}
+
+class CollectionError extends NekoError {
+    constructor(message, collection) {
+        super(message || 'Collection error', 'COLLECTION_ERROR');
+        this.name = 'CollectionError';
+        this.collection = collection;
+    }
+}
+
+module.exports = {
+    AuthError,
+    NotFoundError,
+    ValidationError,
+    BulkOperationError,
+    CollectionError,
+};

package/errors/index.js

@@ -0,0 +1,16 @@
+const { NekoError } = require('./base');
+const { ConnectionError, TimeoutError } = require('./network');
+const { AuthError, NotFoundError, ValidationError, BulkOperationError, CollectionError } = require('./database');
+const { classify } = require('./classifier');
+
+module.exports = {
+    NekoError,
+    ConnectionError,
+    TimeoutError,
+    AuthError,
+    NotFoundError,
+    ValidationError,
+    BulkOperationError,
+    CollectionError,
+    classify,
+};

package/errors/network.js

@@ -0,0 +1,23 @@
+const { NekoError } = require('./base');
+
+class ConnectionError extends NekoError {
+    constructor(message, host) {
+        super(message || 'Connection failed', 'CONNECTION_ERROR');
+        this.name = 'ConnectionError';
+        this.host = host || null;
+    }
+}
+
+class TimeoutError extends NekoError {
+    constructor(message, operation, durationMs) {
+        super(message || 'Operation timed out', 'TIMEOUT');
+        this.name = 'TimeoutError';
+        this.operation = operation || null;
+        this.durationMs = durationMs || 0;
+    }
+}
+
+module.exports = {
+    ConnectionError,
+    TimeoutError,
+};

package/events/constants.js

@@ -0,0 +1,10 @@
+const Events = {
+    CONNECTED: 'connected',
+    DISCONNECTED: 'disconnected',
+    ERROR: 'error',
+    CLOSED: 'closed',
+    MESSAGE: 'message',
+    ALL: '*',
+};
+
+module.exports = { Events };

package/events/emitter.js

@@ -0,0 +1,106 @@
+const { Subscription } = require('./subscriber');
+const { Events } = require('./constants');
+
+class EventBus {
+    #listeners;
+    #onceFlags;
+    #maxListeners;
+
+    constructor(maxListeners = 50) {
+        this.#listeners = new Map();
+        this.#onceFlags = new WeakSet();
+        this.#maxListeners = maxListeners;
+    }
+
+    on(event, handler) {
+        if (typeof handler !== 'function') throw new TypeError('Handler must be a function');
+        if (!this.#listeners.has(event)) this.#listeners.set(event, []);
+        const handlers = this.#listeners.get(event);
+        if (handlers.length >= this.#maxListeners) {
+            console.warn(`[EventBus] Max listeners (${this.#maxListeners}) reached for "${event}"`);
+        }
+        handlers.push(handler);
+        return new Subscription(this, event, handler);
+    }
+
+    once(event, handler) {
+        if (typeof handler !== 'function') throw new TypeError('Handler must be a function');
+        const wrapper = (...args) => {
+            this.off(event, wrapper);
+            handler(...args);
+        };
+        this.#onceFlags.add(wrapper);
+        this.on(event, wrapper);
+        return new Subscription(this, event, wrapper);
+    }
+
+    off(event, handler) {
+        if (!handler) {
+            this.#listeners.delete(event);
+            return this;
+        }
+        const handlers = this.#listeners.get(event);
+        if (handlers) {
+            const idx = handlers.indexOf(handler);
+            if (idx !== -1) handlers.splice(idx, 1);
+            if (handlers.length === 0) this.#listeners.delete(event);
+        }
+        return this;
+    }
+
+    emit(event, ...args) {
+        const handlers = this.#listeners.get(event);
+        if (!handlers || handlers.length === 0) return false;
+        for (const handler of [...handlers]) {
+            try { handler(...args); } catch (err) {
+                console.error(`[EventBus] Error in "${event}" handler:`, err);
+            }
+        }
+
+        if (event !== Events.ALL) {
+            const wildcardHandlers = this.#listeners.get(Events.ALL);
+            if (wildcardHandlers) {
+                for (const handler of [...wildcardHandlers]) {
+                    try { handler(event, ...args); } catch { }
+                }
+            }
+        }
+        return true;
+    }
+
+    listenerCount(event) {
+        return this.#listeners.get(event)?.length || 0;
+    }
+
+    eventNames() {
+        return [...this.#listeners.keys()];
+    }
+
+    removeAllListeners(event) {
+        if (event) {
+            this.#listeners.delete(event);
+        } else {
+            this.#listeners.clear();
+        }
+        return this;
+    }
+
+    waitFor(event, timeoutMs = 30000) {
+        return new Promise((resolve, reject) => {
+            let timer;
+            const handler = (data) => {
+                clearTimeout(timer);
+                resolve(data);
+            };
+            this.once(event, handler);
+            if (timeoutMs > 0) {
+                timer = setTimeout(() => {
+                    this.off(event, handler);
+                    reject(new Error(`Timeout waiting for "${event}"`));
+                }, timeoutMs);
+            }
+        });
+    }
+}
+
+module.exports = { EventBus };

package/events/index.js

@@ -0,0 +1,9 @@
+const { EventBus } = require('./emitter');
+const { Subscription } = require('./subscriber');
+const { Events } = require('./constants');
+
+module.exports = {
+    EventBus,
+    Subscription,
+    Events,
+};

package/events/subscriber.js

@@ -0,0 +1,21 @@
+class Subscription {
+    #bus;
+    #event;
+    #handler;
+
+    constructor(bus, event, handler) {
+        this.#bus = bus;
+        this.#event = event;
+        this.#handler = handler;
+    }
+
+    unsubscribe() {
+        if (this.#bus) {
+            this.#bus.off(this.#event, this.#handler);
+            this.#bus = null;
+            this.#handler = null;
+        }
+    }
+}
+
+module.exports = { Subscription };

package/helpers/collection.js

@@ -0,0 +1,151 @@
+class CollectionHelper {
+    #db;
+    #collection;
+
+    constructor(db, collectionName) {
+        this.#db = db;
+        this.#collection = collectionName;
+    }
+
+    get name() { return this.#collection; }
+
+    async findOne(query) {
+        const ids = await this.#db.search(this.#collection, query);
+        if (!Array.isArray(ids) || ids.length === 0) return null;
+        return this.#db.get(this.#collection, ids[0]);
+    }
+
+    async findById(id) {
+        const doc = await this.#db.get(this.#collection, id);
+        if (doc === 'not-found' || doc === null) return null;
+        return { _id: id, ...doc };
+    }
+
+    async exists(id) {
+        const doc = await this.#db.get(this.#collection, id);
+        return doc !== 'not-found' && doc !== null;
+    }
+
+    async findMany(query) {
+        const ids = await this.#db.search(this.#collection, query);
+        if (!Array.isArray(ids)) return [];
+        const docs = [];
+        for (const id of ids) {
+            const doc = await this.#db.get(this.#collection, id);
+            if (doc && doc !== 'not-found') {
+                docs.push({ _id: id, ...doc });
+            }
+        }
+        return docs;
+    }
+
+    async getAll() {
+        const ids = await this.#db.list(this.#collection);
+        if (!Array.isArray(ids)) return [];
+        const docs = [];
+        for (const id of ids) {
+            const doc = await this.#db.get(this.#collection, id);
+            if (doc && doc !== 'not-found') {
+                docs.push({ _id: id, ...doc });
+            }
+        }
+        return docs;
+    }
+
+    async upsert(query, data) {
+        const ids = await this.#db.search(this.#collection, query);
+        if (Array.isArray(ids) && ids.length > 0) {
+            await this.#db.update(this.#collection, ids[0], data);
+            return { action: 'updated', id: ids[0] };
+        }
+        const id = await this.#db.insert(this.#collection, data);
+        return { action: 'inserted', id };
+    }
+
+    async findOrInsert(query, defaultDoc) {
+        const existing = await this.findOne(query);
+        if (existing) return { doc: existing, created: false };
+        const id = await this.#db.insert(this.#collection, defaultDoc || query);
+        const doc = await this.#db.get(this.#collection, id);
+        return { doc: { _id: id, ...doc }, created: true };
+    }
+
+    async updateWhere(query, updates) {
+        const ids = await this.#db.search(this.#collection, query);
+        if (!Array.isArray(ids)) return { matched: 0, modified: 0 };
+        let modified = 0;
+        for (const id of ids) {
+            const ok = await this.#db.update(this.#collection, id, updates);
+            if (ok !== 'not-found') modified++;
+        }
+        return { matched: ids.length, modified };
+    }
+
+    async deleteWhere(query) {
+        const ids = await this.#db.search(this.#collection, query);
+        if (!Array.isArray(ids)) return { deleted: 0 };
+        let deleted = 0;
+        for (const id of ids) {
+            const ok = await this.#db.delete(this.#collection, id);
+            if (ok !== 'not-found') deleted++;
+        }
+        return { deleted };
+    }
+
+    async replaceOne(id, doc) {
+        const existing = await this.#db.get(this.#collection, id);
+        if (!existing || existing === 'not-found') return false;
+        await this.#db.delete(this.#collection, id);
+        await this.#db.insert(this.#collection, { _original_id: id, ...doc });
+        return true;
+    }
+
+    async insertMany(docs) {
+        return this.#db.bulkInsert(this.#collection, docs);
+    }
+
+    async deleteMany(ids) {
+        return this.#db.bulkDelete(this.#collection, ids);
+    }
+
+    async *paginate(options = {}) {
+        const pageSize = options.limit || 20;
+        let page = 1;
+        let hasMore = true;
+
+        while (hasMore) {
+            const result = await this.#db.listPaginated(this.#collection, {
+                limit: pageSize,
+                page,
+                sort: options.sort || [],
+                filter: options.filter || null,
+            });
+
+            if (result?.data) {
+                yield { page, data: result.data, pageInfo: result.page_info };
+            }
+
+            hasMore = result?.page_info?.has_next || false;
+            page++;
+        }
+    }
+
+    async forEach(query, callback) {
+        const docs = await this.findMany(query);
+        for (let i = 0; i < docs.length; i++) {
+            await callback(docs[i], i);
+        }
+    }
+
+    async map(query, transform) {
+        const docs = await this.findMany(query);
+        return docs.map(transform);
+    }
+
+    async filter(query, predicate) {
+        const docs = await this.findMany(query);
+        return docs.filter(predicate);
+    }
+}
+
+module.exports = { CollectionHelper };

package/helpers/document.js

@@ -0,0 +1,49 @@
+const crypto = require('crypto');
+
+function generateId() {
+    return crypto.randomBytes(16).toString('hex');
+}
+
+function getNestedValue(obj, path) {
+    if (!path) return obj;
+    return path.split('.').reduce((acc, part) => {
+        if (acc && typeof acc === 'object') return acc[part];
+        return undefined;
+    }, obj);
+}
+
+function setNestedValue(obj, path, value) {
+    if (!path) return obj;
+    const parts = path.split('.');
+    let current = obj;
+
+    for (let i = 0; i < parts.length - 1; i++) {
+        const part = parts[i];
+        if (current[part] === undefined || typeof current[part] !== 'object' || current[part] === null) {
+            current[part] = {};
+        }
+        current = current[part];
+    }
+
+    current[parts[parts.length - 1]] = value;
+    return obj;
+}
+
+function deepMerge(target, source) {
+    const result = { ...target };
+    for (const [key, value] of Object.entries(source)) {
+        if (value && typeof value === 'object' && !Array.isArray(value)) {
+            result[key] = deepMerge(result[key] || {}, value);
+        } else {
+            result[key] = value;
+        }
+    }
+    return result;
+}
+
+module.exports = {
+    generateId,
+    getNestedValue,
+    setNestedValue,
+    deepMerge,
+};

package/helpers/index.js

@@ -0,0 +1,9 @@
+const { CollectionHelper } = require('./collection');
+const { CursorNavigator } = require('./pagination');
+const documentHelpers = require('./document');
+
+module.exports = {
+    CollectionHelper,
+    CursorNavigator,
+    ...documentHelpers,
+};