@quickql/server 1.0.0

package/dist/server/src/playground/assets.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"assets.js","sourceRoot":"","sources":["../../../../src/playground/assets.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAEhC;;GAEG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG;EAC1B,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAqjCP,CAAC;AAEF,MAAM,CAAC,MAAM,aAAa,GAAG;;;;;;;;;;;;;;;;;;CAkB5B,CAAC"}

package/dist/server/src/playground/docs.d.ts

@@ -0,0 +1,15 @@
+/**
+ * QuickQL Documentation Generator
+ *
+ * Logic for generating real-time, interactive API documentation
+ * from the server's processed schema metadata.
+ *
+ * (c) 2024-2026 Udinmo Inc. All rights reserved.
+ * Author: Udinmo Inc. <engineering@udinmo.com>
+ * License: MIT
+ */
+/**
+ * Documentation Generator for QuickQL Playground
+ */
+export declare const docsJs = "\nfunction renderDocsPage() {\n    const schema = (window).currentSchema || [];\n    if (schema.length === 0) {\n        return '<div class=\"p-5 text-center text-muted\"><div class=\"mb-3\" style=\"font-size: 48px; opacity: 0.15;\"><i class=\"fas fa-book-open\"></i></div><h4 class=\"fw-bold\">No Schema Loaded</h4><p class=\"text-muted\">Navigate to a collection or refresh to load schema metadata.</p></div>';\n    }\n\n    // --- Helper: infer type badge ---\n    function getTypeInfo(fName) {\n        if (fName === 'id' || fName.endsWith('_id')) return { label: 'ID', color: '#7c3aed', bg: '#ede9fe' };\n        if (fName === 'email') return { label: 'Email', color: '#0891b2', bg: '#e0f2fe' };\n        if (fName === 'created_at' || fName === 'updated_at' || fName.endsWith('_at')) return { label: 'DateTime', color: '#d97706', bg: '#fef3c7' };\n        if (fName.startsWith('is_') || fName.startsWith('has_') || fName === 'active' || fName === 'enabled') return { label: 'Boolean', color: '#059669', bg: '#d1fae5' };\n        if (fName.includes('count') || fName === 'age' || fName === 'total' || fName.includes('amount') || fName.includes('price')) return { label: 'Number', color: '#dc2626', bg: '#fee2e2' };\n        if (fName === 'password' || fName === 'token' || fName === 'secret') return { label: 'Hash', color: '#64748b', bg: '#f1f5f9' };\n        if (fName.includes('url') || fName.includes('image') || fName.includes('avatar') || fName.includes('link')) return { label: 'URL', color: '#6366f1', bg: '#eef2ff' };\n        return { label: 'String', color: '#475569', bg: '#f8fafc' };\n    }\n\n    function getFieldDesc(fName, colName) {\n        if (fName === 'id') return 'Primary key. Unique record identifier \u2014 used for targeted lookups and as a foreign key reference in relations.';\n        if (fName.endsWith('_id')) return 'Foreign key reference to a related <strong>' + fName.replace('_id','') + '</strong> record.';\n        if (fName === 'email') return 'Email address. Used for authentication and contact. Must be a valid RFC 5321 format.';\n        if (fName.includes('name')) return 'Human-readable display name or label for the <strong>' + colName + '</strong> record.';\n        if (fName === 'created_at') return 'Timestamp of when this record was first persisted. Set automatically by the system.';\n        if (fName === 'updated_at') return 'Timestamp of the last modification. Automatically updated on every write operation.';\n        if (fName === 'password') return 'Hashed credential string. Never returned in plain text \u2014 always stored using a one-way hash.';\n        if (fName.startsWith('is_')) return 'Boolean flag. Indicates whether the <em>' + fName.replace('is_','') + '</em> condition is true for this record.';\n        if (fName.startsWith('has_')) return 'Boolean flag. Indicates presence or availability of <em>' + fName.replace('has_','') + '</em>.';\n        if (fName.includes('count')) return 'Aggregate counter. Denormalized value tracking the number of related sub-items.';\n        if (fName.includes('url') || fName.includes('image') || fName.includes('avatar')) return 'URL pointing to an external or stored resource. Should be a fully qualified URI.';\n        if (fName.includes('amount') || fName.includes('price') || fName.includes('total')) return 'Monetary or numeric value. Stored as a fixed-precision number to avoid floating-point errors.';\n        return 'Data attribute on <strong>' + colName + '</strong>. Stores domain-specific information for this field.';\n    }\n\n    let html = '';\n    html += '<div class=\"d-flex h-100 bg-white\" style=\"min-width: 0;\">';\n\n    // --- Left nav sidebar ---\n    html += '<aside class=\"flex-shrink-0 border-end d-flex flex-column\" style=\"width: 190px; overflow-y: auto; background: #fafafa;\">';\n    html += '  <div class=\"px-4 pt-4 pb-3 border-bottom bg-white\">';\n    html += '    <div class=\"text-uppercase fw-bold text-muted mb-1\" style=\"font-size: 10px; letter-spacing: 2px;\">Collections</div>';\n    html += '    <div class=\"text-muted\" style=\"font-size: 11px;\">' + schema.length + ' collection' + (schema.length !== 1 ? 's' : '') + ' detected</div>';\n    html += '  </div>';\n    html += '  <div class=\"py-2\">';\n    schema.forEach((col, idx) => {\n        const colors = ['#3b82f6','#8b5cf6','#ec4899','#10b981','#f59e0b','#ef4444','#06b6d4'];\n        const c = colors[idx % colors.length];\n        html += '<a href=\"#doc-' + col.name + '\" class=\"d-flex align-items-center gap-3 px-4 py-2 text-decoration-none docs-nav-item\" style=\"color: #374151; font-size: 13px; font-weight: 600; transition: background 0.15s;\">';\n        html += '  <span style=\"width: 8px; height: 8px; border-radius: 50%; background: ' + c + '; flex-shrink: 0; display: inline-block;\"></span>';\n        html += '  <span>' + col.name + '</span>';\n        html += '  <span class=\"ms-auto text-muted fw-normal\" style=\"font-size: 11px;\">' + col.fields.length + 'f</span>';\n        html += '</a>';\n    });\n    html += '  </div>';\n    html += '</aside>';\n\n    // --- Main docs body ---\n    html += '<main class=\"flex-grow-1 overflow-auto\" style=\"min-width: 0; background: #fff;\">';\n    html += '  <div class=\"mx-auto\" style=\"max-width: 900px; padding: 28px 24px;\">';\n\n    // Header\n    html += '  <div class=\"mb-4 pb-3 border-bottom\">';\n    html += '    <div class=\"d-flex align-items-start justify-content-between\">';\n    html += '      <div>';\n    html += '        <h1 class=\"fw-bold mb-1\" style=\"font-size: 22px; letter-spacing: -0.5px;\">API Reference</h1>';\n    html += '        <p class=\"text-muted mb-0\" style=\"font-size: 13px;\">Auto-generated docs for your QuickQL schema. Uses the QuickQL native query language.</p>';\n    html += '      </div>';\n    html += '      <span class=\"badge px-3 py-2 ms-3 flex-shrink-0\" style=\"background: #d1fae5; color: #065f46; font-size: 10px; border-radius: 100px; font-weight: 700;\">\u25CF LIVE</span>';\n    html += '    </div>';\n    html += '  </div>';\n\n    // Query Syntax intro box\n    html += '  <div class=\"mb-4 p-3 rounded-2\" style=\"background: #f8fafc; border: 1px solid #e2e8f0;\">';\n    html += '    <div class=\"d-flex align-items-center gap-2 mb-2\">';\n    html += '      <i class=\"fas fa-terminal text-primary\" style=\"font-size: 11px;\"></i>';\n    html += '      <span class=\"fw-bold text-dark\" style=\"font-size: 11px; text-transform: uppercase; letter-spacing: 1px;\">QuickQL Query Syntax</span>';\n    html += '    </div>';\n    html += '    <div style=\"display: flex; gap: 12px; flex-wrap: wrap;\">';\n    html += '      <div class=\"mb-4\" style=\"flex: 1 1 100%; min-width: 0;\">';\n        html += '        <pre class=\"rounded-2 p-3 mb-1 font-monospace\" style=\"background: #0f172a; color: #e2e8f0; font-size: 12px; line-height: 1.7; overflow-x: auto; white-space: pre; margin: 0;\">users {\\n  id,\\n  username,\\n  email\\n}</pre>';\n    html += '        <div class=\"text-muted mt-1\" style=\"font-size: 11px;\"><i class=\"fas fa-arrow-right me-1\"></i>Select fields by name, comma-separated</div>';\n    html += '      </div>';\n    html += '      <div style=\"flex: 1 1 100%; min-width: 0;\">';\n        html += '        <pre class=\"rounded-2 p-3 mb-1 font-monospace\" style=\"background: #0f172a; color: #e2e8f0; font-size: 12px; line-height: 1.7; overflow-x: auto; white-space: pre; margin: 0;\">users {\\n  id,\\n  posts { id, title }\\n}</pre>';\n    html += '        <div class=\"text-muted mt-1\" style=\"font-size: 11px;\"><i class=\"fas fa-arrow-right me-1\"></i>Nest relation names inline for joins</div>';\n    html += '      </div>';\n    html += '    </div>';\n    html += '  </div>';\n\n    // Per-collection docs\n    schema.forEach((col, idx) => {\n        const colors = ['#3b82f6','#8b5cf6','#ec4899','#10b981','#f59e0b','#ef4444','#06b6d4'];\n        const accentColor = colors[idx % colors.length];\n\n        html += '<section id=\"doc-' + col.name + '\" class=\"mb-5\" style=\"scroll-margin-top: 24px;\">';\n\n        // Collection header\n        html += '  <div class=\"d-flex align-items-center gap-3 mb-3\">';\n        html += '    <div class=\"rounded-2 d-flex align-items-center justify-content-center flex-shrink-0\" style=\"width: 36px; height: 36px; background: ' + accentColor + '18;\">';\n        html += '      <i class=\"fas fa-table\" style=\"color: ' + accentColor + '; font-size: 14px;\"></i>';\n        html += '    </div>';\n        html += '    <div>';\n        html += '      <h2 class=\"fw-bold mb-0\" style=\"font-size: 22px; color: #0f172a;\">' + col.name + '</h2>';\n        html += '      <div class=\"text-muted\" style=\"font-size: 12px;\">' + col.fields.length + ' fields' + (col.relations && col.relations.length > 0 ? ' \u00B7 ' + col.relations.length + ' relation' + (col.relations.length > 1 ? 's' : '') : '') + '</div>';\n        html += '    </div>';\n        html += '    <button class=\"btn btn-sm ms-auto fw-bold px-3\" style=\"border: 1.5px solid ' + accentColor + '; color: ' + accentColor + '; border-radius: 8px; font-size: 12px;\" onclick=\"(window).setEditorTemplate(\\'' + col.name + '\\'); (window).switchView(\\'playground\\')\">';\n        html += '      <i class=\"fas fa-play me-1\" style=\"font-size: 10px;\"></i>Try in Playground';\n        html += '    </button>';\n        html += '  </div>';\n\n        html += '  <p class=\"text-muted mb-4\" style=\"font-size: 14px; line-height: 1.7;\">The <strong class=\"text-dark\">' + col.name + '</strong> collection stores records in your QuickQL data layer. Query it directly by name, select specific fields using comma-separated lists, and traverse relations by nesting collection names inline.</p>';\n\n        // Fields table\n        html += '  <div class=\"mb-4 rounded-2 overflow-hidden\" style=\"border: 1px solid #e2e8f0;\">';\n        html += '    <div class=\"px-4 py-3 d-flex align-items-center gap-2\" style=\"background: #f8fafc; border-bottom: 1px solid #e2e8f0;\">';\n        html += '      <i class=\"fas fa-list-ul text-muted\" style=\"font-size: 12px;\"></i>';\n        html += '      <span class=\"fw-bold text-muted text-uppercase\" style=\"font-size: 11px; letter-spacing: 1px;\">Fields</span>';\n        html += '    </div>';\n        html += '    <table class=\"w-100 m-0\" style=\"border-collapse: collapse; font-size: 13px;\">';\n        html += '      <thead>';\n        html += '        <tr style=\"background: #fafafa; border-bottom: 1px solid #f1f5f9;\">';\n        html += '          <th class=\"px-4 py-3 text-muted fw-bold text-uppercase\" style=\"font-size: 10px; letter-spacing: 1px; width: 30%;\">Field</th>';\n        html += '          <th class=\"px-4 py-3 text-muted fw-bold text-uppercase\" style=\"font-size: 10px; letter-spacing: 1px;\">Description</th>';\n        html += '          <th class=\"px-4 py-3 text-muted fw-bold text-uppercase\" style=\"font-size: 10px; letter-spacing: 1px; width: 100px; text-align: right;\">Type</th>';\n        html += '        </tr>';\n        html += '      </thead>';\n        html += '      <tbody>';\n        col.fields.forEach((f, fi) => {\n            const fName = f.toLowerCase();\n            const typeInfo = getTypeInfo(fName);\n            const desc = getFieldDesc(fName, col.name);\n            html += '<tr style=\"border-bottom: 1px solid #f8fafc; ' + (fi % 2 === 0 ? 'background: #fff;' : 'background: #fafafa;') + '\">';\n            html += '  <td class=\"px-4 py-3\"><code style=\"font-size: 13px; font-weight: 700; color: ' + accentColor + '; background: ' + accentColor + '10; padding: 2px 8px; border-radius: 4px; font-family: JetBrains Mono, monospace;\">' + f + '</code></td>';\n            html += '  <td class=\"px-4 py-3 text-muted\" style=\"line-height: 1.6;\">' + desc + '</td>';\n            html += '  <td class=\"px-4 py-3\" style=\"text-align: right;\"><span class=\"fw-bold\" style=\"font-size: 11px; padding: 3px 10px; border-radius: 100px; background: ' + typeInfo.bg + '; color: ' + typeInfo.color + ';\">' + typeInfo.label + '</span></td>';\n            html += '</tr>';\n        });\n        html += '      </tbody>';\n        html += '    </table>';\n        html += '  </div>';\n\n        // Relations block\n        if (col.relations && col.relations.length > 0) {\n            html += '  <div class=\"mb-4 rounded-2 overflow-hidden\" style=\"border: 1px solid #e2e8f0;\">';\n            html += '    <div class=\"px-4 py-3 d-flex align-items-center gap-2\" style=\"background: #f8fafc; border-bottom: 1px solid #e2e8f0;\">';\n            html += '      <i class=\"fas fa-code-branch text-muted\" style=\"font-size: 12px;\"></i>';\n            html += '      <span class=\"fw-bold text-muted text-uppercase\" style=\"font-size: 11px; letter-spacing: 1px;\">Relations</span>';\n            html += '    </div>';\n            col.relations.forEach(rel => {\n                html += '<div class=\"px-4 py-3 d-flex align-items-center justify-content-between\" style=\"border-bottom: 1px solid #f8fafc;\">';\n                html += '  <div class=\"d-flex align-items-center gap-3\">';\n                html += '    <div class=\"d-flex align-items-center justify-content-center rounded-2\" style=\"width: 28px; height: 28px; background: #eff6ff;\">';\n                html += '      <i class=\"fas fa-arrow-right text-primary\" style=\"font-size: 10px;\"></i>';\n                html += '    </div>';\n                html += '    <div>';\n                html += '      <div class=\"fw-bold text-dark\" style=\"font-size: 13px;\">' + rel.name + '</div>';\n                html += '      <div class=\"text-muted\" style=\"font-size: 11px;\">Points to \u2192 <strong>' + rel.target + '</strong> collection</div>';\n                html += '    </div>';\n                html += '  </div>';\n                html += '  <button class=\"btn btn-sm text-primary fw-bold p-0 text-decoration-none\" style=\"font-size: 12px;\" onclick=\"document.getElementById(\\'doc-' + rel.target + '\\')?.scrollIntoView({behavior:\\'smooth\\'})\">View ' + rel.target + ' \u2192</button>';\n                html += '</div>';\n            });\n            html += '  </div>';\n        }\n\n        // Sample query\n        html += '  <div class=\"mb-2\">';\n        html += '    <div class=\"fw-bold text-muted text-uppercase mb-2\" style=\"font-size: 11px; letter-spacing: 1px;\"><i class=\"fas fa-code me-1\"></i> Sample Query</div>';\n        html += '    <div class=\"rounded-2 overflow-hidden\" style=\"border: 1px solid #1e293b;\">';\n        html += '      <div class=\"px-4 py-2 d-flex align-items-center justify-content-between\" style=\"background: #1e293b;\">';\n        html += '        <span class=\"text-muted\" style=\"font-size: 11px; font-family: monospace;\">quickql \u00B7 ' + col.name.toLowerCase() + '</span>';\n        html += '        <button class=\"btn btn-sm p-0 fw-bold\" style=\"font-size: 11px; color: #94a3b8;\" onclick=\"(window).setEditorTemplate(\\'' + col.name + '\\'); (window).switchView(\\'playground\\')\">Copy to Editor \u2197</button>';\n        html += '      </div>';\n        html += '      <pre class=\"m-0 p-4 font-monospace\" style=\"background: #0f172a; color: #e2e8f0; font-size: 13px; line-height: 1.7;\">';\n        const sampleFields = col.fields.slice(0, Math.min(col.fields.length, 4)).join(',\\n  ');\n        html += col.name.toLowerCase() + ' {\\n  ' + sampleFields + '\\n}';\n        if (col.relations && col.relations.length > 0) {\n            html += '\\n\\n' + col.name.toLowerCase() + ' {\\n  id,\\n  ' + col.relations[0].name + ' {\\n    id\\n  }\\n}';\n        }\n        html += '</pre>';\n        html += '    </div>';\n        html += '  </div>';\n\n        html += '  <div style=\"margin: 40px 0; border-top: 1px solid #f1f5f9;\"></div>';\n        html += '</section>';\n    });\n\n    // Footer\n    html += '  <div class=\"text-center py-5\" style=\"opacity: 0.2;\">';\n    html += '    <img src=\"https://cdn-static.udinmo.com/content/logo/quickql.png\" style=\"height: 20px; filter: grayscale(1);\">';\n    html += '    <div class=\"mt-2 fw-bold text-uppercase\" style=\"font-size: 10px; letter-spacing: 3px;\">End of Reference</div>';\n    html += '  </div>';\n\n    html += '  </div>';\n    html += '</main>';\n    html += '</div>';\n\n    // Hover styles for sidebar nav items\n    setTimeout(() => {\n        document.querySelectorAll('.docs-nav-item').forEach(el => {\n            el.addEventListener('mouseenter', () => { el.style.background = '#f1f5f9'; });\n            el.addEventListener('mouseleave', () => { el.style.background = ''; });\n        });\n    }, 50);\n\n    return html;\n}\n";
+//# sourceMappingURL=docs.d.ts.map

package/dist/server/src/playground/docs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"docs.d.ts","sourceRoot":"","sources":["../../../../src/playground/docs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH;;GAEG;AACH,eAAO,MAAM,MAAM,62gBAgNlB,CAAC"}

package/dist/server/src/playground/docs.js

@@ -0,0 +1,223 @@
+/**
+ * QuickQL Documentation Generator
+ *
+ * Logic for generating real-time, interactive API documentation
+ * from the server's processed schema metadata.
+ *
+ * (c) 2024-2026 Udinmo Inc. All rights reserved.
+ * Author: Udinmo Inc. <engineering@udinmo.com>
+ * License: MIT
+ */
+/**
+ * Documentation Generator for QuickQL Playground
+ */
+export const docsJs = `
+function renderDocsPage() {
+    const schema = (window).currentSchema || [];
+    if (schema.length === 0) {
+        return '<div class="p-5 text-center text-muted"><div class="mb-3" style="font-size: 48px; opacity: 0.15;"><i class="fas fa-book-open"></i></div><h4 class="fw-bold">No Schema Loaded</h4><p class="text-muted">Navigate to a collection or refresh to load schema metadata.</p></div>';
+    }
+
+    // --- Helper: infer type badge ---
+    function getTypeInfo(fName) {
+        if (fName === 'id' || fName.endsWith('_id')) return { label: 'ID', color: '#7c3aed', bg: '#ede9fe' };
+        if (fName === 'email') return { label: 'Email', color: '#0891b2', bg: '#e0f2fe' };
+        if (fName === 'created_at' || fName === 'updated_at' || fName.endsWith('_at')) return { label: 'DateTime', color: '#d97706', bg: '#fef3c7' };
+        if (fName.startsWith('is_') || fName.startsWith('has_') || fName === 'active' || fName === 'enabled') return { label: 'Boolean', color: '#059669', bg: '#d1fae5' };
+        if (fName.includes('count') || fName === 'age' || fName === 'total' || fName.includes('amount') || fName.includes('price')) return { label: 'Number', color: '#dc2626', bg: '#fee2e2' };
+        if (fName === 'password' || fName === 'token' || fName === 'secret') return { label: 'Hash', color: '#64748b', bg: '#f1f5f9' };
+        if (fName.includes('url') || fName.includes('image') || fName.includes('avatar') || fName.includes('link')) return { label: 'URL', color: '#6366f1', bg: '#eef2ff' };
+        return { label: 'String', color: '#475569', bg: '#f8fafc' };
+    }
+
+    function getFieldDesc(fName, colName) {
+        if (fName === 'id') return 'Primary key. Unique record identifier — used for targeted lookups and as a foreign key reference in relations.';
+        if (fName.endsWith('_id')) return 'Foreign key reference to a related <strong>' + fName.replace('_id','') + '</strong> record.';
+        if (fName === 'email') return 'Email address. Used for authentication and contact. Must be a valid RFC 5321 format.';
+        if (fName.includes('name')) return 'Human-readable display name or label for the <strong>' + colName + '</strong> record.';
+        if (fName === 'created_at') return 'Timestamp of when this record was first persisted. Set automatically by the system.';
+        if (fName === 'updated_at') return 'Timestamp of the last modification. Automatically updated on every write operation.';
+        if (fName === 'password') return 'Hashed credential string. Never returned in plain text — always stored using a one-way hash.';
+        if (fName.startsWith('is_')) return 'Boolean flag. Indicates whether the <em>' + fName.replace('is_','') + '</em> condition is true for this record.';
+        if (fName.startsWith('has_')) return 'Boolean flag. Indicates presence or availability of <em>' + fName.replace('has_','') + '</em>.';
+        if (fName.includes('count')) return 'Aggregate counter. Denormalized value tracking the number of related sub-items.';
+        if (fName.includes('url') || fName.includes('image') || fName.includes('avatar')) return 'URL pointing to an external or stored resource. Should be a fully qualified URI.';
+        if (fName.includes('amount') || fName.includes('price') || fName.includes('total')) return 'Monetary or numeric value. Stored as a fixed-precision number to avoid floating-point errors.';
+        return 'Data attribute on <strong>' + colName + '</strong>. Stores domain-specific information for this field.';
+    }
+
+    let html = '';
+    html += '<div class="d-flex h-100 bg-white" style="min-width: 0;">';
+
+    // --- Left nav sidebar ---
+    html += '<aside class="flex-shrink-0 border-end d-flex flex-column" style="width: 190px; overflow-y: auto; background: #fafafa;">';
+    html += '  <div class="px-4 pt-4 pb-3 border-bottom bg-white">';
+    html += '    <div class="text-uppercase fw-bold text-muted mb-1" style="font-size: 10px; letter-spacing: 2px;">Collections</div>';
+    html += '    <div class="text-muted" style="font-size: 11px;">' + schema.length + ' collection' + (schema.length !== 1 ? 's' : '') + ' detected</div>';
+    html += '  </div>';
+    html += '  <div class="py-2">';
+    schema.forEach((col, idx) => {
+        const colors = ['#3b82f6','#8b5cf6','#ec4899','#10b981','#f59e0b','#ef4444','#06b6d4'];
+        const c = colors[idx % colors.length];
+        html += '<a href="#doc-' + col.name + '" class="d-flex align-items-center gap-3 px-4 py-2 text-decoration-none docs-nav-item" style="color: #374151; font-size: 13px; font-weight: 600; transition: background 0.15s;">';
+        html += '  <span style="width: 8px; height: 8px; border-radius: 50%; background: ' + c + '; flex-shrink: 0; display: inline-block;"></span>';
+        html += '  <span>' + col.name + '</span>';
+        html += '  <span class="ms-auto text-muted fw-normal" style="font-size: 11px;">' + col.fields.length + 'f</span>';
+        html += '</a>';
+    });
+    html += '  </div>';
+    html += '</aside>';
+
+    // --- Main docs body ---
+    html += '<main class="flex-grow-1 overflow-auto" style="min-width: 0; background: #fff;">';
+    html += '  <div class="mx-auto" style="max-width: 900px; padding: 28px 24px;">';
+
+    // Header
+    html += '  <div class="mb-4 pb-3 border-bottom">';
+    html += '    <div class="d-flex align-items-start justify-content-between">';
+    html += '      <div>';
+    html += '        <h1 class="fw-bold mb-1" style="font-size: 22px; letter-spacing: -0.5px;">API Reference</h1>';
+    html += '        <p class="text-muted mb-0" style="font-size: 13px;">Auto-generated docs for your QuickQL schema. Uses the QuickQL native query language.</p>';
+    html += '      </div>';
+    html += '      <span class="badge px-3 py-2 ms-3 flex-shrink-0" style="background: #d1fae5; color: #065f46; font-size: 10px; border-radius: 100px; font-weight: 700;">● LIVE</span>';
+    html += '    </div>';
+    html += '  </div>';
+
+    // Query Syntax intro box
+    html += '  <div class="mb-4 p-3 rounded-2" style="background: #f8fafc; border: 1px solid #e2e8f0;">';
+    html += '    <div class="d-flex align-items-center gap-2 mb-2">';
+    html += '      <i class="fas fa-terminal text-primary" style="font-size: 11px;"></i>';
+    html += '      <span class="fw-bold text-dark" style="font-size: 11px; text-transform: uppercase; letter-spacing: 1px;">QuickQL Query Syntax</span>';
+    html += '    </div>';
+    html += '    <div style="display: flex; gap: 12px; flex-wrap: wrap;">';
+    html += '      <div class="mb-4" style="flex: 1 1 100%; min-width: 0;">';
+        html += '        <pre class="rounded-2 p-3 mb-1 font-monospace" style="background: #0f172a; color: #e2e8f0; font-size: 12px; line-height: 1.7; overflow-x: auto; white-space: pre; margin: 0;">users {\\n  id,\\n  username,\\n  email\\n}</pre>';
+    html += '        <div class="text-muted mt-1" style="font-size: 11px;"><i class="fas fa-arrow-right me-1"></i>Select fields by name, comma-separated</div>';
+    html += '      </div>';
+    html += '      <div style="flex: 1 1 100%; min-width: 0;">';
+        html += '        <pre class="rounded-2 p-3 mb-1 font-monospace" style="background: #0f172a; color: #e2e8f0; font-size: 12px; line-height: 1.7; overflow-x: auto; white-space: pre; margin: 0;">users {\\n  id,\\n  posts { id, title }\\n}</pre>';
+    html += '        <div class="text-muted mt-1" style="font-size: 11px;"><i class="fas fa-arrow-right me-1"></i>Nest relation names inline for joins</div>';
+    html += '      </div>';
+    html += '    </div>';
+    html += '  </div>';
+
+    // Per-collection docs
+    schema.forEach((col, idx) => {
+        const colors = ['#3b82f6','#8b5cf6','#ec4899','#10b981','#f59e0b','#ef4444','#06b6d4'];
+        const accentColor = colors[idx % colors.length];
+
+        html += '<section id="doc-' + col.name + '" class="mb-5" style="scroll-margin-top: 24px;">';
+
+        // Collection header
+        html += '  <div class="d-flex align-items-center gap-3 mb-3">';
+        html += '    <div class="rounded-2 d-flex align-items-center justify-content-center flex-shrink-0" style="width: 36px; height: 36px; background: ' + accentColor + '18;">';
+        html += '      <i class="fas fa-table" style="color: ' + accentColor + '; font-size: 14px;"></i>';
+        html += '    </div>';
+        html += '    <div>';
+        html += '      <h2 class="fw-bold mb-0" style="font-size: 22px; color: #0f172a;">' + col.name + '</h2>';
+        html += '      <div class="text-muted" style="font-size: 12px;">' + col.fields.length + ' fields' + (col.relations && col.relations.length > 0 ? ' · ' + col.relations.length + ' relation' + (col.relations.length > 1 ? 's' : '') : '') + '</div>';
+        html += '    </div>';
+        html += '    <button class="btn btn-sm ms-auto fw-bold px-3" style="border: 1.5px solid ' + accentColor + '; color: ' + accentColor + '; border-radius: 8px; font-size: 12px;" onclick="(window).setEditorTemplate(\\'' + col.name + '\\'); (window).switchView(\\'playground\\')">';
+        html += '      <i class="fas fa-play me-1" style="font-size: 10px;"></i>Try in Playground';
+        html += '    </button>';
+        html += '  </div>';
+
+        html += '  <p class="text-muted mb-4" style="font-size: 14px; line-height: 1.7;">The <strong class="text-dark">' + col.name + '</strong> collection stores records in your QuickQL data layer. Query it directly by name, select specific fields using comma-separated lists, and traverse relations by nesting collection names inline.</p>';
+
+        // Fields table
+        html += '  <div class="mb-4 rounded-2 overflow-hidden" style="border: 1px solid #e2e8f0;">';
+        html += '    <div class="px-4 py-3 d-flex align-items-center gap-2" style="background: #f8fafc; border-bottom: 1px solid #e2e8f0;">';
+        html += '      <i class="fas fa-list-ul text-muted" style="font-size: 12px;"></i>';
+        html += '      <span class="fw-bold text-muted text-uppercase" style="font-size: 11px; letter-spacing: 1px;">Fields</span>';
+        html += '    </div>';
+        html += '    <table class="w-100 m-0" style="border-collapse: collapse; font-size: 13px;">';
+        html += '      <thead>';
+        html += '        <tr style="background: #fafafa; border-bottom: 1px solid #f1f5f9;">';
+        html += '          <th class="px-4 py-3 text-muted fw-bold text-uppercase" style="font-size: 10px; letter-spacing: 1px; width: 30%;">Field</th>';
+        html += '          <th class="px-4 py-3 text-muted fw-bold text-uppercase" style="font-size: 10px; letter-spacing: 1px;">Description</th>';
+        html += '          <th class="px-4 py-3 text-muted fw-bold text-uppercase" style="font-size: 10px; letter-spacing: 1px; width: 100px; text-align: right;">Type</th>';
+        html += '        </tr>';
+        html += '      </thead>';
+        html += '      <tbody>';
+        col.fields.forEach((f, fi) => {
+            const fName = f.toLowerCase();
+            const typeInfo = getTypeInfo(fName);
+            const desc = getFieldDesc(fName, col.name);
+            html += '<tr style="border-bottom: 1px solid #f8fafc; ' + (fi % 2 === 0 ? 'background: #fff;' : 'background: #fafafa;') + '">';
+            html += '  <td class="px-4 py-3"><code style="font-size: 13px; font-weight: 700; color: ' + accentColor + '; background: ' + accentColor + '10; padding: 2px 8px; border-radius: 4px; font-family: JetBrains Mono, monospace;">' + f + '</code></td>';
+            html += '  <td class="px-4 py-3 text-muted" style="line-height: 1.6;">' + desc + '</td>';
+            html += '  <td class="px-4 py-3" style="text-align: right;"><span class="fw-bold" style="font-size: 11px; padding: 3px 10px; border-radius: 100px; background: ' + typeInfo.bg + '; color: ' + typeInfo.color + ';">' + typeInfo.label + '</span></td>';
+            html += '</tr>';
+        });
+        html += '      </tbody>';
+        html += '    </table>';
+        html += '  </div>';
+
+        // Relations block
+        if (col.relations && col.relations.length > 0) {
+            html += '  <div class="mb-4 rounded-2 overflow-hidden" style="border: 1px solid #e2e8f0;">';
+            html += '    <div class="px-4 py-3 d-flex align-items-center gap-2" style="background: #f8fafc; border-bottom: 1px solid #e2e8f0;">';
+            html += '      <i class="fas fa-code-branch text-muted" style="font-size: 12px;"></i>';
+            html += '      <span class="fw-bold text-muted text-uppercase" style="font-size: 11px; letter-spacing: 1px;">Relations</span>';
+            html += '    </div>';
+            col.relations.forEach(rel => {
+                html += '<div class="px-4 py-3 d-flex align-items-center justify-content-between" style="border-bottom: 1px solid #f8fafc;">';
+                html += '  <div class="d-flex align-items-center gap-3">';
+                html += '    <div class="d-flex align-items-center justify-content-center rounded-2" style="width: 28px; height: 28px; background: #eff6ff;">';
+                html += '      <i class="fas fa-arrow-right text-primary" style="font-size: 10px;"></i>';
+                html += '    </div>';
+                html += '    <div>';
+                html += '      <div class="fw-bold text-dark" style="font-size: 13px;">' + rel.name + '</div>';
+                html += '      <div class="text-muted" style="font-size: 11px;">Points to → <strong>' + rel.target + '</strong> collection</div>';
+                html += '    </div>';
+                html += '  </div>';
+                html += '  <button class="btn btn-sm text-primary fw-bold p-0 text-decoration-none" style="font-size: 12px;" onclick="document.getElementById(\\'doc-' + rel.target + '\\')?.scrollIntoView({behavior:\\'smooth\\'})">View ' + rel.target + ' →</button>';
+                html += '</div>';
+            });
+            html += '  </div>';
+        }
+
+        // Sample query
+        html += '  <div class="mb-2">';
+        html += '    <div class="fw-bold text-muted text-uppercase mb-2" style="font-size: 11px; letter-spacing: 1px;"><i class="fas fa-code me-1"></i> Sample Query</div>';
+        html += '    <div class="rounded-2 overflow-hidden" style="border: 1px solid #1e293b;">';
+        html += '      <div class="px-4 py-2 d-flex align-items-center justify-content-between" style="background: #1e293b;">';
+        html += '        <span class="text-muted" style="font-size: 11px; font-family: monospace;">quickql · ' + col.name.toLowerCase() + '</span>';
+        html += '        <button class="btn btn-sm p-0 fw-bold" style="font-size: 11px; color: #94a3b8;" onclick="(window).setEditorTemplate(\\'' + col.name + '\\'); (window).switchView(\\'playground\\')">Copy to Editor ↗</button>';
+        html += '      </div>';
+        html += '      <pre class="m-0 p-4 font-monospace" style="background: #0f172a; color: #e2e8f0; font-size: 13px; line-height: 1.7;">';
+        const sampleFields = col.fields.slice(0, Math.min(col.fields.length, 4)).join(',\\n  ');
+        html += col.name.toLowerCase() + ' {\\n  ' + sampleFields + '\\n}';
+        if (col.relations && col.relations.length > 0) {
+            html += '\\n\\n' + col.name.toLowerCase() + ' {\\n  id,\\n  ' + col.relations[0].name + ' {\\n    id\\n  }\\n}';
+        }
+        html += '</pre>';
+        html += '    </div>';
+        html += '  </div>';
+
+        html += '  <div style="margin: 40px 0; border-top: 1px solid #f1f5f9;"></div>';
+        html += '</section>';
+    });
+
+    // Footer
+    html += '  <div class="text-center py-5" style="opacity: 0.2;">';
+    html += '    <img src="https://cdn-static.udinmo.com/content/logo/quickql.png" style="height: 20px; filter: grayscale(1);">';
+    html += '    <div class="mt-2 fw-bold text-uppercase" style="font-size: 10px; letter-spacing: 3px;">End of Reference</div>';
+    html += '  </div>';
+
+    html += '  </div>';
+    html += '</main>';
+    html += '</div>';
+
+    // Hover styles for sidebar nav items
+    setTimeout(() => {
+        document.querySelectorAll('.docs-nav-item').forEach(el => {
+            el.addEventListener('mouseenter', () => { el.style.background = '#f1f5f9'; });
+            el.addEventListener('mouseleave', () => { el.style.background = ''; });
+        });
+    }, 50);
+
+    return html;
+}
+`;
+//# sourceMappingURL=docs.js.map

package/dist/server/src/playground/docs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"docs.js","sourceRoot":"","sources":["../../../../src/playground/docs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH;;GAEG;AACH,MAAM,CAAC,MAAM,MAAM,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAgNrB,CAAC"}

package/dist/server/src/playground/html.d.ts

@@ -0,0 +1,20 @@
+/**
+ * QuickQL Playground HTML
+ *
+ * Provides the main HTML shell for the QuickQL Console/Playground,
+ * integrating CDN-based assets for maximum performance and light bundle size.
+ *
+ * (c) 2024-2026 Udinmo Inc. All rights reserved.
+ * Author: Udinmo Inc. <engineering@udinmo.com>
+ * License: MIT
+ */
+export interface PlaygroundOptions {
+    endpoint: string;
+    debug?: boolean;
+}
+/**
+ * Renders the HTML shell for the QuickQL Playground.
+ * Loads core assets (JS/CSS) from the official CDN to keep the server package lightweight.
+ */
+export declare function renderPlayground(options: PlaygroundOptions): string;
+//# sourceMappingURL=html.d.ts.map

package/dist/server/src/playground/html.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"html.d.ts","sourceRoot":"","sources":["../../../../src/playground/html.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,iBAAiB,GAAG,MAAM,CAmCnE"}

package/dist/server/src/playground/html.js

@@ -0,0 +1,50 @@
+/**
+ * QuickQL Playground HTML
+ *
+ * Provides the main HTML shell for the QuickQL Console/Playground,
+ * integrating CDN-based assets for maximum performance and light bundle size.
+ *
+ * (c) 2024-2026 Udinmo Inc. All rights reserved.
+ * Author: Udinmo Inc. <engineering@udinmo.com>
+ * License: MIT
+ */
+/**
+ * Renders the HTML shell for the QuickQL Playground.
+ * Loads core assets (JS/CSS) from the official CDN to keep the server package lightweight.
+ */
+export function renderPlayground(options) {
+    const cdnBase = 'https://cdn-static.udinmo.com/qucikql';
+    return `
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>QuickQL Console</title>
+    <!-- External & CDN Assets -->
+    <link rel="stylesheet" href="https://cdn-static.udinmo.com/@static/css/bootstrap.min.css" crossorigin="anonymous">
+    <link rel="stylesheet" href="https://cdn-static.udinmo.com/@static/css/awesome/css/all.min.css" crossorigin="anonymous">
+    <link rel="stylesheet" href="${cdnBase}/playground.css" crossorigin="anonymous">
+    <script src="https://cdn-static.udinmo.com/@static/js/bootstrap.bundle.min.js" crossorigin="anonymous"></script>
+</head>
+<body>
+    <div id="app">
+        <!-- Initial Loader -->
+        <div style="height: 100vh; width: 100vw; display: flex; align-items: center; justify-content: center; background: #0d1117">
+             <div style="border: 4px solid rgba(255, 255, 255, 0.1); border-top: 4px solid #3b82f6; border-radius: 50%; width: 40px; height: 40px; animation: spin 1s linear infinite"></div>
+        </div>
+        <style>@keyframes spin { 0% { transform: rotate(0deg) } 100% { transform: rotate(360deg) } }</style>
+    </div>
+    <script>
+        window.QuickQLConfig = {
+            endpoint: '${options.endpoint}',
+            debug: ${options.debug || false}
+        };
+    </script>
+    <!-- CDN Logic -->
+    <script src="${cdnBase}/playground.js" crossorigin="anonymous"></script>
+</body>
+</html>
+  `.trim();
+}
+//# sourceMappingURL=html.js.map

package/dist/server/src/playground/html.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"html.js","sourceRoot":"","sources":["../../../../src/playground/html.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAOH;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAA0B;IACzD,MAAM,OAAO,GAAG,uCAAuC,CAAC;IAExD,OAAO;;;;;;;;;;mCAU0B,OAAO;;;;;;;;;;;;;yBAajB,OAAO,CAAC,QAAQ;qBACpB,OAAO,CAAC,KAAK,IAAI,KAAK;;;;mBAIxB,OAAO;;;GAGvB,CAAC,IAAI,EAAE,CAAC;AACX,CAAC"}

package/dist/server/src/plugins/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * QuickQL Standard Plugins
+ *
+ * Collection of built-in hooks for audit logging, result minification,
+ * and other common server-side middleware.
+ *
+ * (c) 2024-2026 Udinmo Inc. All rights reserved.
+ * Author: Udinmo Inc. <engineering@udinmo.com>
+ * License: MIT
+ */
+import { QuickQLPlugin } from '../types';
+/**
+ * Standard Audit Logging Plugin for Security and Compliance.
+ */
+export declare const AuditLogPlugin: QuickQLPlugin;
+/**
+ * Intelligent Response Minification Plugin.
+ * Automatically strips nulls or internal keys to reduce bandwidth.
+ */
+export declare const MinifyResponsePlugin: QuickQLPlugin;
+//# sourceMappingURL=index.d.ts.map

package/dist/server/src/plugins/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/plugins/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,EAAE,aAAa,EAAwB,MAAM,UAAU,CAAC;AAE/D;;GAEG;AACH,eAAO,MAAM,cAAc,EAAE,aAK5B,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,oBAAoB,EAAE,aAalC,CAAC"}

package/dist/server/src/plugins/index.js

@@ -0,0 +1,38 @@
+/**
+ * QuickQL Standard Plugins
+ *
+ * Collection of built-in hooks for audit logging, result minification,
+ * and other common server-side middleware.
+ *
+ * (c) 2024-2026 Udinmo Inc. All rights reserved.
+ * Author: Udinmo Inc. <engineering@udinmo.com>
+ * License: MIT
+ */
+/**
+ * Standard Audit Logging Plugin for Security and Compliance.
+ */
+export const AuditLogPlugin = {
+    name: 'audit-log',
+    onMutation: async (mutation, ctx) => {
+        console.log(`[AUDIT] Mutation: ${mutation.type} in ${mutation.collection} by ${ctx.user?.id || 'anonymous'}`);
+    }
+};
+/**
+ * Intelligent Response Minification Plugin.
+ * Automatically strips nulls or internal keys to reduce bandwidth.
+ */
+export const MinifyResponsePlugin = {
+    name: 'minify-response',
+    afterQuery: async (results) => {
+        return results.map(row => {
+            const cleaned = {};
+            for (const [k, v] of Object.entries(row)) {
+                if (v !== null && v !== undefined && k !== '_internal') {
+                    cleaned[k] = v;
+                }
+            }
+            return cleaned;
+        });
+    }
+};
+//# sourceMappingURL=index.js.map

package/dist/server/src/plugins/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/plugins/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAKH;;GAEG;AACH,MAAM,CAAC,MAAM,cAAc,GAAkB;IAC3C,IAAI,EAAE,WAAW;IACjB,UAAU,EAAE,KAAK,EAAE,QAAkB,EAAE,GAAyB,EAAE,EAAE;QAClE,OAAO,CAAC,GAAG,CAAC,qBAAqB,QAAQ,CAAC,IAAI,OAAO,QAAQ,CAAC,UAAU,OAAO,GAAG,CAAC,IAAI,EAAE,EAAE,IAAI,WAAW,EAAE,CAAC,CAAC;IAChH,CAAC;CACF,CAAC;AAEF;;;GAGG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAkB;IACjD,IAAI,EAAE,iBAAiB;IACvB,UAAU,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE;QAC5B,OAAO,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE;YACrB,MAAM,OAAO,GAAQ,EAAE,CAAC;YACxB,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;gBACvC,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,SAAS,IAAI,CAAC,KAAK,WAAW,EAAE,CAAC;oBACrD,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;gBACnB,CAAC;YACL,CAAC;YACD,OAAO,OAAO,CAAC;QACnB,CAAC,CAAC,CAAC;IACL,CAAC;CACF,CAAC"}

package/dist/server/src/relations.d.ts

@@ -0,0 +1,22 @@
+/**
+ * QuickQL Relation Engine
+ *
+ * Optimized engine for resolving and mapping nested data relations
+ * while maintaining high performance and preventing N+1 problems.
+ *
+ * (c) 2024-2026 Udinmo Inc. All rights reserved.
+ * Author: Udinmo Inc. <engineering@udinmo.com>
+ * License: MIT
+ */
+import { Query } from '@quickql/core';
+import { SchemaConfig, ServerFeatures } from './types';
+export declare class RelationEngine {
+    private schema;
+    private executeQueryRef;
+    private features;
+    constructor(schema: SchemaConfig, executeQueryRef: (query: Query, depth: number) => Promise<any[]>, features?: ServerFeatures);
+    resolve(items: any[], include: {
+        [key: string]: Partial<Query>;
+    }, relations: any, depth: number): Promise<any[]>;
+}
+//# sourceMappingURL=relations.d.ts.map

package/dist/server/src/relations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relations.d.ts","sourceRoot":"","sources":["../../../src/relations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,KAAK,EAAE,MAAM,eAAe,CAAC;AACtC,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAEvD,qBAAa,cAAc;IAEvB,OAAO,CAAC,MAAM;IACd,OAAO,CAAC,eAAe;IACvB,OAAO,CAAC,QAAQ;gBAFR,MAAM,EAAE,YAAY,EACpB,eAAe,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,GAAG,EAAE,CAAC,EAChE,QAAQ,GAAE,cAAiD;IAG/D,OAAO,CACX,KAAK,EAAE,GAAG,EAAE,EACZ,OAAO,EAAE;QAAE,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,CAAA;KAAE,EAC1C,SAAS,EAAE,GAAG,EACd,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,GAAG,EAAE,CAAC;CAwFlB"}

package/dist/server/src/relations.js

@@ -0,0 +1,98 @@
+/**
+ * QuickQL Relation Engine
+ *
+ * Optimized engine for resolving and mapping nested data relations
+ * while maintaining high performance and preventing N+1 problems.
+ *
+ * (c) 2024-2026 Udinmo Inc. All rights reserved.
+ * Author: Udinmo Inc. <engineering@udinmo.com>
+ * License: MIT
+ */
+export class RelationEngine {
+    schema;
+    executeQueryRef;
+    features;
+    constructor(schema, executeQueryRef, features = { smartRelationDiscovery: true }) {
+        this.schema = schema;
+        this.executeQueryRef = executeQueryRef;
+        this.features = features;
+    }
+    async resolve(items, include, relations, depth) {
+        const newItems = [...items];
+        for (const [relationKey, relationQuery] of Object.entries(include)) {
+            let relationDef = relations[relationKey];
+            // Smart Discovery: If relation is missing, try to infer it from field naming conventions
+            if (!relationDef && this.features.smartRelationDiscovery) {
+                const parentItems = items[0];
+                if (!parentItems)
+                    continue;
+                // Try user_id -> user or userId -> user
+                const possibleKeys = [`${relationKey}Id`, `${relationKey}_id`, `${relationKey}`];
+                const localKey = possibleKeys.find(k => k in parentItems);
+                if (localKey) {
+                    // Guess target collection (singular or plural)
+                    const target = [relationKey, `${relationKey}s`, `${relationKey}es`].find(t => this.schema[t]);
+                    if (target) {
+                        relationDef = {
+                            from: target,
+                            localKey,
+                            foreignKey: 'id', // Default to 'id' for target
+                            isSingle: true // Default to single for inferred child relations
+                        };
+                        console.warn(`\x1b[33m[QuickQL][SmartDiscovery]\x1b[0m Inferred relation: '${relationKey}' -> '${target}' via field '${localKey}'`);
+                    }
+                }
+            }
+            if (!relationDef)
+                continue;
+            const targetCollection = this.schema[relationDef.from];
+            if (!targetCollection)
+                continue;
+            // Group local keys to avoid redundant queries (Optimizing N+1 problem)
+            const localKeys = [...new Set(items.map(item => item[relationDef.localKey]).filter(Boolean))];
+            if (localKeys.length === 0)
+                continue;
+            // Execute a single query for the entire batch of parent items
+            const select = relationQuery.select ? [...relationQuery.select] : undefined;
+            // ALWAYS include the foreign key in the sub-query, otherwise we can't map it back!
+            if (select && !select.includes(relationDef.foreignKey)) {
+                select.push(relationDef.foreignKey);
+            }
+            const fullRelationQuery = {
+                ...relationQuery,
+                from: relationDef.from,
+                select,
+                where: {
+                    [relationDef.foreignKey]: { in: localKeys }
+                }
+            };
+            const relatedData = await this.executeQueryRef(fullRelationQuery, depth + 1);
+            // --- HIGHLY OPTIMIZED MAPPING SYSTEM ---
+            // Use a Map for O(1) lookups instead of O(N) filter in a loop
+            const lookupMap = new Map();
+            for (const rd of relatedData) {
+                const key = rd[relationDef.foreignKey];
+                if (!lookupMap.has(key))
+                    lookupMap.set(key, []);
+                lookupMap.get(key).push(rd);
+            }
+            const originalSelect = relationQuery.select;
+            const shouldClean = originalSelect && !originalSelect.includes(relationDef.foreignKey);
+            for (const item of newItems) {
+                const localKeyValue = item[relationDef.localKey];
+                const matches = lookupMap.get(localKeyValue) || [];
+                // 2. Clean up unrequested fields from the matches
+                const finalMatches = shouldClean
+                    ? matches.map(rd => {
+                        const clean = { ...rd };
+                        delete clean[relationDef.foreignKey];
+                        return clean;
+                    })
+                    : matches;
+                item[relationKey] = relationDef.isSingle ? (finalMatches[0] || null) : finalMatches;
+            }
+        }
+        return newItems;
+    }
+}
+//# sourceMappingURL=relations.js.map

package/dist/server/src/relations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"relations.js","sourceRoot":"","sources":["../../../src/relations.ts"],"names":[],"mappings":"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"}

package/dist/server/src/resolver/generator.d.ts

@@ -0,0 +1,25 @@
+/**
+ * QuickQL Resolver Generator
+ *
+ * Automated resolver generation for ORM-backed collections (Prisma, etc.),
+ * bridging the gap between QuickQL queries and native database operations.
+ *
+ * (c) 2024-2026 Udinmo Inc. All rights reserved.
+ * Author: Udinmo Inc. <engineering@udinmo.com>
+ * License: MIT
+ */
+import { Query, Mutation } from '@quickql/core';
+import { CollectionDefinition, QuickQLServerContext } from '../schema/types';
+export declare class ResolverGenerator {
+    /**
+     * Generates a single Prisma-backed resolver for a given collection.
+     * Handles findMany and findUnique operations.
+     */
+    static generateResolver(collection: CollectionDefinition): (query: Query, ctx: QuickQLServerContext) => Promise<any>;
+    /**
+     * Generates an automatic Prisma mutation resolver for a collection.
+     * Supports create, update, and delete actions.
+     */
+    static generateMutationResolver(collection: CollectionDefinition): (mutation: Mutation, ctx: QuickQLServerContext) => Promise<any>;
+}
+//# sourceMappingURL=generator.d.ts.map

package/dist/server/src/resolver/generator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generator.d.ts","sourceRoot":"","sources":["../../../../src/resolver/generator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAG7E,qBAAa,iBAAiB;IAC5B;;;OAGG;IACH,MAAM,CAAC,gBAAgB,CAAC,UAAU,EAAE,oBAAoB,WAGjC,KAAK,OAAO,oBAAoB;IAkBvD;;;OAGG;IACH,MAAM,CAAC,wBAAwB,CAAC,UAAU,EAAE,oBAAoB,cAGtC,QAAQ,OAAO,oBAAoB;CA4B9D"}