icql-core 1.0.0

package/index.js

@@ -0,0 +1,206 @@
+/**
+ * ICQL CORE - The Relational Engine
+ */
+
+import { setDoc, getDoc, deleteDoc, initJuno } from "@junobuild/core";
+
+export class ICQLEngine {
+    constructor() {
+        this.schemas = new Map();
+        this.initialized = false;
+    }
+
+    /**
+     * Initialize the Engine.
+     * @param {Object} config
+     * @param {string} config.satelliteId - The Juno Satellite ID
+     * @param {Array} config.schemas - Optional array of schemas to define on boot
+     */
+    async init({ satelliteId, schemas = [] }) {
+        if (this.initialized) return;
+
+        await initJuno({ satelliteId });
+
+        // Register initial schemas if provided
+        for (const schema of schemas) {
+            await this.defineSchema(schema);
+        }
+
+        this.initialized = true;
+    }
+
+    // --- SCHEMA MANAGER ---
+
+    async defineSchema(schema) {
+        const schemaKey = `schema_${schema.name}`;
+        let currentVersion = undefined;
+
+        try {
+            const existing = await getDoc({ collection: "_schemas", key: schemaKey });
+            if (existing) currentVersion = existing.version;
+        } catch (e) {}
+
+        const docPayload = { key: schemaKey, data: schema };
+        if (currentVersion !== undefined) docPayload.version = currentVersion;
+
+        await setDoc({ collection: "_schemas", doc: docPayload });
+        this.schemas.set(schema.name, schema);
+        return schema;
+    }
+
+    async getSchema(name) {
+        if (this.schemas.has(name)) return this.schemas.get(name);
+        try {
+            const schemaDoc = await getDoc({ collection: "_schemas", key: `schema_${name}` });
+            if (schemaDoc?.data) {
+                this.schemas.set(name, schemaDoc.data);
+                return schemaDoc.data;
+            }
+        } catch (e) {}
+        return null;
+    }
+
+    // --- INDEX MANAGER (Internal) ---
+
+    async _updateIndexWithRetry(indexKey, updateFn, maxAttempts = 5) {
+        let attempts = 0;
+        while (attempts < maxAttempts) {
+            try {
+                const indexDoc = await getDoc({ collection: "_indexes", key: indexKey });
+                let ids = [];
+                let currentVersion = undefined;
+
+                if (indexDoc?.data) {
+                    ids = Array.isArray(indexDoc.data) ? indexDoc.data : (indexDoc.data.data || []);
+                    currentVersion = indexDoc.version;
+                }
+
+                const newIds = await updateFn(ids);
+                if (newIds === null) return true;
+
+                const docPayload = { key: indexKey, data: newIds };
+                if (currentVersion !== undefined) docPayload.version = currentVersion;
+
+                await setDoc({ collection: "_indexes", doc: docPayload });
+                return true;
+            } catch (e) {
+                attempts++;
+                // Handle Not Found (Race condition on creation)
+                if (e.message?.includes('not found') || e.message?.includes('NotFound')) {
+                    try {
+                        const newIds = await updateFn([]);
+                        await setDoc({ collection: "_indexes", doc: { key: indexKey, data: newIds } });
+                        return true;
+                    } catch (err) {}
+                }
+                
+                // Exponential Backoff
+                if (attempts < maxAttempts) {
+                    await new Promise(r => setTimeout(r, 100 * Math.pow(2, attempts - 1)));
+                } else {
+                    console.error(`ICQL Index Error: Failed to update ${indexKey}`, e);
+                    return false;
+                }
+            }
+        }
+        return false;
+    }
+
+    // --- CRUD OPERATIONS ---
+
+    async create(type, data) {
+        const docId = `doc_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+        const doc = {
+            _id: docId,
+            _type: type,
+            _createdAt: new Date().toISOString(),
+            _updatedAt: new Date().toISOString(),
+            ...data
+        };
+
+        // Write to generic collection if not specific
+        // Note: For advanced usage, one might want specific collections. 
+        // Here we default to 'content' unless the type matches a collection name, 
+        // but for ICQL standard we usually assume 'post', 'author' etc exist.
+        // We try to write to the collection named 'type', fallback to 'content' if logic requires.
+        // For now, we assume the user configured the collection in Juno Config.
+        
+        await setDoc({
+            collection: type, // We assume the collection exists (e.g. 'post')
+            doc: { key: docId, data: doc }
+        });
+
+        // Update Indexes
+        this._updateIndexWithRetry(`idx__type_${type}`, ids => [...new Set([...ids, docId])]);
+        
+        // Auto-index slug if present
+        if (data.slug) {
+            this._updateIndexWithRetry(`idx_slug_${data.slug}`, ids => [...new Set([...ids, docId])]);
+        }
+
+        // Handle References (Foreign Keys)
+        for (const [key, value] of Object.entries(data)) {
+            if (value && typeof value === 'object' && value._ref) {
+                this._updateIndexWithRetry(`ref_reverse_${value._ref}`, ids => [...new Set([...ids, docId])]);
+            }
+        }
+
+        return doc;
+    }
+
+    async fetch(type) {
+        const indexKey = `idx__type_${type}`;
+        try {
+            const indexDoc = await getDoc({ collection: "_indexes", key: indexKey });
+            if (!indexDoc?.data) return [];
+            
+            const docIds = Array.isArray(indexDoc.data) ? indexDoc.data : (indexDoc.data.data || []);
+            
+            // Parallel Fetch
+            const results = await Promise.all(docIds.map(id => 
+                getDoc({ collection: type, key: id })
+                .catch(() => null) // Handle deleted docs gracefully
+            ));
+            
+            return results.filter(r => r?.data).map(r => r.data);
+        } catch (e) {
+            return [];
+        }
+    }
+
+    async getById(docId) {
+        // We don't know the collection, so we try the most common ones or we need an index "all_docs".
+        // For this version, we require the user to know the collection OR we scan standard ones.
+        // A pro version would have a `sys_id_map` index.
+        // FALLBACK: Try 'content', 'post', 'author', 'category'
+        const candidates = ['post', 'author', 'category', 'content'];
+        
+        for (const col of candidates) {
+            try {
+                const res = await getDoc({ collection: col, key: docId });
+                if (res?.data) return res.data;
+            } catch(e) {}
+        }
+        return null;
+    }
+
+    async delete(docId) {
+        // Same bruteforce approach for delete if we don't know the collection
+        const candidates = ['post', 'author', 'category', 'content'];
+        for (const col of candidates) {
+            try {
+                const docEnvelope = await getDoc({ collection: col, key: docId });
+                if (docEnvelope) {
+                    await deleteDoc({ collection: col, doc: docEnvelope });
+                    // Note: We are NOT cleaning up indexes here to save bandwidth/time.
+                    // Ideally, we should remove IDs from _indexes.
+                    return true;
+                }
+            } catch (e) {}
+        }
+        throw new Error("Document not found or could not be deleted");
+    }
+}
+
+// Default Singleton Instance
+export const icql = new ICQLEngine();

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "icql-core",
+  "version": "1.0.0",
+  "description": "Relational Layer and Query Engine for Juno (Internet Computer). Build decentralized databases with JS only.",
+  "main": "index.js",
+  "type": "module",
+  "files": [
+    "index.js",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [
+    "juno",
+    "icp",
+    "internet-computer",
+    "cms",
+    "relational",
+    "database",
+    "web3",
+    "decentralized"
+  ],
+  "author": "GrayFox",
+  "license": "ISC",
+  "peerDependencies": {
+    "@junobuild/core": "^0.0.57"
+  },
+  "dependencies": {
+    "nanoid": "^5.0.9"
+  }
+}