@bquery/bquery 1.5.0 → 1.6.0

package/src/security/sanitize.ts

@@ -1,66 +1,70 @@
-/**
- * Security utilities for HTML sanitization.
- * All DOM writes are sanitized by default to prevent XSS attacks.
- *
- * @module bquery/security
- */
-
-import { sanitizeHtmlCore } from './sanitize-core';
-import type { SanitizeOptions } from './types';
-export { generateNonce } from './csp';
-export { isTrustedTypesSupported } from './trusted-types';
-
-/**
- * Sanitize HTML string, removing dangerous elements and attributes.
- * Uses Trusted Types when available for CSP compliance.
- *
- * @param html - The HTML string to sanitize
- * @param options - Sanitization options
- * @returns Sanitized HTML string
- *
- * @example
- * ```ts
- * const safe = sanitizeHtml('<div onclick="alert(1)">Hello</div>');
- * // Returns: '<div>Hello</div>'
- * ```
- */
-export const sanitizeHtml = (html: string, options: SanitizeOptions = {}): string => {
-  return sanitizeHtmlCore(html, options);
-};
-
-/**
- * Escape HTML entities to prevent XSS.
- * Use this for displaying user content as text.
- *
- * @param text - The text to escape
- * @returns Escaped HTML string
- *
- * @example
- * ```ts
- * escapeHtml('<script>alert(1)</script>');
- * // Returns: '&lt;script&gt;alert(1)&lt;/script&gt;'
- * ```
- */
-export const escapeHtml = (text: string): string => {
-  const escapeMap: Record<string, string> = {
-    '&': '&amp;',
-    '<': '&lt;',
-    '>': '&gt;',
-    '"': '&quot;',
-    "'": '&#x27;',
-    '`': '&#x60;',
-  };
-  return text.replace(/[&<>"'`]/g, (char) => escapeMap[char]);
-};
-
-/**
- * Strip all HTML tags and return plain text.
- *
- * @param html - The HTML string to strip
- * @returns Plain text content
- */
-export const stripTags = (html: string): string => {
-  return sanitizeHtmlCore(html, { stripAllTags: true });
-};
-
-export type { SanitizeOptions } from './types';
+/**
+ * Security utilities for HTML sanitization.
+ * All DOM writes are sanitized by default to prevent XSS attacks.
+ *
+ * @module bquery/security
+ */
+
+import { sanitizeHtmlCore } from './sanitize-core';
+import { toSanitizedHtml } from './trusted-html';
+import type { SanitizedHtml } from './trusted-html';
+import type { SanitizeOptions } from './types';
+export { generateNonce } from './csp';
+export { isTrustedTypesSupported } from './trusted-types';
+export { trusted } from './trusted-html';
+export type { SanitizedHtml, TrustedHtml } from './trusted-html';
+
+/**
+ * Sanitize HTML string, removing dangerous elements and attributes.
+ * Uses Trusted Types when available for CSP compliance.
+ *
+ * @param html - The HTML string to sanitize
+ * @param options - Sanitization options
+ * @returns Sanitized HTML string
+ *
+ * @example
+ * ```ts
+ * const safe = sanitizeHtml('<div onclick="alert(1)">Hello</div>');
+ * // Returns: '<div>Hello</div>'
+ * ```
+ */
+export const sanitizeHtml = (html: string, options: SanitizeOptions = {}): SanitizedHtml => {
+  return toSanitizedHtml(sanitizeHtmlCore(html, options));
+};
+
+/**
+ * Escape HTML entities to prevent XSS.
+ * Use this for displaying user content as text.
+ *
+ * @param text - The text to escape
+ * @returns Escaped HTML string
+ *
+ * @example
+ * ```ts
+ * escapeHtml('<script>alert(1)</script>');
+ * // Returns: '&lt;script&gt;alert(1)&lt;/script&gt;'
+ * ```
+ */
+export const escapeHtml = (text: string): string => {
+  const escapeMap: Record<string, string> = {
+    '&': '&amp;',
+    '<': '&lt;',
+    '>': '&gt;',
+    '"': '&quot;',
+    "'": '&#x27;',
+    '`': '&#x60;',
+  };
+  return text.replace(/[&<>"'`]/g, (char) => escapeMap[char]);
+};
+
+/**
+ * Strip all HTML tags and return plain text.
+ *
+ * @param html - The HTML string to strip
+ * @returns Plain text content
+ */
+export const stripTags = (html: string): string => {
+  return sanitizeHtmlCore(html, { stripAllTags: true });
+};
+
+export type { SanitizeOptions } from './types';

package/src/security/trusted-html.ts

@@ -0,0 +1,71 @@
+declare const sanitizedHtmlBrand: unique symbol;
+const trustedHtmlBrand: unique symbol = Symbol('bquery.trusted-html.brand');
+const TRUSTED_HTML_VALUE = Symbol('bquery.trusted-html');
+
+/**
+ * Branded HTML string produced by bQuery's sanitization or escaping template helpers.
+ *
+ * Values returned from {@link sanitizeHtml} carry sanitized markup. Values returned from
+ * {@link safeHtml} preserve the template's static markup while escaping normal interpolations
+ * and splicing {@link trusted} fragments verbatim. This brand is not intended for arbitrary
+ * strings or manual concatenation outside those helpers.
+ */
+export type SanitizedHtml = string & { readonly [sanitizedHtmlBrand]: true };
+
+/**
+ * Marker object that safeHtml can splice into templates without escaping again.
+ */
+export type TrustedHtml = { readonly [trustedHtmlBrand]: true; toString(): string };
+
+type TrustedHtmlValue = TrustedHtml & { readonly [TRUSTED_HTML_VALUE]: string };
+
+/**
+ * Apply the internal {@link SanitizedHtml} brand to helper output.
+ *
+ * @internal
+ */
+export const toSanitizedHtml = (html: string): SanitizedHtml => html as SanitizedHtml;
+
+/**
+ * Mark a sanitized HTML string for verbatim splicing into safeHtml templates.
+ *
+ * @param html - HTML previously produced by sanitizeHtml, safeHtml, or another trusted bQuery helper
+ * @returns Trusted HTML marker object for safeHtml interpolations
+ *
+ * @example
+ * ```ts
+ * const badge = trusted(sanitizeHtml('<strong onclick="alert(1)">New</strong>'));
+ * const markup = safeHtml`<span>${badge}</span>`;
+ * ```
+ */
+export const trusted = (html: SanitizedHtml): TrustedHtml => {
+  const value = String(html);
+  return Object.freeze({
+    [trustedHtmlBrand]: true as const,
+    [TRUSTED_HTML_VALUE]: value,
+    toString: () => value,
+  });
+};
+
+/**
+ * Check whether a value is a trusted HTML marker created by trusted().
+ *
+ * @internal
+ */
+export const isTrustedHtml = (value: unknown): value is TrustedHtml => {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    trustedHtmlBrand in value &&
+    TRUSTED_HTML_VALUE in value
+  );
+};
+
+/**
+ * Unwrap the raw HTML string stored inside a trusted HTML marker.
+ *
+ * @internal
+ */
+export const unwrapTrustedHtml = (value: TrustedHtml): string => {
+  return (value as TrustedHtmlValue)[TRUSTED_HTML_VALUE];
+};

package/src/store/define-store.ts

@@ -1,48 +1,49 @@
-/**
- * Store factory helpers.
- */
-
-import { createStore } from './create-store';
-import { getStore, hasStore } from './registry';
-import type { Store, StoreDefinition } from './types';
-
-/**
- * Creates a store factory that returns the store instance.
- *
- * The store is lazily created on first call and cached in the global store
- * registry. Subsequent calls return the same instance. After calling
- * `destroyStore(id)`, the next factory call will create a fresh store.
- *
- * @param id - Store identifier
- * @param definition - Store definition without id
- * @returns A function that returns the store instance
- *
- * @example
- * ```ts
- * const useCounter = defineStore('counter', {
- *   state: () => ({ count: 0 }),
- *   actions: { increment() { this.count++; } },
- * });
- *
- * const counter = useCounter();
- * counter.increment();
- * ```
- */
-export const defineStore = <
-  S extends Record<string, unknown>,
-  G extends Record<string, unknown> = Record<string, never>,
-  A extends Record<string, (...args: unknown[]) => unknown> = Record<string, never>,
->(
-  id: string,
-  definition: Omit<StoreDefinition<S, G, A>, 'id'>
-): (() => Store<S, G, A>) => {
-  // Check registry first to avoid noisy warnings from createStore()
-  // when the factory is called multiple times (intended usage pattern).
-  // createStore() only called when store doesn't exist or was destroyed.
-  return () => {
-    if (hasStore(id)) {
-      return getStore(id) as Store<S, G, A>;
-    }
-    return createStore({ id, ...definition });
-  };
-};
+/**
+ * Store factory helpers.
+ */
+
+import { createStore } from './create-store';
+import { getStore, hasStore } from './registry';
+import type { Store, StoreDefinition } from './types';
+
+/**
+ * Creates a store factory that returns the store instance.
+ *
+ * The store is lazily created on first call and cached in the global store
+ * registry. Subsequent calls return the same instance. After calling
+ * `destroyStore(id)`, the next factory call will create a fresh store.
+ *
+ * @param id - Store identifier
+ * @param definition - Store definition without id
+ * @returns A function that returns the store instance
+ *
+ * @example
+ * ```ts
+ * const useCounter = defineStore('counter', {
+ *   state: () => ({ count: 0 }),
+ *   actions: { increment() { this.count++; } },
+ * });
+ *
+ * const counter = useCounter();
+ * counter.increment();
+ * ```
+ */
+export const defineStore = <
+  S extends Record<string, unknown>,
+  G extends Record<string, unknown> = Record<string, never>,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- actions may declare specific parameter types
+  A extends Record<string, (...args: any[]) => any> = Record<string, never>,
+>(
+  id: string,
+  definition: Omit<StoreDefinition<S, G, A>, 'id'>
+): (() => Store<S, G, A>) => {
+  // Check registry first to avoid noisy warnings from createStore()
+  // when the factory is called multiple times (intended usage pattern).
+  // createStore() only called when store doesn't exist or was destroyed.
+  return () => {
+    if (hasStore(id)) {
+      return getStore(id) as Store<S, G, A>;
+    }
+    return createStore({ id, ...definition });
+  };
+};

package/src/store/mapping.ts

@@ -1,73 +1,74 @@
-/**
- * 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;
-};
+/**
+ * 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 = <
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- actions may declare specific parameter types
+  A extends Record<string, (...args: any[]) => any>,
+  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

@@ -1,61 +1,62 @@
-/**
- * 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;
-};
+/**
+ * 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>,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- actions may declare specific parameter types
+  A extends Record<string, (...args: any[]) => any> = 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;
+};