@bquery/bquery 1.2.0 → 1.4.0

package/src/store/mapping.ts

@@ -0,0 +1,73 @@
+/**
+ * Mapping helpers for store state and actions.
+ */
+
+/**
+ * Maps store state properties to a reactive object for use in components.
+ *
+ * @param store - The store instance
+ * @param keys - State keys to map
+ * @returns Object with mapped properties
+ */
+export const mapState = <S extends Record<string, unknown>, K extends keyof S>(
+  store: S,
+  keys: K[]
+): Pick<S, K> => {
+  const mapped = {} as Pick<S, K>;
+
+  for (const key of keys) {
+    Object.defineProperty(mapped, key, {
+      get: () => store[key],
+      enumerable: true,
+    });
+  }
+
+  return mapped;
+};
+
+/**
+ * Maps store getters to a reactive object for use in components.
+ *
+ * @param store - The store instance
+ * @param keys - Getter keys to map
+ * @returns Object with mapped getters
+ */
+export const mapGetters = <G extends Record<string, unknown>, K extends keyof G>(
+  store: G,
+  keys: K[]
+): Pick<G, K> => {
+  const mapped = {} as Pick<G, K>;
+
+  for (const key of keys) {
+    Object.defineProperty(mapped, key, {
+      get: () => store[key],
+      enumerable: true,
+    });
+  }
+
+  return mapped;
+};
+
+/**
+ * Maps store actions to an object for easier destructuring.
+ *
+ * @param store - The store instance
+ * @param keys - Action keys to map
+ * @returns Object with mapped actions
+ */
+export const mapActions = <
+  A extends Record<string, (...args: unknown[]) => unknown>,
+  K extends keyof A,
+>(
+  store: A,
+  keys: K[]
+): Pick<A, K> => {
+  const mapped = {} as Pick<A, K>;
+
+  for (const key of keys) {
+    (mapped as Record<string, unknown>)[key as string] = (...args: unknown[]) =>
+      (store[key] as (...args: unknown[]) => unknown)(...args);
+  }
+
+  return mapped;
+};

package/src/store/persisted.ts

@@ -0,0 +1,61 @@
+/**
+ * Store persistence helpers.
+ */
+
+import { createStore } from './create-store';
+import type { Store, StoreDefinition } from './types';
+
+/**
+ * Creates a store with automatic persistence to localStorage.
+ *
+ * @param definition - Store definition
+ * @param storageKey - Optional custom storage key
+ * @returns The reactive store instance
+ */
+export const createPersistedStore = <
+  S extends Record<string, unknown>,
+  G extends Record<string, unknown> = Record<string, never>,
+  A extends Record<string, (...args: unknown[]) => unknown> = Record<string, never>,
+>(
+  definition: StoreDefinition<S, G, A>,
+  storageKey?: string
+): Store<S, G, A> => {
+  const key = storageKey ?? `bquery-store-${definition.id}`;
+
+  const originalStateFactory = definition.state;
+
+  const wrappedDefinition: StoreDefinition<S, G, A> = {
+    ...definition,
+    state: () => {
+      const defaultState = originalStateFactory();
+
+      if (typeof window !== 'undefined') {
+        try {
+          const saved = localStorage.getItem(key);
+          if (saved) {
+            return { ...defaultState, ...JSON.parse(saved) } as S;
+          }
+        } catch {
+          // Ignore parse errors
+        }
+      }
+
+      return defaultState;
+    },
+  };
+
+  const store = createStore(wrappedDefinition);
+
+  // Subscribe to save changes
+  store.$subscribe((state) => {
+    if (typeof window !== 'undefined') {
+      try {
+        localStorage.setItem(key, JSON.stringify(state));
+      } catch {
+        // Ignore quota errors
+      }
+    }
+  });
+
+  return store;
+};

package/src/store/plugins.ts

@@ -0,0 +1,32 @@
+/**
+ * Store plugins API.
+ */
+
+import type { Store, StoreDefinition, StorePlugin } from './types';
+
+/** @internal Registered plugins */
+const plugins: StorePlugin[] = [];
+
+/**
+ * Registers a plugin that extends all stores.
+ *
+ * @param plugin - The plugin function
+ */
+export const registerPlugin = (plugin: StorePlugin): void => {
+  plugins.push(plugin);
+};
+
+/** @internal */
+export const applyPlugins = (
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  store: Store<any, any, any>,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  options: StoreDefinition<any, any, any>
+): void => {
+  for (const plugin of plugins) {
+    const extension = plugin({ store, options });
+    if (extension) {
+      Object.assign(store, extension);
+    }
+  }
+};

package/src/store/registry.ts

@@ -0,0 +1,51 @@
+/**
+ * Store registry utilities.
+ */
+
+import { unregisterDevtoolsStore } from './devtools';
+import type { Store } from './types';
+
+/** @internal Registry of all stores for devtools */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const storeRegistry = new Map<string, Store<any, any, any>>();
+
+/** @internal */
+export const hasStore = (id: string): boolean => storeRegistry.has(id);
+
+/** @internal */
+export const registerStore = (
+  id: string,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  store: Store<any, any, any>
+): void => {
+  storeRegistry.set(id, store);
+};
+
+/**
+ * Retrieves an existing store by its ID.
+ *
+ * @param id - The store identifier
+ * @returns The store instance or undefined if not found
+ */
+export const getStore = <T = unknown>(id: string): T | undefined => {
+  return storeRegistry.get(id) as T | undefined;
+};
+
+/**
+ * Lists all registered store IDs.
+ *
+ * @returns Array of store IDs
+ */
+export const listStores = (): string[] => {
+  return Array.from(storeRegistry.keys());
+};
+
+/**
+ * Removes a store from the registry.
+ *
+ * @param id - The store identifier
+ */
+export const destroyStore = (id: string): void => {
+  storeRegistry.delete(id);
+  unregisterDevtoolsStore(id);
+};

package/src/store/types.ts

@@ -0,0 +1,94 @@
+/**
+ * Store types for bQuery's state module.
+ * @module bquery/store
+ */
+
+/**
+ * Store state factory function.
+ */
+export type StateFactory<S> = () => S;
+
+/**
+ * Getter definition - derives computed values from state.
+ */
+export type Getters<S, G> = {
+  [K in keyof G]: (state: S, getters: G) => G[K];
+};
+
+/**
+ * Action definition - methods that can modify state.
+ * The `this` context includes state, getters, and other actions.
+ */
+export type Actions<S, G, A> = {
+  [K in keyof A]: A[K] extends (...args: infer P) => infer R
+    ? (this: S & G & A, ...args: P) => R
+    : never;
+};
+
+/**
+ * Store definition for createStore.
+ */
+export type StoreDefinition<
+  S extends Record<string, unknown> = Record<string, unknown>,
+  G extends Record<string, unknown> = Record<string, unknown>,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  A extends Record<string, (...args: any[]) => any> = Record<string, never>,
+> = {
+  /** Unique store identifier for devtools */
+  id: string;
+  /** State factory function */
+  state: StateFactory<S>;
+  /** Computed getters */
+  getters?: Getters<S, G>;
+  /** Action methods */
+  actions?: Actions<S, G, A>;
+};
+
+/**
+ * Store subscriber callback.
+ */
+export type StoreSubscriber<S> = (state: S) => void;
+
+/**
+ * Patch payload for store updates.
+ */
+export type StorePatch<S> = Partial<S> | ((state: S) => void);
+
+/**
+ * The returned store instance with state, getters, and actions merged.
+ */
+export type Store<
+  S extends Record<string, unknown>,
+  G extends Record<string, unknown>,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  A extends Record<string, (...args: any[]) => any>,
+> = S &
+  G &
+  A & {
+    /** Store identifier */
+    $id: string;
+    /** Reset state to initial values */
+    $reset: () => void;
+    /** Subscribe to state changes */
+    $subscribe: (callback: StoreSubscriber<S>) => () => void;
+    /** Patch multiple state properties at once (shallow) */
+    $patch: (partial: StorePatch<S>) => void;
+    /**
+     * Patch with deep reactivity support.
+     * Unlike $patch, this method deep-clones nested objects before mutation,
+     * ensuring that all changes trigger reactive updates.
+     */
+    $patchDeep: (partial: StorePatch<S>) => void;
+    /** Get raw state object (non-reactive snapshot) */
+    $state: S;
+  };
+
+/**
+ * Plugin that can extend store functionality.
+ */
+export type StorePlugin<S = unknown> = (context: {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  store: Store<any, any, any>;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  options: StoreDefinition<any, any, any>;
+}) => Partial<S> | void;

package/src/store/utils.ts

@@ -0,0 +1,141 @@
+/**
+ * Internal utilities for the store module.
+ * @internal
+ */
+
+/**
+ * Check if a value is a plain object (not array, null, Date, etc.).
+ * @internal
+ */
+export const isPlainObject = (value: unknown): value is Record<string, unknown> => {
+  return (
+    value !== null && typeof value === 'object' && Object.getPrototypeOf(value) === Object.prototype
+  );
+};
+
+/**
+ * Deep clones an object. Used for deep reactivity support.
+ * @internal
+ */
+export const deepClone = <T>(obj: T): T => {
+  if (obj === null || typeof obj !== 'object') {
+    return obj;
+  }
+
+  if (Array.isArray(obj)) {
+    return obj.map(deepClone) as T;
+  }
+
+  if (obj instanceof Date) {
+    return new Date(obj.getTime()) as T;
+  }
+
+  if (obj instanceof Map) {
+    return new Map(Array.from(obj.entries()).map(([k, v]) => [k, deepClone(v)])) as T;
+  }
+
+  if (obj instanceof Set) {
+    return new Set(Array.from(obj).map(deepClone)) as T;
+  }
+
+  const cloned = {} as T;
+  for (const key of Object.keys(obj)) {
+    (cloned as Record<string, unknown>)[key] = deepClone((obj as Record<string, unknown>)[key]);
+  }
+  return cloned;
+};
+
+/**
+ * Compares two values for deep equality.
+ * @internal
+ */
+export const deepEqual = (a: unknown, b: unknown): boolean => {
+  if (a === b) return true;
+  if (a === null || b === null) return false;
+  if (typeof a !== 'object' || typeof b !== 'object') return false;
+
+  if (a instanceof Date && b instanceof Date) {
+    return a.getTime() === b.getTime();
+  }
+
+  if (a instanceof Map && b instanceof Map) {
+    if (a.size !== b.size) return false;
+    for (const [key, value] of a.entries()) {
+      if (!b.has(key) || !deepEqual(value, b.get(key))) return false;
+    }
+    return true;
+  }
+
+  if (a instanceof Set && b instanceof Set) {
+    if (a.size !== b.size) return false;
+    for (const value of a.values()) {
+      let found = false;
+      for (const candidate of b.values()) {
+        if (deepEqual(value, candidate)) {
+          found = true;
+          break;
+        }
+      }
+      if (!found) return false;
+    }
+    return true;
+  }
+
+  if (Array.isArray(a) && Array.isArray(b)) {
+    if (a.length !== b.length) return false;
+    return a.every((item, i) => deepEqual(item, b[i]));
+  }
+
+  if (Array.isArray(a) !== Array.isArray(b)) return false;
+
+  const keysA = Object.keys(a as object);
+  const keysB = Object.keys(b as object);
+
+  if (keysA.length !== keysB.length) return false;
+
+  return keysA.every((key) =>
+    deepEqual((a as Record<string, unknown>)[key], (b as Record<string, unknown>)[key])
+  );
+};
+
+/**
+ * Detects if nested objects were mutated but the reference stayed the same.
+ * Returns the keys where nested mutations were detected.
+ * @internal
+ */
+export const detectNestedMutations = <S extends Record<string, unknown>>(
+  before: S,
+  after: S,
+  signalValues: Map<keyof S, unknown>
+): Array<keyof S> => {
+  const mutatedKeys: Array<keyof S> = [];
+
+  for (const key of Object.keys(after) as Array<keyof S>) {
+    const beforeValue = before[key];
+    const afterValue = after[key];
+    const signalValue = signalValues.get(key);
+
+    // Check if it's the same reference but content changed
+    if (
+      signalValue === afterValue &&
+      isPlainObject(beforeValue) &&
+      isPlainObject(afterValue) &&
+      !deepEqual(beforeValue, afterValue)
+    ) {
+      mutatedKeys.push(key);
+    }
+  }
+
+  return mutatedKeys;
+};
+
+/** @internal Flag to enable/disable development warnings */
+export const isDev = (() => {
+  try {
+    const globalProcess = (globalThis as { process?: { env?: { NODE_ENV?: string } } }).process;
+    // Default to dev mode unless explicitly set to production
+    return !(typeof globalProcess !== 'undefined' && globalProcess.env?.NODE_ENV === 'production');
+  } catch {
+    return true;
+  }
+})();

package/src/store/watch.ts

@@ -0,0 +1,52 @@
+/**
+ * Store watch helpers.
+ */
+
+import type { Store } from './types';
+import { deepEqual } from './utils';
+
+export type WatchStoreOptions<T> = {
+  /** Call the callback immediately with the current value. */
+  immediate?: boolean;
+  /** Use deep comparison when determining changes. */
+  deep?: boolean;
+  /** Custom equality check for selected values. */
+  equals?: (a: T, b: T) => boolean;
+};
+
+/**
+ * Watch a selected slice of store state.
+ *
+ * @param store - The store instance
+ * @param selector - Function to select the watched value
+ * @param callback - Called when the selected value changes
+ * @param options - Watch options
+ * @returns Unsubscribe function
+ */
+export const watchStore = <
+  S extends Record<string, unknown>,
+  G extends Record<string, unknown>,
+  A extends Record<string, (...args: unknown[]) => unknown>,
+  T,
+>(
+  store: Store<S, G, A>,
+  selector: (state: S) => T,
+  callback: (value: T, previous: T | undefined) => void,
+  options: WatchStoreOptions<T> = {}
+): (() => void) => {
+  const equals = options.equals ?? (options.deep ? deepEqual : Object.is);
+  let previous = selector(store.$state);
+
+  if (options.immediate) {
+    callback(previous, undefined);
+  }
+
+  return store.$subscribe((state) => {
+    const current = selector(state);
+    if (!equals(current, previous)) {
+      const prev = previous;
+      previous = current;
+      callback(current, prev);
+    }
+  });
+};

package/src/view/directives/bind.ts

@@ -0,0 +1,23 @@
+import { effect } from '../../reactive/index';
+import { evaluate } from '../evaluate';
+import type { DirectiveHandler } from '../types';
+
+/**
+ * Handles bq-bind:attr directive - attribute binding.
+ * @internal
+ */
+export const handleBind = (attrName: string): DirectiveHandler => {
+  return (el, expression, context, cleanups) => {
+    const cleanup = effect(() => {
+      const value = evaluate(expression, context);
+      if (value == null || value === false) {
+        el.removeAttribute(attrName);
+      } else if (value === true) {
+        el.setAttribute(attrName, '');
+      } else {
+        el.setAttribute(attrName, String(value));
+      }
+    });
+    cleanups.push(cleanup);
+  };
+};

package/src/view/directives/class.ts

@@ -0,0 +1,70 @@
+import { effect } from '../../reactive/index';
+import { evaluate, parseObjectExpression } from '../evaluate';
+import type { DirectiveHandler } from '../types';
+
+/**
+ * Handles bq-class directive - dynamic class binding.
+ * Tracks previously added classes to ensure proper cleanup when expressions change.
+ * @internal
+ */
+export const handleClass: DirectiveHandler = (el, expression, context, cleanups) => {
+  // Track classes added by this directive to clean them up on re-evaluation
+  let previousClasses: Set<string> = new Set();
+
+  const cleanup = effect(() => {
+    const newClasses: Set<string> = new Set();
+
+    if (expression.trimStart().startsWith('{')) {
+      // Object syntax: { active: isActive, disabled: !enabled }
+      const classMap = parseObjectExpression(expression);
+      for (const [className, conditionExpr] of Object.entries(classMap)) {
+        const condition = evaluate<boolean>(conditionExpr, context);
+        el.classList.toggle(className, Boolean(condition));
+        // Track class regardless of condition - toggle handles add/remove
+        newClasses.add(className);
+      }
+    } else if (/^\s*\[/.test(expression)) {
+      // Array literal syntax: [class1, class2]
+      const classes = evaluate<string[]>(expression, context);
+      if (Array.isArray(classes)) {
+        for (const cls of classes) {
+          if (cls) {
+            el.classList.add(cls);
+            newClasses.add(cls);
+          }
+        }
+      }
+    } else {
+      // Single expression returning string or array
+      const result = evaluate<string | string[]>(expression, context);
+      if (typeof result === 'string') {
+        result.split(/\s+/).forEach((cls) => {
+          if (cls) {
+            el.classList.add(cls);
+            newClasses.add(cls);
+          }
+        });
+      } else if (Array.isArray(result)) {
+        result.forEach((cls) => {
+          if (cls) {
+            el.classList.add(cls);
+            newClasses.add(cls);
+          }
+        });
+      }
+    }
+
+    // Remove classes that were previously added but are no longer in the new set
+    // This keeps directive-managed classes in sync across all syntax forms and provides
+    // defensive cleanup behavior for edge cases (e.g. external classList changes)
+    for (const cls of previousClasses) {
+      if (!newClasses.has(cls)) {
+        el.classList.remove(cls);
+      }
+    }
+
+    previousClasses = newClasses;
+  });
+
+  cleanups.push(cleanup);
+};