@objectstack/driver-memory 4.0.4 → 4.1.0

package/README.md

@@ -1,21 +1,102 @@
 # @objectstack/driver-memory
 
-In-Memory Database access layer for ObjectStack. Supports rich querying capabilities (MongoDB-style operators) on standard JavaScript arrays.
+> In-memory ObjectQL driver for ObjectStack — zero-config storage for development, unit tests, Storybook, and browser MSW mocks.
 
-## Features
+[![npm](https://img.shields.io/npm/v/@objectstack/driver-memory.svg)](https://www.npmjs.com/package/@objectstack/driver-memory)
+[![License: Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 
-- **NoSQL Syntax**: Supports `$eq`, `$gt`, `$lt`, `$in`, `$and`, `$or` operators.
-- **Sorting & Pagination**: Full support for `sort`, `skip`, `limit`.
-- **Zero Config**: Perfect for prototyping, testing, and the **MSW Browser Mock**.
-- **Stateful**: Preserves data in memory during the session.
+## Overview
 
-## Usage
+Implements the `IDataEngine` contract against in-memory `Map`-backed tables. Supports the full ObjectQL surface: MongoDB-style operators (`$eq`, `$ne`, `$gt`, `$lt`, `$gte`, `$lte`, `$in`, `$nin`, `$and`, `$or`, `$not`), sorting, pagination, aggregations, and joins. Optional persistence adapters serialize state to disk (Node) or `localStorage` (browser).
+
+## Installation
+
+```bash
+pnpm add @objectstack/driver-memory
+```
+
+## Quick Start
+
+```typescript
+import { ObjectKernel } from '@objectstack/core';
+import memoryPlugin from '@objectstack/driver-memory';
+
+const kernel = new ObjectKernel();
+kernel.use(memoryPlugin);                 // default plugin
+await kernel.bootstrap();
+```
+
+### Direct instantiation
 
 ```typescript
 import { InMemoryDriver } from '@objectstack/driver-memory';
 
 const driver = new InMemoryDriver();
 await driver.connect();
+```
+
+### With filesystem persistence (Node)
+
+```typescript
+import { InMemoryDriver, FileSystemPersistenceAdapter } from '@objectstack/driver-memory';
 
-// Used internally by ObjectQL
+const driver = new InMemoryDriver({
+  persistence: new FileSystemPersistenceAdapter('./data/snapshot.json'),
+});
+await driver.connect();
 ```
+
+### With `localStorage` persistence (browser)
+
+```typescript
+import { InMemoryDriver, LocalStoragePersistenceAdapter } from '@objectstack/driver-memory';
+
+const driver = new InMemoryDriver({
+  persistence: new LocalStoragePersistenceAdapter('objectstack:dev'),
+});
+```
+
+## Key Exports
+
+| Export | Kind | Description |
+|:---|:---|:---|
+| `default` | kernel plugin | Drop-in plugin. |
+| `InMemoryDriver` | class | Driver instance for direct use. |
+| `InMemoryStrategy` | class | Query execution strategy used by ObjectQL. |
+| `FileSystemPersistenceAdapter` | class | Node-only persistence. |
+| `LocalStoragePersistenceAdapter` | class | Browser-only persistence. |
+| `MemoryAnalyticsService` | class | Adds analytics aggregations backed by memory store. |
+| `InMemoryDriverConfig`, `PersistenceAdapterInterface`, `MemoryAnalyticsConfig` | types | Configuration shapes. |
+
+## Configuration
+
+| Option | Type | Default | Notes |
+|:---|:---|:---|:---|
+| `persistence` | `PersistenceAdapterInterface?` | `undefined` | Optional snapshot store. |
+| `seed` | `Record<string, any[]>?` | `{}` | Initial rows keyed by object name. |
+| `idStrategy` | `'uuid' \| 'auto'` | `'uuid'` | ID generation strategy. |
+
+## When to use
+
+- ✅ Development, unit tests, CI, Storybook.
+- ✅ Browser-only demos pairing with [`@objectstack/plugin-msw`](../plugin-msw).
+
+## When not to use
+
+- ❌ Production — data is lost on restart without a persistence adapter; durability/concurrency guarantees are minimal.
+- ❌ Multi-process deployments.
+
+## Related Packages
+
+- [`@objectstack/objectql`](../../objectql) — query engine.
+- [`@objectstack/driver-sql`](../driver-sql), [`@objectstack/driver-turso`](../driver-turso) — production drivers.
+- [`@objectstack/plugin-msw`](../plugin-msw) — browser mock API.
+
+## Links
+
+- 📖 Docs: <https://objectstack.ai/docs>
+- 📚 API Reference: <https://objectstack.ai/docs/references>
+
+## License
+
+Apache-2.0 © ObjectStack

package/dist/index.d.mts

@@ -395,6 +395,50 @@ declare class MemoryAnalyticsService implements IAnalyticsService {
         sql: string;
         params: unknown[];
     }>;
+    /**
+     * Normalize filters into a cube-style array regardless of input shape.
+     *
+     * Accepts:
+     *   - undefined / null → []
+     *   - cube-style array `[{member, operator, values}]` → returned as-is
+     *   - MongoDB FilterCondition object (per spec/data/filter.zod.ts):
+     *       * implicit equality:  `{is_active: true}`
+     *       * operator wrapper:   `{stage: {$nin: [...]}}`
+     *       * mixed:              `{stage: 'won', amount: {$gte: 100}}`
+     *     → flattened into one cube-style entry per (field, operator) pair
+     *
+     * Logical combinators (`$and`, `$or`, `$not`) are not yet expanded into
+     * the cube pipeline; for current dashboard widget metadata the implicit
+     * top-level AND of fields is sufficient. `$and` clauses are flattened
+     * into the same AND list.
+     */
+    private normalizeFilters;
+    private flattenFilterCondition;
+    /**
+     * Map MongoDB-style `$op` keys (from FilterCondition) to the cube-style
+     * operator names accepted by `convertOperatorToMongo` / `operatorToSql`.
+     */
+    private mongoOperatorToCubeOperator;
+    /**
+     * Stringify a filter value for cube-style storage. Booleans become
+     * `'1'/'0'` so that downstream consumers expecting SQLite-style
+     * numeric booleans match correctly. The in-memory pipeline uses
+     * {@link coerceFilterValue} to recover real JS types from these
+     * strings.
+     */
+    private stringifyForCube;
+    /**
+     * Recover a runtime value from its cube-stringified form for in-memory
+     * comparison. Booleans, integers, floats and ISO-date-like strings are
+     * coerced; everything else stays as a string.
+     */
+    private coerceFilterValue;
+    /**
+     * Type-aware SQL literal formatter. Booleans and numbers are emitted
+     * unquoted; everything else is single-quoted with embedded quotes
+     * escaped.
+     */
+    private toSqlLiteral;
     private resolveFieldPath;
     private resolveMeasure;
     private resolveDimension;

package/dist/index.d.ts

@@ -395,6 +395,50 @@ declare class MemoryAnalyticsService implements IAnalyticsService {
         sql: string;
         params: unknown[];
     }>;
+    /**
+     * Normalize filters into a cube-style array regardless of input shape.
+     *
+     * Accepts:
+     *   - undefined / null → []
+     *   - cube-style array `[{member, operator, values}]` → returned as-is
+     *   - MongoDB FilterCondition object (per spec/data/filter.zod.ts):
+     *       * implicit equality:  `{is_active: true}`
+     *       * operator wrapper:   `{stage: {$nin: [...]}}`
+     *       * mixed:              `{stage: 'won', amount: {$gte: 100}}`
+     *     → flattened into one cube-style entry per (field, operator) pair
+     *
+     * Logical combinators (`$and`, `$or`, `$not`) are not yet expanded into
+     * the cube pipeline; for current dashboard widget metadata the implicit
+     * top-level AND of fields is sufficient. `$and` clauses are flattened
+     * into the same AND list.
+     */
+    private normalizeFilters;
+    private flattenFilterCondition;
+    /**
+     * Map MongoDB-style `$op` keys (from FilterCondition) to the cube-style
+     * operator names accepted by `convertOperatorToMongo` / `operatorToSql`.
+     */
+    private mongoOperatorToCubeOperator;
+    /**
+     * Stringify a filter value for cube-style storage. Booleans become
+     * `'1'/'0'` so that downstream consumers expecting SQLite-style
+     * numeric booleans match correctly. The in-memory pipeline uses
+     * {@link coerceFilterValue} to recover real JS types from these
+     * strings.
+     */
+    private stringifyForCube;
+    /**
+     * Recover a runtime value from its cube-stringified form for in-memory
+     * comparison. Booleans, integers, floats and ISO-date-like strings are
+     * coerced; everything else stays as a string.
+     */
+    private coerceFilterValue;
+    /**
+     * Type-aware SQL literal formatter. Booleans and numbers are emitted
+     * unquoted; everything else is single-quoted with embedded quotes
+     * escaped.
+     */
+    private toSqlLiteral;
     private resolveFieldPath;
     private resolveMeasure;
     private resolveDimension;

package/dist/index.js

@@ -876,9 +876,14 @@ var _InMemoryDriver = class _InMemoryDriver {
   performAggregation(records, query) {
     const { groupBy, aggregations } = query;
     const groups = /* @__PURE__ */ new Map();
+    const normalizeGroupBy = (node) => {
+      if (typeof node === "string") return { field: node, alias: node };
+      return { field: node.field, alias: node.alias ?? node.field };
+    };
     if (groupBy && groupBy.length > 0) {
       for (const record of records) {
-        const keyParts = groupBy.map((field) => {
+        const keyParts = groupBy.map((node) => {
+          const { field } = normalizeGroupBy(node);
           const val = getValueByPath(record, field);
           return val === void 0 || val === null ? "null" : String(val);
         });
@@ -897,8 +902,9 @@ var _InMemoryDriver = class _InMemoryDriver {
       if (groupBy && groupBy.length > 0) {
         if (groupRecords.length > 0) {
           const firstRecord = groupRecords[0];
-          for (const field of groupBy) {
-            this.setValueByPath(row, field, getValueByPath(firstRecord, field));
+          for (const node of groupBy) {
+            const { field, alias } = normalizeGroupBy(node);
+            this.setValueByPath(row, alias, getValueByPath(firstRecord, field));
           }
         }
       }
@@ -1179,18 +1185,20 @@ var MemoryAnalyticsService = class {
       throw new Error(`Cube not found: ${query.cube}`);
     }
     const pipeline = [];
-    if (query.filters && query.filters.length > 0) {
+    const normalizedFilters = this.normalizeFilters(query);
+    if (normalizedFilters.length > 0) {
       const matchStage = {};
-      for (const filter of query.filters) {
+      for (const filter of normalizedFilters) {
         const mongoOp = this.convertOperatorToMongo(filter.operator);
         const fieldPath = this.resolveFieldPath(cube, filter.member);
         if (filter.values && filter.values.length > 0) {
+          const coerced = filter.values.map((v) => this.coerceFilterValue(v));
           if (mongoOp === "$in") {
-            matchStage[fieldPath] = { $in: filter.values };
+            matchStage[fieldPath] = { $in: coerced };
           } else if (mongoOp === "$nin") {
-            matchStage[fieldPath] = { $nin: filter.values };
+            matchStage[fieldPath] = { $nin: coerced };
           } else {
-            matchStage[fieldPath] = { [mongoOp]: filter.values[0] };
+            matchStage[fieldPath] = { [mongoOp]: coerced[0] };
           }
         } else if (mongoOp === "$exists") {
           matchStage[fieldPath] = { $exists: filter.operator === "set" };
@@ -1367,12 +1375,14 @@ var MemoryAnalyticsService = class {
       }
     }
     const whereClauses = [];
-    if (query.filters && query.filters.length > 0) {
-      for (const filter of query.filters) {
+    const normalizedFilters = this.normalizeFilters(query);
+    if (normalizedFilters.length > 0) {
+      for (const filter of normalizedFilters) {
         const fieldPath = this.resolveFieldPath(cube, filter.member);
         const sqlOp = this.operatorToSql(filter.operator);
         if (filter.values && filter.values.length > 0) {
-          whereClauses.push(`${fieldPath} ${sqlOp} '${filter.values[0]}'`);
+          const literal = this.toSqlLiteral(filter.values[0]);
+          whereClauses.push(`${fieldPath} ${sqlOp} ${literal}`);
         }
       }
     }
@@ -1400,6 +1410,147 @@ var MemoryAnalyticsService = class {
   // ===================================
   // Helper Methods
   // ===================================
+  /**
+   * Normalize filters into a cube-style array regardless of input shape.
+   *
+   * Accepts:
+   *   - undefined / null → []
+   *   - cube-style array `[{member, operator, values}]` → returned as-is
+   *   - MongoDB FilterCondition object (per spec/data/filter.zod.ts):
+   *       * implicit equality:  `{is_active: true}`
+   *       * operator wrapper:   `{stage: {$nin: [...]}}`
+   *       * mixed:              `{stage: 'won', amount: {$gte: 100}}`
+   *     → flattened into one cube-style entry per (field, operator) pair
+   *
+   * Logical combinators (`$and`, `$or`, `$not`) are not yet expanded into
+   * the cube pipeline; for current dashboard widget metadata the implicit
+   * top-level AND of fields is sufficient. `$and` clauses are flattened
+   * into the same AND list.
+   */
+  normalizeFilters(query) {
+    if (!query || typeof query !== "object") return [];
+    const out = [];
+    const where = query.where;
+    if (where && typeof where === "object" && !Array.isArray(where)) {
+      this.flattenFilterCondition(where, out);
+    }
+    return out;
+  }
+  flattenFilterCondition(cond, out) {
+    for (const [key, raw] of Object.entries(cond)) {
+      if (raw == null) continue;
+      if (key === "$and" && Array.isArray(raw)) {
+        for (const sub of raw) {
+          if (sub && typeof sub === "object") {
+            this.flattenFilterCondition(sub, out);
+          }
+        }
+        continue;
+      }
+      if (key === "$or" || key === "$not") continue;
+      if (typeof raw === "object" && !Array.isArray(raw) && !(raw instanceof Date)) {
+        const wrapper = raw;
+        const opEntries = Object.keys(wrapper).filter((k) => k.startsWith("$"));
+        if (opEntries.length > 0) {
+          for (const opKey of opEntries) {
+            const cubeOp = this.mongoOperatorToCubeOperator(opKey);
+            if (!cubeOp) continue;
+            const v = wrapper[opKey];
+            const values2 = Array.isArray(v) ? v.map((x) => this.stringifyForCube(x)) : [this.stringifyForCube(v)];
+            out.push({ member: key, operator: cubeOp, values: values2 });
+          }
+          continue;
+        }
+        for (const [nestedKey, nestedVal] of Object.entries(wrapper)) {
+          this.flattenFilterCondition({ [`${key}.${nestedKey}`]: nestedVal }, out);
+        }
+        continue;
+      }
+      const values = Array.isArray(raw) ? raw.map((x) => this.stringifyForCube(x)) : [this.stringifyForCube(raw)];
+      out.push({
+        member: key,
+        operator: Array.isArray(raw) ? "in" : "equals",
+        values
+      });
+    }
+  }
+  /**
+   * Map MongoDB-style `$op` keys (from FilterCondition) to the cube-style
+   * operator names accepted by `convertOperatorToMongo` / `operatorToSql`.
+   */
+  mongoOperatorToCubeOperator(op) {
+    switch (op) {
+      case "$eq":
+        return "equals";
+      case "$ne":
+        return "notEquals";
+      case "$gt":
+        return "gt";
+      case "$gte":
+        return "gte";
+      case "$lt":
+        return "lt";
+      case "$lte":
+        return "lte";
+      case "$in":
+        return "in";
+      case "$nin":
+        return "notIn";
+      case "$contains":
+        return "contains";
+      case "$notContains":
+        return "notContains";
+      case "$exists":
+        return "set";
+      default:
+        return null;
+    }
+  }
+  /**
+   * Stringify a filter value for cube-style storage. Booleans become
+   * `'1'/'0'` so that downstream consumers expecting SQLite-style
+   * numeric booleans match correctly. The in-memory pipeline uses
+   * {@link coerceFilterValue} to recover real JS types from these
+   * strings.
+   */
+  stringifyForCube(v) {
+    if (v == null) return "";
+    if (typeof v === "boolean") return v ? "1" : "0";
+    if (v instanceof Date) return v.toISOString();
+    if (typeof v === "object") return JSON.stringify(v);
+    return String(v);
+  }
+  /**
+   * Recover a runtime value from its cube-stringified form for in-memory
+   * comparison. Booleans, integers, floats and ISO-date-like strings are
+   * coerced; everything else stays as a string.
+   */
+  coerceFilterValue(s) {
+    if (s === "true") return true;
+    if (s === "false") return false;
+    if (s === "null") return null;
+    if (/^-?\d+$/.test(s)) {
+      const n = Number(s);
+      if (Number.isFinite(n)) return n;
+    }
+    if (/^-?\d+\.\d+$/.test(s)) {
+      const n = Number(s);
+      if (Number.isFinite(n)) return n;
+    }
+    return s;
+  }
+  /**
+   * Type-aware SQL literal formatter. Booleans and numbers are emitted
+   * unquoted; everything else is single-quoted with embedded quotes
+   * escaped.
+   */
+  toSqlLiteral(s) {
+    if (s === "true") return "1";
+    if (s === "false") return "0";
+    if (s === "null") return "NULL";
+    if (/^-?\d+(\.\d+)?$/.test(s)) return s;
+    return `'${s.replace(/'/g, "''")}'`;
+  }
   resolveFieldPath(cube, member) {
     const parts = member.split(".");
     const fieldName = parts.length > 1 ? parts[1] : parts[0];
@@ -1416,7 +1567,20 @@ var MemoryAnalyticsService = class {
   resolveMeasure(cube, measureName) {
     const parts = measureName.split(".");
     const fieldName = parts.length > 1 ? parts[1] : parts[0];
-    return cube.measures[fieldName];
+    const direct = cube.measures[fieldName];
+    if (direct) return direct;
+    const aggTypes = ["count", "sum", "avg", "min", "max", "count_distinct"];
+    for (const type of aggTypes) {
+      const suffix = `_${type}`;
+      if (fieldName.endsWith(suffix)) {
+        const baseField = fieldName.slice(0, -suffix.length);
+        const candidate = cube.measures[baseField];
+        if (candidate && candidate.type === type) {
+          return candidate;
+        }
+      }
+    }
+    return void 0;
   }
   resolveDimension(cube, dimensionName) {
     const parts = dimensionName.split(".");
@@ -1475,6 +1639,8 @@ var MemoryAnalyticsService = class {
       "gte": "$gte",
       "lt": "$lt",
       "lte": "$lte",
+      "in": "$in",
+      "notIn": "$nin",
       "set": "$exists",
       "notSet": "$exists",
       "inDateRange": "$gte"