@storion/storion 1.0.0

package/docs/API.md

@@ -0,0 +1,216 @@
+# API reference
+
+## createDatabase(options)
+
+Create or connect to a database. Returns a **Database** instance.
+
+- **options.name** (string) – Database name.
+- **options.storage** (`'localStorage' | 'sessionStorage' | 'indexedDB'`) – Storage backend.
+- **options.config** (object, optional) – Config object to create tables from. See [CONFIG_FORMAT.md](./CONFIG_FORMAT.md).
+- **options.storageKey** (string, optional) – Key used in storage (default: `__LS_DB__`).
+
+```js
+const db = await createDatabase({
+  name: 'myapp',
+  storage: 'localStorage',
+  config: { tables: { users: { columns: [{ name: 'id', type: 'int' }, { name: 'email', type: 'string' }] } } }
+});
+```
+
+---
+
+## loadConfigFromUrl(url)
+
+Load a config object from a URL (e.g. `/config/db.json`). Returns a **Promise<object>**.
+
+```js
+const config = await loadConfigFromUrl('/config/db.json');
+const db = await createDatabase({ name: 'myapp', storage: 'localStorage', config });
+```
+
+---
+
+## loadConfigFromFile(file)
+
+Load a config object from a **File** (e.g. from `<input type="file">`). Returns a **Promise&lt;object&gt;**.
+
+```js
+const config = await loadConfigFromFile(fileInput.files[0]);
+const db = await createDatabase({ name: 'imported', storage: 'localStorage', config });
+```
+
+---
+
+## Database instance
+
+### db.name
+
+Read-only. The database name.
+
+### db.createTable(tableName, columns)
+
+Create a table. **columns** is an array of `string` (column name, type `string`) or `{ name, type }` with `type` in `'int' | 'float' | 'boolean' | 'string' | 'json'`. An `id` column (type `int`) is added if missing.
+
+```js
+await db.createTable('users', [
+  { name: 'id', type: 'int' },
+  { name: 'email', type: 'string' },
+  { name: 'active', type: 'boolean' }
+]);
+```
+
+### db.listTables()
+
+Returns **Promise&lt;string[]&gt;** – table names.
+
+### db.getTable(tableName)
+
+Returns **Promise&lt;{ columns, rows }&gt;** – table structure and all rows.
+
+### db.insert(tableName, row)
+
+Insert a row. `id` is auto-generated if omitted. Returns **Promise&lt;object&gt;** – the inserted row.
+
+```js
+const row = await db.insert('users', { email: 'a@b.com', active: true });
+```
+
+### db.fetch(tableName, options?)
+
+Fetch rows with optional **options**: `filter` (object), `sortBy` (string), `sortOrder` (`'asc' | 'desc'`), `limit` (number). Returns **Promise&lt;object[]&gt;** – rows.
+
+```js
+const rows = await db.fetch('users', { filter: { active: true }, sortBy: 'email', limit: 10 });
+```
+
+### db.query(tableName, query)
+
+Run a JSON query (where, orderBy, limit, offset). Returns **Promise&lt;{ rows, totalCount }&gt;**. See [QUERY_LANGUAGE.md](./QUERY_LANGUAGE.md).
+
+```js
+const { rows, totalCount } = await db.query('users', {
+  where: { field: 'status', op: 'eq', value: 'active' },
+  orderBy: [{ field: 'name', direction: 'asc' }],
+  limit: 20,
+  offset: 0
+});
+```
+
+### db.update(tableName, id, newData)
+
+Update a row by `id`. Returns **Promise&lt;object&gt;** – updated row.
+
+```js
+await db.update('users', 1, { email: 'new@b.com' });
+```
+
+### db.delete(tableName, id)
+
+Delete a row by `id`. Returns **Promise&lt;boolean&gt;** – success.
+
+### db.deleteTable(tableName)
+
+Delete a table. Fails if another table has a foreign key to it.
+
+### db.exportConfig()
+
+Export the current database (and its tables/rows) as a config-like object. Returns **Promise&lt;object&gt;**.
+
+### db.subscribe(callback) / db.subscribe(tableName, callback) / db.subscribe(tableName, rowId, callback)
+
+Subscribe to change events. When any code mutates the database (insert, update, delete, createTable, deleteTable), all matching subscribers receive an event. Use this so **multiple components** that share the same `Database` instance can react to changes without polling—e.g. Component A updates a row and Component B (subscribed to that table) receives the event and refreshes its view.
+
+- **subscribe(callback)** – subscribe to all changes in this database.
+- **subscribe(tableName, callback)** – subscribe only to changes for `tableName`.
+- **subscribe(tableName, rowId, callback)** – subscribe only to changes for that row.
+
+Returns a function **unsubscribe()** – call it to stop receiving events.
+
+Every matching subscriber receives the event (multiple components can subscribe to the same table or row). If no one has subscribed, the database behaves as before; subscription is optional.
+
+```js
+const unsubscribe = db.subscribe('todos', (event) => {
+  console.log(event.type, event.tableName, event.row);
+  // event.type: 'insert' | 'update' | 'delete' | 'tableCreated' | 'tableDeleted'
+  // event.row, event.rowId, event.previousRow (for update/delete)
+});
+// later: unsubscribe();
+```
+
+### db.unsubscribe(id)
+
+Remove a subscription by id. Prefer using the function returned from **subscribe()** instead.
+
+### Change event shape (StorionChangeEvent)
+
+- **type** – `'insert' | 'update' | 'delete' | 'tableCreated' | 'tableDeleted'`
+- **dbName** – database name
+- **tableName** – table name
+- **row** – inserted/updated row (current state); for delete, see **previousRow**
+- **rowId** – id of the row (for update/delete)
+- **previousRow** – for `update` and `delete`, the row before the change
+
+### db.setChangeBroadcaster(broadcaster)
+
+Optional. Set an object with **broadcastChange(event)** to send change events to another context (e.g. for cross-context sync in a Chrome extension). The same event payload is passed to local subscribers and to the broadcaster. Omit or pass `null` to disable.
+
+---
+
+## createChangeListener(transport, onChange)
+
+Helper for **receiving** Storion change events from another context (e.g. a Chrome extension, another window, or a background script) over a custom transport.
+
+- **transport.onMessage(handler)** – function you provide that registers a message handler and returns an optional unsubscribe function. The handler should be called with messages that are already decoded `StorionChangeEvent`-like objects.
+- **onChange(event)** – callback that will be invoked whenever a valid `StorionChangeEvent` is received.
+
+Returns a function **unsubscribe()** that detaches the listener (if the transport provided one).
+
+```js
+// Example: adapter around window.postMessage
+const transport = {
+  onMessage(handler) {
+    function listener(ev) {
+      // assume ev.data is already a StorionChangeEvent from another context
+      handler(ev.data);
+    }
+    window.addEventListener('message', listener);
+    return () => window.removeEventListener('message', listener);
+  }
+};
+
+const stop = createChangeListener(transport, (event) => {
+  console.log('Received change from another context:', event);
+  // e.g. trigger a UI refresh or sync a local Database instance
+});
+
+// later:
+stop();
+```
+
+Only messages that look like a valid `StorionChangeEvent` are forwarded to **onChange**; other messages on the same transport are ignored.
+
+---
+
+## Query engine (standalone)
+
+You can use the query engine on raw arrays of rows (e.g. from another source):
+
+- **executeQuery(rows, columns, query)** – returns `{ rows, totalCount }`.
+- **validateQuery(query, columns)** – returns `{ valid: boolean, error?: string }`.
+- **QUERY_OPERATORS** – array of allowed operator names.
+
+---
+
+## Schema helpers
+
+- **parseConfig(config, dbName?)** – parse a config object into internal `{ databases }` shape.
+- **normalizeColumn(col)** – normalize a column def to `{ name, type }`.
+- **getColumnNames(columns)** – array of column names.
+- **getColumnType(columns, colName)** – type string for a column.
+- **coerceValue(value, type)** – coerce a value to the given type.
+
+---
+
+## getStorageAdapter(type, storageKey?)
+
+Returns the low-level adapter for `'localStorage' | 'sessionStorage' | 'indexedDB'`. Used internally; you typically use **createDatabase** only.

package/docs/CONFIG_FORMAT.md

@@ -0,0 +1,117 @@
+# Database configuration format
+
+You can create a database and its tables from a **config object** when calling `createDatabase()`, or load that config from a URL or file.
+
+## Option 1: Config object in code
+
+```js
+import { createDatabase } from 'storion';
+
+const config = {
+  tables: {
+    users: {
+      columns: [
+        { name: 'id', type: 'int' },
+        { name: 'email', type: 'string' },
+        { name: 'name', type: 'string' },
+        { name: 'active', type: 'boolean' }
+      ]
+    },
+    posts: {
+      columns: [
+        { name: 'id', type: 'int' },
+        { name: 'title', type: 'string' },
+        { name: 'user_id', type: 'int', references: { table: 'users', column: 'id' } }
+      ]
+    }
+  }
+};
+
+const db = await createDatabase({
+  name: 'myapp',
+  storage: 'localStorage',
+  config
+});
+```
+
+## Option 2: Multiple databases in one config
+
+```json
+{
+  "databases": {
+    "app1": {
+      "tables": {
+        "users": {
+          "columns": [
+            { "name": "id", "type": "int" },
+            { "name": "email", "type": "string" }
+          ]
+        }
+      }
+    },
+    "app2": {
+      "tables": {
+        "items": {
+          "columns": [
+            { "name": "id", "type": "int" },
+            { "name": "label", "type": "string" }
+          ]
+        }
+      }
+    }
+  }
+}
+```
+
+When you call `createDatabase({ name: 'app1', storage: 'localStorage', config })`, only the `app1` database and its tables are created in that instance.
+
+## Option 3: Load config from URL
+
+In the browser you can fetch a JSON config from your server or public folder:
+
+```js
+import { createDatabase, loadConfigFromUrl } from 'storion';
+
+const config = await loadConfigFromUrl('/config/db.json');
+const db = await createDatabase({
+  name: 'myapp',
+  storage: 'localStorage',
+  config
+});
+```
+
+## Option 4: Load config from a File (e.g. file input)
+
+```js
+import { createDatabase, loadConfigFromFile } from 'storion';
+
+// In your HTML: <input type="file" id="configFile" accept=".json" />
+document.getElementById('configFile').addEventListener('change', async (e) => {
+  const file = e.target.files?.[0];
+  if (!file) return;
+  const config = await loadConfigFromFile(file);
+  const db = await createDatabase({
+    name: 'imported',
+    storage: 'localStorage',
+    config
+  });
+});
+```
+
+## Column types
+
+- `int` – integer
+- `float` – number
+- `boolean` – true/false
+- `string` – text
+- `json` – JSON value (object or array). Values are stored as parsed JSON; when you pass a string, it will be `JSON.parse`d where possible.
+
+## Optional: foreign key
+
+Use `references` to point a column to another table’s column:
+
+```json
+{ "name": "user_id", "type": "int", "references": { "table": "users", "column": "id" } }
+```
+
+If you omit `id` in the columns list, an `id` (type `int`) column is added automatically as the primary key.

package/docs/QUERY_LANGUAGE.md

@@ -0,0 +1,73 @@
+# Query language
+
+The package uses a **JSON query object** to filter and sort table data. Use it with `db.query(tableName, query)`.
+
+## Query structure
+
+```json
+{
+  "where": { ... },
+  "orderBy": [ ... ],
+  "limit": 1000,
+  "offset": 0
+}
+```
+
+| Key       | Type   | Description |
+|-----------|--------|-------------|
+| `where`   | object | Optional. Filter conditions. Omit or `null` = no filter. |
+| `orderBy` | array  | Optional. Sort by one or more columns. |
+| `limit`   | number | Optional. Max rows (non-negative integer). |
+| `offset`  | number | Optional. Skip N rows (non-negative integer). |
+
+## Where clause
+
+`where` can be:
+
+1. **A single condition** – `{ "field": "columnName", "op": "eq", "value": 42 }`
+2. **Logic node** – `{ "and": [ ... ] }` or `{ "or": [ ... ] }` (arrays of conditions or nested logic).
+
+### Operators
+
+| Operator       | Description                    | `value` required |
+|----------------|--------------------------------|-------------------|
+| `eq`           | Equals                         | Yes (except null) |
+| `ne`           | Not equals                     | Yes               |
+| `gt`           | Greater than                   | Yes               |
+| `gte`          | Greater than or equal          | Yes               |
+| `lt`           | Less than                      | Yes               |
+| `lte`          | Less than or equal             | Yes               |
+| `contains`     | String contains (case-insensitive) | Yes           |
+| `startsWith`   | String starts with (case-insensitive) | Yes        |
+| `endsWith`     | String ends with (case-insensitive)   | Yes        |
+| `in`           | Value in list                  | Yes (array)       |
+| `notIn`        | Value not in list              | Yes (array)       |
+| `isNull`       | Value is null/undefined        | No                |
+| `isNotNull`    | Value is not null/undefined    | No                |
+
+String comparisons are **case-insensitive**. Column types (`int`, `float`, `boolean`, `string`, `json`) are used for type-aware comparison. For `json` columns, comparisons use the JSON string representation (e.g. `JSON.stringify`), so equality and string operators work on the serialized form of the value.
+
+## OrderBy
+
+Array of `{ "field": "columnName", "direction": "asc" | "desc" }`. Multiple columns supported; earlier entries have higher priority.
+
+## Example with db.query()
+
+```js
+const { rows, totalCount } = await db.query('users', {
+  where: {
+    and: [
+      { field: 'status', op: 'eq', value: 'active' },
+      { field: 'name', op: 'contains', value: 'smith' }
+    ]
+  },
+  orderBy: [
+    { field: 'created_at', direction: 'desc' },
+    { field: 'id', direction: 'asc' }
+  ],
+  limit: 20,
+  offset: 0
+});
+```
+
+Returns `{ rows: [...], totalCount: number }`.

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@storion/storion",
+  "version": "1.0.0",
+  "description": "Framework-agnostic client-side database with localStorage, sessionStorage, and IndexedDB. Create databases, tables, save/fetch records, and run JSON queries.",
+  "type": "module",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "types",
+    "README.md",
+    "docs"
+  ],
+  "scripts": {
+    "build": "node build.js",
+    "build:cdn": "node build-cdn.js",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "browser",
+    "database",
+    "localStorage",
+    "sessionStorage",
+    "indexeddb",
+    "query",
+    "offline",
+    "storage",
+    "framework-agnostic",
+    "react",
+    "vue",
+    "angular"
+  ],
+  "author": "",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/storionjs/storion.git"
+  },
+  "bugs": {
+    "url": "https://github.com/storionjs/storion/issues"
+  },
+  "homepage": "https://github.com/storionjs/storion#readme",
+  "sideEffects": false,
+  "devDependencies": {
+    "esbuild": "^0.24.0"
+  }
+}

package/types/index.d.ts

@@ -0,0 +1,142 @@
+/**
+ * Type declarations for storion.
+ * Database instance methods are async and return Promises.
+ */
+
+export type StorageType = 'localStorage' | 'sessionStorage' | 'indexedDB';
+
+export interface CreateDatabaseOptions {
+  name: string;
+  storage: StorageType;
+  /** Optional config object to create DB and tables from */
+  config?: DBConfig;
+  /** Optional storage key (default: __LS_DB__) */
+  storageKey?: string;
+}
+
+export interface DBConfig {
+  databases?: Record<string, { tables?: Record<string, TableDef> }>;
+  tables?: Record<string, TableDef>;
+}
+
+export interface TableDef {
+  columns: Array<string | { name: string; type: 'int' | 'float' | 'boolean' | 'string' | 'json'; references?: { table: string; column: string } }>;
+}
+
+export interface QueryWhere {
+  field?: string;
+  op?: string;
+  value?: unknown;
+  and?: QueryWhere[];
+  or?: QueryWhere[];
+}
+
+export interface Query {
+  where?: QueryWhere | null;
+  orderBy?: Array<{ field: string; direction: 'asc' | 'desc' }>;
+  limit?: number;
+  offset?: number;
+}
+
+export interface QueryResult {
+  rows: Record<string, unknown>[];
+  totalCount: number;
+}
+
+export interface FetchOptions {
+  filter?: Record<string, unknown>;
+  sortBy?: string;
+  sortOrder?: 'asc' | 'desc';
+  limit?: number;
+}
+
+/** Change event emitted after insert, update, delete, createTable, or deleteTable. */
+export interface StorionChangeEvent {
+  type: 'insert' | 'update' | 'delete' | 'tableCreated' | 'tableDeleted';
+  dbName: string;
+  tableName: string;
+  row?: Record<string, unknown>;
+  rowId?: number | string;
+  previousRow?: Record<string, unknown>;
+}
+
+/** Generic transport interface for receiving change events from another context. */
+export interface ChangeTransport {
+  /**
+   * Register a message handler. The handler will be called with messages that
+   * should represent StorionChangeEvent-like objects. Returns an optional
+   * function that can be called to unsubscribe.
+   */
+  onMessage(handler: (message: unknown) => void): (() => void) | void;
+}
+
+/** Optional broadcaster for cross-context sync (e.g. extension ↔ webapp). */
+export interface ChangeBroadcaster {
+  broadcastChange(event: StorionChangeEvent): void | Promise<void>;
+}
+
+export function createDatabase(options: CreateDatabaseOptions): Promise<Database>;
+
+export function loadConfigFromUrl(url: string): Promise<DBConfig>;
+
+export function loadConfigFromFile(file: File): Promise<DBConfig>;
+
+export function getStorageAdapter(type: StorageType, storageKey?: string): StorageAdapter;
+
+export function executeQuery(rows: object[], columns: unknown[], query: Query | null): QueryResult;
+
+export function validateQuery(query: Query | null, columns: unknown[]): { valid: boolean; error?: string };
+
+export const QUERY_OPERATORS: string[];
+
+export function parseConfig(config: DBConfig, dbName?: string): { databases: Record<string, unknown> };
+
+export function normalizeColumn(col: string | { name: string; type?: string }): { name: string; type: string } | null;
+
+export function getColumnNames(columns: unknown[]): string[];
+
+export function getColumnType(columns: unknown[], colName: string): string;
+
+export function coerceValue(value: unknown, type: string): unknown;
+
+export interface StorageAdapter {
+  getItem(): string | null | Promise<string | null>;
+  setItem(key: null, value: string): void | boolean | Promise<void | boolean>;
+  removeItem(): void | boolean | Promise<void | boolean>;
+  getAllKeys(): string[] | Promise<string[]>;
+  isAsync?: boolean;
+}
+
+export interface Database {
+  readonly name: string;
+  createTable(tableName: string, columns: Array<string | { name: string; type: string }>): Promise<boolean>;
+  listTables(): Promise<string[]>;
+  getTable(tableName: string): Promise<{ columns: unknown[]; rows: Record<string, unknown>[] }>;
+  insert(tableName: string, row: Record<string, unknown>): Promise<Record<string, unknown>>;
+  fetch(tableName: string, options?: FetchOptions): Promise<Record<string, unknown>[]>;
+  query(tableName: string, query: Query): Promise<QueryResult>;
+  update(tableName: string, id: number | string, newData: Record<string, unknown>): Promise<Record<string, unknown>>;
+  delete(tableName: string, id: number | string): Promise<boolean>;
+  deleteTable(tableName: string): Promise<boolean>;
+  exportConfig(): Promise<DBConfig>;
+  /** Subscribe to all changes in this database. Returns unsubscribe function. */
+  subscribe(callback: (event: StorionChangeEvent) => void): () => void;
+  /** Subscribe to changes for one table. Returns unsubscribe function. */
+  subscribe(tableName: string, callback: (event: StorionChangeEvent) => void): () => void;
+  /** Subscribe to changes for one row. Returns unsubscribe function. */
+  subscribe(tableName: string, rowId: number | string, callback: (event: StorionChangeEvent) => void): () => void;
+  /** Remove subscription by id (prefer using the function returned from subscribe). */
+  unsubscribe(id: number): void;
+  /** Set optional broadcaster for cross-context sync (Phase 2). */
+  setChangeBroadcaster(broadcaster: ChangeBroadcaster | null): void;
+}
+
+/**
+ * Create a listener for change events coming from another context (e.g. from
+ * a Chrome extension or another window) via a user-provided transport.
+ * Returns a function to unsubscribe.
+ */
+export function createChangeListener(
+  transport: ChangeTransport,
+  onChange: (event: StorionChangeEvent) => void
+): () => void;