@storion/storion 1.0.0

package/dist/index.js

@@ -0,0 +1,26 @@
+/**
+ * storion – Framework-agnostic client-side database.
+ * Use with React, Vue, Angular, or vanilla JS.
+ */
+
+import { createDatabase, loadConfigFromUrl, loadConfigFromFile } from './Database.js';
+import { getStorageAdapter } from './storage/adapters.js';
+import { executeQuery, validateQuery, QUERY_OPERATORS } from './queryEngine.js';
+import { parseConfig, normalizeColumn, getColumnNames, getColumnType, coerceValue } from './schema.js';
+import { createChangeListener } from './changeListener.js';
+
+export {
+  createDatabase,
+  loadConfigFromUrl,
+  loadConfigFromFile,
+  getStorageAdapter,
+  executeQuery,
+  validateQuery,
+  QUERY_OPERATORS,
+  parseConfig,
+  normalizeColumn,
+  getColumnNames,
+  getColumnType,
+  coerceValue,
+  createChangeListener
+};

package/dist/queryEngine.js

@@ -0,0 +1,299 @@
+/**
+ * Query Engine - JSON query language for filtering and sorting table data.
+ * Framework-agnostic; no DOM or storage dependencies.
+ */
+
+const COLUMN_TYPES = ['int', 'float', 'boolean', 'string', 'json'];
+
+export const QUERY_OPERATORS = [
+  'eq', 'ne', 'gt', 'gte', 'lt', 'lte',
+  'contains', 'startsWith', 'endsWith',
+  'in', 'notIn', 'isNull', 'isNotNull'
+];
+
+function getColName(col) {
+  if (typeof col === 'string') return col;
+  if (col && typeof col === 'object' && col.name) return col.name;
+  return null;
+}
+
+function getColumnType(columns, colName) {
+  if (!Array.isArray(columns)) return 'string';
+  const col = columns.find(c => getColName(c) === colName);
+  if (!col) return 'string';
+  return typeof col === 'string' ? 'string' : (col.type || 'string');
+}
+
+function coerceValue(value, type) {
+  if (value === null || value === undefined || value === '') {
+    return type === 'boolean' ? false : null;
+  }
+  switch (type) {
+    case 'int': {
+      const i = parseInt(value, 10);
+      return isNaN(i) ? null : i;
+    }
+    case 'float': {
+      const f = parseFloat(value);
+      return isNaN(f) ? null : f;
+    }
+    case 'boolean':
+      if (typeof value === 'boolean') return value;
+      return String(value).toLowerCase() === 'true' || String(value).toLowerCase() === '1' || String(value).toLowerCase() === 'yes';
+    case 'json':
+      if (typeof value === 'object') return value;
+      if (typeof value === 'string') {
+        try {
+          return JSON.parse(value);
+        } catch {
+          return value;
+        }
+      }
+      return value;
+    case 'string':
+    default:
+      return String(value);
+  }
+}
+
+function getRowValue(row, field) {
+  if (!row || typeof row !== 'object') return null;
+  if (!Object.prototype.hasOwnProperty.call(row, field)) return null;
+  return row[field];
+}
+
+export function validateQuery(query, columns) {
+  if (query == null || typeof query !== 'object') {
+    return { valid: true };
+  }
+
+  const colNames = Array.isArray(columns)
+    ? columns.map(c => getColName(c)).filter(Boolean)
+    : [];
+
+  function checkField(field, context) {
+    if (typeof field !== 'string' || !field.trim()) {
+      return `Invalid or missing field in ${context}`;
+    }
+    if (!colNames.includes(field)) {
+      return `Unknown column: ${field}`;
+    }
+    return null;
+  }
+
+  function validateWhere(where, depth) {
+    if (where == null) return null;
+    if (depth > 50) return 'Where clause too deeply nested';
+
+    if (Array.isArray(where.and)) {
+      for (const item of where.and) {
+        const err = validateWhere(item, depth + 1);
+        if (err) return err;
+      }
+      return null;
+    }
+    if (Array.isArray(where.or)) {
+      for (const item of where.or) {
+        const err = validateWhere(item, depth + 1);
+        if (err) return err;
+      }
+      return null;
+    }
+
+    if (where.field != null) {
+      const err = checkField(where.field, 'where');
+      if (err) return err;
+      const op = where.op;
+      if (typeof op !== 'string' || !QUERY_OPERATORS.includes(op)) {
+        return `Invalid operator: ${op}. Allowed: ${QUERY_OPERATORS.join(', ')}`;
+      }
+      if ((op === 'in' || op === 'notIn') && !Array.isArray(where.value)) {
+        return `Operator "${op}" requires "value" to be an array`;
+      }
+      return null;
+    }
+
+    return 'Invalid where clause: expected "field"/"op"/"value" or "and"/"or"';
+  }
+
+  function validateOrderBy(orderBy) {
+    if (orderBy == null) return null;
+    if (!Array.isArray(orderBy)) return 'orderBy must be an array';
+    for (let i = 0; i < orderBy.length; i++) {
+      const item = orderBy[i];
+      if (!item || typeof item !== 'object') return `orderBy[${i}] must be { field, direction }`;
+      const err = checkField(item.field, `orderBy[${i}]`);
+      if (err) return err;
+      const dir = item.direction;
+      if (dir != null && dir !== 'asc' && dir !== 'desc') {
+        return `orderBy[${i}].direction must be "asc" or "desc"`;
+      }
+    }
+    return null;
+  }
+
+  const whereErr = validateWhere(query.where, 0);
+  if (whereErr) return { valid: false, error: whereErr };
+
+  const orderErr = validateOrderBy(query.orderBy);
+  if (orderErr) return { valid: false, error: orderErr };
+
+  if (query.limit != null && (typeof query.limit !== 'number' || query.limit < 0 || !Number.isInteger(query.limit))) {
+    return { valid: false, error: 'limit must be a non-negative integer' };
+  }
+  if (query.offset != null && (typeof query.offset !== 'number' || query.offset < 0 || !Number.isInteger(query.offset))) {
+    return { valid: false, error: 'offset must be a non-negative integer' };
+  }
+
+  return { valid: true };
+}
+
+function toComparableString(value, type) {
+  if (value == null) return '';
+  if (type === 'json') {
+    try {
+      return JSON.stringify(value);
+    } catch {
+      return String(value);
+    }
+  }
+  return String(value);
+}
+
+function evaluatePredicate(row, condition, columns) {
+  const { field, op, value } = condition;
+  const type = getColumnType(columns, field);
+  const raw = getRowValue(row, field);
+  const cell = raw === undefined || raw === null ? null : coerceValue(raw, type);
+
+  const str = cell != null ? toComparableString(cell, type) : '';
+  const strLower = str.toLowerCase();
+  const valueStr = value != null && value !== undefined ? toComparableString(value, type) : '';
+  const valueStrLower = valueStr.toLowerCase();
+
+  switch (op) {
+    case 'eq':
+      if (cell === null) return value === null || value === undefined;
+      if (type === 'string' || type === 'json') return strLower === valueStrLower;
+      return cell === coerceValue(value, type);
+    case 'ne':
+      if (cell === null) return value !== null && value !== undefined;
+      if (type === 'string' || type === 'json') return strLower !== valueStrLower;
+      return cell !== coerceValue(value, type);
+    case 'gt':
+      if (cell == null) return false;
+      return Number(cell) > Number(coerceValue(value, type));
+    case 'gte':
+      if (cell == null) return false;
+      return Number(cell) >= Number(coerceValue(value, type));
+    case 'lt':
+      if (cell == null) return false;
+      return Number(cell) < Number(coerceValue(value, type));
+    case 'lte':
+      if (cell == null) return false;
+      return Number(cell) <= Number(coerceValue(value, type));
+    case 'contains':
+      return strLower.includes(valueStrLower);
+    case 'startsWith':
+      return strLower.startsWith(valueStrLower);
+    case 'endsWith':
+      return strLower.endsWith(valueStrLower);
+    case 'in': {
+      const arr = Array.isArray(value) ? value : [];
+      return arr.some(v => {
+        const coerced = coerceValue(v, type);
+        if (type === 'string' || type === 'json') {
+          const coercedStr = toComparableString(coerced, type).toLowerCase();
+          return strLower === coercedStr;
+        }
+        return cell === coerced;
+      });
+    }
+    case 'notIn': {
+      const arr = Array.isArray(value) ? value : [];
+      return !arr.some(v => {
+        const coerced = coerceValue(v, type);
+        if (type === 'string' || type === 'json') {
+          const coercedStr = toComparableString(coerced, type).toLowerCase();
+          return strLower === coercedStr;
+        }
+        return cell === coerced;
+      });
+    }
+    case 'isNull':
+      return cell === null || cell === undefined;
+    case 'isNotNull':
+      return cell !== null && cell !== undefined;
+    default:
+      return false;
+  }
+}
+
+function evaluateWhere(row, where, columns) {
+  if (where == null) return true;
+
+  if (Array.isArray(where.and)) {
+    return where.and.every(item => evaluateWhere(row, item, columns));
+  }
+  if (Array.isArray(where.or)) {
+    return where.or.some(item => evaluateWhere(row, item, columns));
+  }
+
+  if (where.field != null && where.op != null) {
+    return evaluatePredicate(row, where, columns);
+  }
+
+  return true;
+}
+
+/**
+ * Execute query: filter, sort, and apply limit/offset.
+ * @param {Array<Object>} rows - All row objects
+ * @param {Array} columns - Table columns (string[] or { name, type }[])
+ * @param {Object} query - Query object (where, orderBy, limit, offset)
+ * @returns {{ rows: Array<Object>, totalCount: number }}
+ */
+export function executeQuery(rows, columns, query) {
+  if (!Array.isArray(rows)) return { rows: [], totalCount: 0 };
+  if (query == null || typeof query !== 'object') {
+    return { rows: [...rows], totalCount: rows.length };
+  }
+
+  let result = rows.filter(row => evaluateWhere(row, query.where, columns));
+
+  if (Array.isArray(query.orderBy) && query.orderBy.length > 0) {
+    const colNames = Array.isArray(columns) ? columns.map(c => getColName(c)).filter(Boolean) : [];
+    result = [...result];
+    result.sort((a, b) => {
+      for (const { field, direction } of query.orderBy) {
+        const type = getColumnType(columns, field);
+        const aVal = getRowValue(a, field);
+        const bVal = getRowValue(b, field);
+        const aCoerced = aVal == null ? null : coerceValue(aVal, type);
+        const bCoerced = bVal == null ? null : coerceValue(bVal, type);
+
+        let cmp = 0;
+        if (aCoerced == null && bCoerced == null) cmp = 0;
+        else if (aCoerced == null) cmp = 1;
+        else if (bCoerced == null) cmp = -1;
+        else if (type === 'string') {
+          cmp = String(aCoerced).toLowerCase().localeCompare(String(bCoerced).toLowerCase());
+        } else if (type === 'int' || type === 'float') {
+          cmp = Number(aCoerced) - Number(bCoerced);
+        } else if (type === 'boolean') {
+          cmp = (aCoerced ? 1 : 0) - (bCoerced ? 1 : 0);
+        } else {
+          cmp = String(aCoerced).localeCompare(String(bCoerced));
+        }
+        if (cmp !== 0) return direction === 'desc' ? -cmp : cmp;
+      }
+      return 0;
+    });
+  }
+
+  const totalCount = result.length;
+  const offset = query.offset != null && Number.isInteger(query.offset) ? query.offset : 0;
+  const limit = query.limit != null && Number.isInteger(query.limit) ? query.limit : result.length;
+  const pageRows = result.slice(offset, offset + limit);
+  return { rows: pageRows, totalCount };
+}

package/dist/schema.js

@@ -0,0 +1,121 @@
+/**
+ * Schema helpers: normalize columns, validate config.
+ */
+
+const COLUMN_TYPES = ['int', 'float', 'boolean', 'string', 'json'];
+
+export function normalizeColumn(col) {
+  if (typeof col === 'string') {
+    return { name: col, type: 'string' };
+  }
+  if (col && typeof col === 'object' && col.name) {
+    const ref = col.references;
+    const hasRef = ref && typeof ref === 'object' &&
+      typeof ref.table === 'string' && ref.table.trim() !== '' &&
+      typeof ref.column === 'string' && ref.column.trim() !== '';
+    const out = { name: col.name, type: COLUMN_TYPES.includes(col.type) ? col.type : 'string' };
+    if (hasRef) out.references = { table: ref.table.trim(), column: ref.column.trim() };
+    return out;
+  }
+  return null;
+}
+
+export function getColumnNames(columns) {
+  if (!Array.isArray(columns)) return [];
+  return columns.map(c => typeof c === 'string' ? c : (c && c.name) ? c.name : null).filter(Boolean);
+}
+
+export function getColumnType(columns, colName) {
+  if (!Array.isArray(columns)) return 'string';
+  const col = columns.find(c => (typeof c === 'string' ? c : c && c.name) === colName);
+  if (!col) return 'string';
+  return typeof col === 'string' ? 'string' : (col.type || 'string');
+}
+
+export function coerceValue(value, type) {
+  if (value === null || value === undefined || value === '') {
+    return type === 'boolean' ? false : null;
+  }
+  switch (type) {
+    case 'int': {
+      const i = parseInt(value, 10);
+      return isNaN(i) ? null : i;
+    }
+    case 'float': {
+      const f = parseFloat(value);
+      return isNaN(f) ? null : f;
+    }
+    case 'boolean':
+      if (typeof value === 'boolean') return value;
+      const s = String(value).toLowerCase();
+      return s === 'true' || s === '1' || s === 'yes';
+    case 'json':
+      if (typeof value === 'object') return value;
+      if (typeof value === 'string') {
+        try {
+          return JSON.parse(value);
+        } catch {
+          return value;
+        }
+      }
+      return value;
+    case 'string':
+    default:
+      return String(value);
+  }
+}
+
+/**
+ * Parse config object into internal db structure.
+ * Config format: { databases: { dbName: { tables: { tableName: { columns: [...] } } } } }
+ * or { tables: { tableName: { columns: [...] } } } for a single-db config.
+ * @param {Object} config
+ * @param {string} [dbName] - If config has top-level tables, use this db name
+ * @returns {{ databases: Object }}
+ */
+export function parseConfig(config, dbName = 'default') {
+  if (!config || typeof config !== 'object') {
+    return { databases: {} };
+  }
+  if (config.databases && typeof config.databases === 'object') {
+    const databases = {};
+    for (const [name, db] of Object.entries(config.databases)) {
+      if (!db || typeof db !== 'object') continue;
+      databases[name] = { tables: {} };
+      const tables = db.tables || db;
+      if (typeof tables === 'object' && !Array.isArray(tables)) {
+        for (const [tName, tDef] of Object.entries(tables)) {
+          if (!tDef || typeof tDef !== 'object') continue;
+          const cols = Array.isArray(tDef.columns) ? tDef.columns : (tDef.columns && tDef.columns.split) ? [] : [];
+          const normalized = cols.map(c => normalizeColumn(c)).filter(Boolean);
+          const names = normalized.map(c => c.name);
+          if (normalized.length > 0 && !names.includes('id')) {
+            normalized.unshift({ name: 'id', type: 'int' });
+          } else if (names.includes('id')) {
+            const idCol = normalized.find(c => c.name === 'id');
+            if (idCol) idCol.type = 'int';
+          }
+          databases[name].tables[tName] = { columns: normalized, rows: [] };
+        }
+      }
+    }
+    return { databases };
+  }
+  // Single-db: { tables: { tableName: { columns: [...] } } }
+  const tables = config.tables || {};
+  const databases = { [dbName]: { tables: {} } };
+  for (const [tName, tDef] of Object.entries(tables)) {
+    if (!tDef || typeof tDef !== 'object') continue;
+    const cols = Array.isArray(tDef.columns) ? tDef.columns : [];
+    const normalized = cols.map(c => normalizeColumn(c)).filter(Boolean);
+    const names = normalized.map(c => c.name);
+    if (normalized.length > 0 && !names.includes('id')) {
+      normalized.unshift({ name: 'id', type: 'int' });
+    } else if (names.includes('id')) {
+      const idCol = normalized.find(c => c.name === 'id');
+      if (idCol) idCol.type = 'int';
+    }
+    databases[dbName].tables[tName] = { columns: normalized, rows: [] };
+  }
+  return { databases };
+}

package/dist/storage/adapters.js

@@ -0,0 +1,197 @@
+/**
+ * Storage adapters for localStorage, sessionStorage, and IndexedDB.
+ * All adapters expose getItem(key), setItem(key, value), removeItem(key), getAllKeys().
+ * Async adapters return Promises; sync adapters return values directly.
+ */
+
+const STORAGE_KEY = '__LS_DB__';
+
+function createLocalStorageAdapter(storageKey = STORAGE_KEY) {
+  const key = storageKey;
+  return {
+    getItem() {
+      try {
+        return typeof localStorage !== 'undefined' ? localStorage.getItem(key) : null;
+      } catch (e) {
+        console.error('localStorage.getItem error:', e);
+        return null;
+      }
+    },
+    setItem(_, value) {
+      try {
+        if (typeof localStorage !== 'undefined') {
+          localStorage.setItem(key, value);
+          return true;
+        }
+        return false;
+      } catch (e) {
+        if (e.name === 'QuotaExceededError') throw new Error('Storage quota exceeded.');
+        throw e;
+      }
+    },
+    removeItem() {
+      try {
+        if (typeof localStorage !== 'undefined') localStorage.removeItem(key);
+        return true;
+      } catch (e) {
+        return false;
+      }
+    },
+    getAllKeys() {
+      return typeof localStorage !== 'undefined' && localStorage.getItem(key) != null ? [key] : [];
+    },
+    isAsync: false
+  };
+}
+
+function createSessionStorageAdapter(storageKey = STORAGE_KEY) {
+  const key = storageKey;
+  return {
+    getItem() {
+      try {
+        return typeof sessionStorage !== 'undefined' ? sessionStorage.getItem(key) : null;
+      } catch (e) {
+        console.error('sessionStorage.getItem error:', e);
+        return null;
+      }
+    },
+    setItem(_, value) {
+      try {
+        if (typeof sessionStorage !== 'undefined') {
+          sessionStorage.setItem(key, value);
+          return true;
+        }
+        return false;
+      } catch (e) {
+        if (e.name === 'QuotaExceededError') throw new Error('Storage quota exceeded.');
+        throw e;
+      }
+    },
+    removeItem() {
+      try {
+        if (typeof sessionStorage !== 'undefined') sessionStorage.removeItem(key);
+        return true;
+      } catch (e) {
+        return false;
+      }
+    },
+    getAllKeys() {
+      return typeof sessionStorage !== 'undefined' && sessionStorage.getItem(key) != null ? [key] : [];
+    },
+    isAsync: false
+  };
+}
+
+function createIndexedDBAdapter(storageKey = STORAGE_KEY) {
+  const DB_NAME = 'BrowserDB_Meta';
+  const STORE_NAME = 'meta';
+  const key = storageKey;
+
+  function openDB() {
+    return new Promise((resolve, reject) => {
+      if (typeof indexedDB === 'undefined') {
+        reject(new Error('IndexedDB not available'));
+        return;
+      }
+      const req = indexedDB.open(DB_NAME, 1);
+      req.onerror = () => reject(req.error);
+      req.onsuccess = () => resolve(req.result);
+      req.onupgradeneeded = (e) => {
+        e.target.result.createObjectStore(STORE_NAME);
+      };
+    });
+  }
+
+  return {
+    getItem() {
+      return openDB().then((db) => {
+        return new Promise((resolve, reject) => {
+          const tx = db.transaction(STORE_NAME, 'readonly');
+          const store = tx.objectStore(STORE_NAME);
+          const req = store.get(key);
+          req.onsuccess = () => {
+            db.close();
+            resolve(req.result ?? null);
+          };
+          req.onerror = () => {
+            db.close();
+            reject(req.error);
+          };
+        });
+      });
+    },
+    setItem(_, value) {
+      return openDB().then((db) => {
+        return new Promise((resolve, reject) => {
+          const tx = db.transaction(STORE_NAME, 'readwrite');
+          const store = tx.objectStore(STORE_NAME);
+          const req = store.put(value, key);
+          req.onsuccess = () => {
+            db.close();
+            resolve(true);
+          };
+          req.onerror = () => {
+            db.close();
+            reject(req.error);
+          };
+        });
+      });
+    },
+    removeItem() {
+      return openDB().then((db) => {
+        return new Promise((resolve, reject) => {
+          const tx = db.transaction(STORE_NAME, 'readwrite');
+          const store = tx.objectStore(STORE_NAME);
+          const req = store.delete(key);
+          req.onsuccess = () => {
+            db.close();
+            resolve(true);
+          };
+          req.onerror = () => {
+            db.close();
+            reject(req.error);
+          };
+        });
+      });
+    },
+    getAllKeys() {
+      return openDB().then((db) => {
+        return new Promise((resolve, reject) => {
+          const tx = db.transaction(STORE_NAME, 'readonly');
+          const store = tx.objectStore(STORE_NAME);
+          const req = store.get(key);
+          req.onsuccess = () => {
+            db.close();
+            resolve(req.result != null ? [key] : []);
+          };
+          req.onerror = () => {
+            db.close();
+            reject(req.error);
+          };
+        });
+      }).catch(() => []);
+    },
+    isAsync: true
+  };
+}
+
+/**
+ * Get storage adapter by type.
+ * @param {'localStorage'|'sessionStorage'|'indexedDB'} type
+ * @param {string} [storageKey] - Optional key to store data under
+ * @returns {Object} Adapter with getItem, setItem, removeItem, getAllKeys, isAsync
+ */
+export function getStorageAdapter(type, storageKey = STORAGE_KEY) {
+  switch (type) {
+    case 'localStorage':
+      return createLocalStorageAdapter(storageKey);
+    case 'sessionStorage':
+      return createSessionStorageAdapter(storageKey);
+    case 'indexedDB':
+      return createIndexedDBAdapter(storageKey);
+    default:
+      throw new Error(`Unsupported storage type: ${type}. Use localStorage, sessionStorage, or indexedDB.`);
+  }
+}
+
+export { STORAGE_KEY };