@prabhask5/stellar-engine 1.1.6 → 1.1.8

package/dist/types.d.ts

@@ -1,118 +1,223 @@
 /**
- * Intent-Based Sync Operation Types
+ * @fileoverview Core Type Definitions for the Stellar Sync Engine
  *
- * These types enable preserving operation intent (e.g., "increment by 1")
- * rather than just final state (e.g., "current_value: 50").
+ * Defines the foundational TypeScript types used throughout the engine:
+ * - Intent-based sync operation types (preserving operation semantics)
+ * - Offline authentication types (credential caching, session tokens)
+ * - Conflict resolution types (field-level history tracking)
+ * - Single-user authentication types (PIN/password gate)
+ * - Device trust types (multi-device verification)
  *
- * Benefits:
- * - Rapid increments are coalesced locally (50 +1s -> single +50) reducing sync traffic
- * - Pending operations are protected during conflict resolution
- *
- * Note: True numeric merge across devices (e.g., +50 + +30 = +80) is not implemented.
- * Operations are converted to final values before pushing to Supabase, so conflicts
- * use last-write-wins. Full numeric merge would require an operation inbox system.
+ * Architecture note:
+ *   Operations use an intent-based model (e.g., "increment by 1") rather than
+ *   final-state snapshots (e.g., "current_value: 50"). This enables local
+ *   coalescing (50 rapid +1s become a single +50) and smarter conflict
+ *   resolution. See {@link queue.ts} for the coalescing implementation.
  */
 /**
- * Operation types that preserve intent:
- * - 'increment': Add delta to numeric field (e.g., current_value += 1)
- * - 'set': Set field to value (works for any type)
- * - 'create': Create new entity
- * - 'delete': Soft delete entity
+ * The four supported operation intents for the sync queue.
+ *
+ * Each intent carries different semantics during coalescing and push:
+ * - `'increment'` — Add a numeric delta to a field (coalesceable: multiple deltas sum)
+ * - `'set'`       — Overwrite field(s) with new value(s) (coalesceable: later sets win)
+ * - `'create'`    — Insert a new entity (coalesceable: subsequent sets merge into the create payload)
+ * - `'delete'`    — Soft-delete an entity (a create + delete pair cancels both out entirely)
  */
 export type OperationType = 'increment' | 'set' | 'create' | 'delete';
 /**
- * Intent-based sync operation item.
+ * A single intent-based sync operation stored in the IndexedDB `syncQueue` table.
+ *
+ * Design decisions:
+ * - `operationType` preserves the *intent* so the coalescer can intelligently merge
+ *   (e.g., 50 increment ops → one +50 instead of 50 separate server requests).
+ * - `field` is optional: increment/single-field set use it; create and multi-field
+ *   set store data in `value` instead.
+ * - `retries` and `lastRetryAt` power exponential backoff for failed pushes.
  *
- * Key design:
- * - Uses `operationType` to specify the operation intent
- * - Has optional `field` for field-level operations
- * - `value` is the delta (for increment) or new value (for set/create)
+ * @example
+ * // Increment operation: add 1 to `current_value`
+ * { table: "goals", entityId: "abc", operationType: "increment", field: "current_value", value: 1 }
  *
- * For create operations, value contains the full entity payload.
- * For increment operations, value contains the delta to add.
- * For set operations, value contains the new field value(s).
- * For delete operations, value is not used.
+ * // Multi-field set operation: update title and description
+ * { table: "goals", entityId: "abc", operationType: "set", value: { title: "New", description: "..." } }
+ *
+ * // Create operation: full entity payload in `value`
+ * { table: "goals", entityId: "abc", operationType: "create", value: { title: "Goal", target: 10 } }
  */
 export interface SyncOperationItem {
+    /** Auto-increment primary key (assigned by IndexedDB). */
     id?: number;
+    /** Supabase table name (e.g., `"goals"`, `"goal_lists"`). */
     table: string;
+    /** UUID of the entity being operated on. */
     entityId: string;
+    /** The operation intent: `'increment'`, `'set'`, `'create'`, or `'delete'`. */
     operationType: OperationType;
+    /** Target field name — used by increment and single-field set operations. */
     field?: string;
+    /** Payload — delta (increment), new value (set), full entity (create), or unused (delete). */
     value?: unknown;
+    /** ISO 8601 timestamp of when the operation was enqueued locally. */
     timestamp: string;
+    /** Number of failed push attempts (drives exponential backoff). */
     retries: number;
+    /** ISO 8601 timestamp of the last retry attempt (used for backoff calculation). */
     lastRetryAt?: string;
 }
+/**
+ * Cached credentials stored in IndexedDB for offline sign-in.
+ *
+ * Uses a singleton pattern (`id: 'current_user'`) so only one set of
+ * credentials is cached at a time. The password is stored as a SHA-256
+ * hash — legacy records may contain plaintext from before hashing was added.
+ *
+ * @see {@link auth/offlineCredentials.ts} for caching/verification logic
+ */
 export interface OfflineCredentials {
+    /** Singleton key — always `'current_user'`. */
     id: string;
+    /** Supabase user UUID. */
     userId: string;
+    /** User's email address. */
     email: string;
+    /** SHA-256 hash of the user's password (legacy records may be plaintext). */
     password: string;
+    /** App-specific profile data (e.g., `{ firstName, lastName }`). */
     profile: Record<string, unknown>;
+    /** ISO 8601 timestamp of when credentials were cached. */
     cachedAt: string;
 }
+/**
+ * Offline session token stored in IndexedDB.
+ *
+ * Created when the device goes offline (if credentials are cached) and
+ * consumed during offline sign-in to verify the user's identity without
+ * a network call.
+ *
+ * Sessions have no expiry — they are revoked only on:
+ *   1. Successful online re-authentication
+ *   2. Explicit logout
+ *
+ * @see {@link auth/offlineSession.ts} for session management
+ */
 export interface OfflineSession {
+    /** Singleton key — always `'current_session'`. */
     id: string;
+    /** Supabase user UUID. */
     userId: string;
+    /** Random UUID used as the offline session token. */
     offlineToken: string;
+    /** ISO 8601 timestamp of session creation. */
     createdAt: string;
 }
 /**
- * Conflict history entry (stored in IndexedDB)
- * Records field-level conflict resolutions for review and potential undo
+ * A single field-level conflict resolution record stored in IndexedDB.
+ *
+ * Recorded whenever the conflict resolution engine detects divergent values
+ * for the same field across devices. Entries are retained for 30 days to
+ * allow review and potential manual override.
+ *
+ * @see {@link conflicts.ts} for the three-tier resolution algorithm
  */
 export interface ConflictHistoryEntry {
+    /** Auto-increment primary key (assigned by IndexedDB). */
     id?: number;
+    /** UUID of the conflicting entity. */
     entityId: string;
+    /** Supabase table name (e.g., `"goals"`). */
     entityType: string;
+    /** Field that had conflicting values. */
     field: string;
+    /** Value from the local device. */
     localValue: unknown;
+    /** Value from the remote server. */
     remoteValue: unknown;
+    /** Final merged value written to IndexedDB. */
     resolvedValue: unknown;
+    /** Which side's value was chosen (or `'merged'` for numeric merges). */
     winner: 'local' | 'remote' | 'merged';
+    /** The strategy that resolved this conflict (e.g., `'last_write'`, `'delete_wins'`). */
     strategy: string;
+    /** ISO 8601 timestamp of when the conflict was resolved. */
     timestamp: string;
 }
+/**
+ * Current state of the sync engine's background loop.
+ *
+ * - `'idle'`    — No active sync; everything is up to date
+ * - `'syncing'` — Push or pull currently in progress
+ * - `'error'`   — Last sync attempt failed (will retry)
+ * - `'offline'` — Device has no network connectivity
+ */
 export type SyncStatus = 'idle' | 'syncing' | 'error' | 'offline';
+/**
+ * Authentication mode for the engine.
+ *
+ * - `'supabase'` — Standard Supabase email/password or OAuth auth
+ * - `'offline'`  — Using cached credentials (device is offline)
+ * - `'none'`     — No active authentication
+ */
 export type AuthMode = 'supabase' | 'offline' | 'none';
+/**
+ * The type of gate protecting single-user mode.
+ *
+ * - `'code'`     — Numeric PIN (4 or 6 digits)
+ * - `'password'` — Freeform password string
+ */
 export type SingleUserGateType = 'code' | 'password';
+/**
+ * Persistent configuration for single-user mode, stored in IndexedDB.
+ *
+ * Single-user mode replaces traditional email/password sign-in with a
+ * simplified local gate (PIN or password). Under the hood it still uses
+ * a real Supabase account — the PIN is padded to meet Supabase's minimum
+ * password length and used as the account password.
+ *
+ * Uses a singleton pattern (`id: 'config'`).
+ *
+ * @see {@link auth/singleUser.ts} for setup, unlock, and change flows
+ */
 export interface SingleUserConfig {
+    /** Singleton key — always `'config'`. */
     id: string;
+    /** Whether the gate is a numeric code or a freeform password. */
     gateType: SingleUserGateType;
+    /** Digit count for code gates (4 or 6). Only set when `gateType === 'code'`. */
     codeLength?: 4 | 6;
+    /** SHA-256 hash of the code/password (deprecated — kept for offline fallback verification). */
     gateHash?: string;
+    /** Email address used for the underlying Supabase account. */
     email?: string;
+    /** App-specific profile data (e.g., `{ firstName, lastName }`). */
     profile: Record<string, unknown>;
+    /** Supabase user UUID (set after first successful online setup). */
     supabaseUserId?: string;
+    /** ISO 8601 timestamp of initial setup. */
     setupAt: string;
+    /** ISO 8601 timestamp of last configuration change. */
     updatedAt: string;
 }
+/**
+ * A trusted device record stored in the Supabase `trusted_devices` table.
+ *
+ * When device verification is enabled, untrusted devices must complete an
+ * email OTP challenge before they can access data. Once verified, the device
+ * is trusted for a configurable duration (default: 90 days).
+ *
+ * @see {@link auth/deviceVerification.ts} for the trust/verify flow
+ */
 export interface TrustedDevice {
+    /** Row UUID (primary key in Supabase). */
     id: string;
+    /** Supabase user UUID who owns this device. */
     userId: string;
+    /** Stable device identifier from localStorage. */
     deviceId: string;
+    /** Human-readable device label (e.g., browser + OS). */
     deviceLabel?: string;
+    /** ISO 8601 timestamp of when the device was first trusted. */
     trustedAt: string;
+    /** ISO 8601 timestamp of the device's most recent use. */
     lastUsedAt: string;
 }
-/**
- * Base interface for all syncable entities.
- * Every entity managed by the sync engine has these fields.
- */
-export interface SyncableEntity {
-    id: string;
-    created_at: string;
-    updated_at: string;
-    deleted?: boolean;
-    _version?: number;
-    device_id?: string | null;
-}
-/**
- * Base interface for entities owned by a user.
- * Extends SyncableEntity with a user_id field.
- */
-export interface UserOwnedEntity extends SyncableEntity {
-    user_id: string;
-}
 //# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -1,16 +1,18 @@
 /**
- * Intent-Based Sync Operation Types
+ * @fileoverview Core Type Definitions for the Stellar Sync Engine
  *
- * These types enable preserving operation intent (e.g., "increment by 1")
- * rather than just final state (e.g., "current_value: 50").
+ * Defines the foundational TypeScript types used throughout the engine:
+ * - Intent-based sync operation types (preserving operation semantics)
+ * - Offline authentication types (credential caching, session tokens)
+ * - Conflict resolution types (field-level history tracking)
+ * - Single-user authentication types (PIN/password gate)
+ * - Device trust types (multi-device verification)
  *
- * Benefits:
- * - Rapid increments are coalesced locally (50 +1s -> single +50) reducing sync traffic
- * - Pending operations are protected during conflict resolution
- *
- * Note: True numeric merge across devices (e.g., +50 + +30 = +80) is not implemented.
- * Operations are converted to final values before pushing to Supabase, so conflicts
- * use last-write-wins. Full numeric merge would require an operation inbox system.
+ * Architecture note:
+ *   Operations use an intent-based model (e.g., "increment by 1") rather than
+ *   final-state snapshots (e.g., "current_value: 50"). This enables local
+ *   coalescing (50 rapid +1s become a single +50) and smarter conflict
+ *   resolution. See {@link queue.ts} for the coalescing implementation.
  */
 export {};
 //# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG"}

package/dist/utils.d.ts

@@ -1,29 +1,71 @@
 /**
- * Common utility functions for sync engine consumers.
+ * @fileoverview Common Utility Functions
+ *
+ * Small, pure helper functions used across the sync engine and exposed
+ * to consumers via the `@prabhask5/stellar-engine/utils` subpath export.
+ *
+ * All functions in this module are side-effect-free and safe to call in
+ * both browser and SSR contexts.
  */
 /**
- * Convert a snake_case string to a safe camelCase identifier.
- * Strips invalid characters (keeps only alphanumeric and underscores),
- * then converts snake_case to camelCase.
- * e.g. 'goal_lists' → 'goalLists', 'goals' → 'goals', 'my-table!' → 'mytable'
+ * Convert a `snake_case` string to a safe `camelCase` identifier.
+ *
+ * First strips any characters that are not alphanumeric or underscores,
+ * then converts underscore-separated words to camelCase.
+ *
+ * Used internally to derive Dexie (IndexedDB) table names from Supabase
+ * snake_case table names.
+ *
+ * @param s - The snake_case string to convert.
+ * @returns The camelCase equivalent.
+ *
+ * @example
+ * snakeToCamel('goal_lists');  // → 'goalLists'
+ * snakeToCamel('goals');       // → 'goals'
+ * snakeToCamel('my-table!');   // → 'mytable' (invalid chars stripped first)
  */
 export declare function snakeToCamel(s: string): string;
 /**
- * Generate a UUID v4 (random UUID).
+ * Generate a UUID v4 (random UUID) using the native Web Crypto API.
+ *
+ * Suitable for entity primary keys, device IDs, and any context where
+ * a universally unique identifier is needed.
+ *
+ * @returns A lowercase UUID v4 string (e.g., `"550e8400-e29b-41d4-a716-446655440000"`).
  */
 export declare function generateId(): string;
 /**
- * Get the current timestamp as an ISO string.
+ * Get the current timestamp as an ISO 8601 string.
+ *
+ * Convenience wrapper around `new Date().toISOString()` used as the
+ * default value for `created_at`, `updated_at`, and sync operation
+ * timestamps throughout the engine.
+ *
+ * @returns An ISO 8601 timestamp string (e.g., `"2025-01-15T12:30:00.000Z"`).
  */
 export declare function now(): string;
 /**
- * Calculate new order value when moving an item to a new position.
- * Uses fractional ordering to minimize updates.
+ * Calculate a new `order` value when moving an item to a different position.
+ *
+ * Uses **fractional ordering** so that only the moved item's `order` value
+ * changes — no need to re-index the entire list. The new value is placed
+ * at the midpoint between its new neighbours.
+ *
+ * Includes a guard against floating-point precision exhaustion: if the
+ * midpoint collapses to either bound, a small epsilon nudge is applied
+ * instead. In practice, precision issues only arise after ~50 consecutive
+ * moves between the same two items.
+ *
+ * @typeParam T - Any object with a numeric `order` property.
+ * @param items     - The sorted array of items (by `order`, ascending).
+ * @param fromIndex - Current index of the item being moved.
+ * @param toIndex   - Target index where the item should be placed.
+ * @returns The new `order` value for the moved item.
  *
- * @param items - The sorted array of items with order property
- * @param fromIndex - Current index of the item being moved
- * @param toIndex - Target index where the item should be placed
- * @returns The new order value for the moved item
+ * @example
+ * const items = [{ order: 1 }, { order: 2 }, { order: 3 }];
+ * calculateNewOrder(items, 2, 0); // → 0 (before the first item)
+ * calculateNewOrder(items, 0, 1); // → 2.5 (between items[1] and items[2])
  */
 export declare function calculateNewOrder<T extends {
     order: number;

package/dist/utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAE9C;AAED;;GAEG;AACH,wBAAgB,UAAU,IAAI,MAAM,CAEnC;AAED;;GAEG;AACH,wBAAgB,GAAG,IAAI,MAAM,CAE5B;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,SAAS;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,EAC3D,KAAK,EAAE,CAAC,EAAE,EACV,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,GACd,MAAM,CA2CR"}
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAMH;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAE9C;AAMD;;;;;;;GAOG;AACH,wBAAgB,UAAU,IAAI,MAAM,CAEnC;AAMD;;;;;;;;GAQG;AACH,wBAAgB,GAAG,IAAI,MAAM,CAE5B;AAMD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,SAAS;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,EAC3D,KAAK,EAAE,CAAC,EAAE,EACV,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,GACd,MAAM,CAkDR"}

package/dist/utils.js

@@ -1,68 +1,129 @@
 /**
- * Common utility functions for sync engine consumers.
+ * @fileoverview Common Utility Functions
+ *
+ * Small, pure helper functions used across the sync engine and exposed
+ * to consumers via the `@prabhask5/stellar-engine/utils` subpath export.
+ *
+ * All functions in this module are side-effect-free and safe to call in
+ * both browser and SSR contexts.
  */
+// =============================================================================
+// String Utilities
+// =============================================================================
 /**
- * Convert a snake_case string to a safe camelCase identifier.
- * Strips invalid characters (keeps only alphanumeric and underscores),
- * then converts snake_case to camelCase.
- * e.g. 'goal_lists' → 'goalLists', 'goals' → 'goals', 'my-table!' → 'mytable'
+ * Convert a `snake_case` string to a safe `camelCase` identifier.
+ *
+ * First strips any characters that are not alphanumeric or underscores,
+ * then converts underscore-separated words to camelCase.
+ *
+ * Used internally to derive Dexie (IndexedDB) table names from Supabase
+ * snake_case table names.
+ *
+ * @param s - The snake_case string to convert.
+ * @returns The camelCase equivalent.
+ *
+ * @example
+ * snakeToCamel('goal_lists');  // → 'goalLists'
+ * snakeToCamel('goals');       // → 'goals'
+ * snakeToCamel('my-table!');   // → 'mytable' (invalid chars stripped first)
  */
 export function snakeToCamel(s) {
     return s.replace(/[^a-zA-Z0-9_]/g, '').replace(/_([a-z])/g, (_, c) => c.toUpperCase());
 }
+// =============================================================================
+// ID Generation
+// =============================================================================
 /**
- * Generate a UUID v4 (random UUID).
+ * Generate a UUID v4 (random UUID) using the native Web Crypto API.
+ *
+ * Suitable for entity primary keys, device IDs, and any context where
+ * a universally unique identifier is needed.
+ *
+ * @returns A lowercase UUID v4 string (e.g., `"550e8400-e29b-41d4-a716-446655440000"`).
  */
 export function generateId() {
     return crypto.randomUUID();
 }
+// =============================================================================
+// Timestamp Utilities
+// =============================================================================
 /**
- * Get the current timestamp as an ISO string.
+ * Get the current timestamp as an ISO 8601 string.
+ *
+ * Convenience wrapper around `new Date().toISOString()` used as the
+ * default value for `created_at`, `updated_at`, and sync operation
+ * timestamps throughout the engine.
+ *
+ * @returns An ISO 8601 timestamp string (e.g., `"2025-01-15T12:30:00.000Z"`).
  */
 export function now() {
     return new Date().toISOString();
 }
+// =============================================================================
+// Ordering Utilities
+// =============================================================================
 /**
- * Calculate new order value when moving an item to a new position.
- * Uses fractional ordering to minimize updates.
+ * Calculate a new `order` value when moving an item to a different position.
+ *
+ * Uses **fractional ordering** so that only the moved item's `order` value
+ * changes — no need to re-index the entire list. The new value is placed
+ * at the midpoint between its new neighbours.
+ *
+ * Includes a guard against floating-point precision exhaustion: if the
+ * midpoint collapses to either bound, a small epsilon nudge is applied
+ * instead. In practice, precision issues only arise after ~50 consecutive
+ * moves between the same two items.
+ *
+ * @typeParam T - Any object with a numeric `order` property.
+ * @param items     - The sorted array of items (by `order`, ascending).
+ * @param fromIndex - Current index of the item being moved.
+ * @param toIndex   - Target index where the item should be placed.
+ * @returns The new `order` value for the moved item.
  *
- * @param items - The sorted array of items with order property
- * @param fromIndex - Current index of the item being moved
- * @param toIndex - Target index where the item should be placed
- * @returns The new order value for the moved item
+ * @example
+ * const items = [{ order: 1 }, { order: 2 }, { order: 3 }];
+ * calculateNewOrder(items, 2, 0); // → 0 (before the first item)
+ * calculateNewOrder(items, 0, 1); // → 2.5 (between items[1] and items[2])
  */
 export function calculateNewOrder(items, fromIndex, toIndex) {
-    // No movement
+    /* No movement — return the item's existing order. */
     if (fromIndex === toIndex) {
         return items[fromIndex].order;
     }
-    // Moving to the beginning
+    /* Moving to the beginning — place 1 unit before the current first item. */
     if (toIndex === 0) {
         return items[0].order - 1;
     }
-    // Moving to the end
+    /* Moving to the end — place 1 unit after the current last item. */
     if (toIndex === items.length - 1) {
         return items[items.length - 1].order + 1;
     }
-    // Moving between two items
-    // Account for the shift that happens when removing the item from its original position
+    /*
+     * Moving between two existing items.
+     * Account for the index shift that occurs when the item is removed
+     * from its original position before being re-inserted.
+     */
     let prevIndex;
     let nextIndex;
     if (fromIndex < toIndex) {
-        // Moving down: the item will be placed between toIndex and toIndex + 1
+        /* Moving down: the item lands between toIndex and toIndex + 1. */
         prevIndex = toIndex;
         nextIndex = toIndex + 1;
     }
     else {
-        // Moving up: the item will be placed between toIndex - 1 and toIndex
+        /* Moving up: the item lands between toIndex - 1 and toIndex. */
         prevIndex = toIndex - 1;
         nextIndex = toIndex;
     }
     const prevOrder = items[prevIndex].order;
     const nextOrder = items[nextIndex].order;
     const midpoint = (prevOrder + nextOrder) / 2;
-    // Guard against floating-point precision exhaustion:
-    // if the midpoint collapses to either bound, nudge by a small epsilon
+    /*
+     * Guard against floating-point precision exhaustion:
+     * If the midpoint collapses to either bound (i.e., they're so close
+     * that IEEE 754 can't represent a value between them), nudge by a
+     * small epsilon instead.
+     */
     if (midpoint === prevOrder || midpoint === nextOrder) {
         return prevOrder + Number.EPSILON * 100;
     }

package/dist/utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"utils.js","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAAC,CAAS;IACpC,OAAO,CAAC,CAAC,OAAO,CAAC,gBAAgB,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC;AACzF,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,UAAU;IACxB,OAAO,MAAM,CAAC,UAAU,EAAE,CAAC;AAC7B,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,GAAG;IACjB,OAAO,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;AAClC,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,iBAAiB,CAC/B,KAAU,EACV,SAAiB,EACjB,OAAe;IAEf,cAAc;IACd,IAAI,SAAS,KAAK,OAAO,EAAE,CAAC;QAC1B,OAAO,KAAK,CAAC,SAAS,CAAC,CAAC,KAAK,CAAC;IAChC,CAAC;IAED,0BAA0B;IAC1B,IAAI,OAAO,KAAK,CAAC,EAAE,CAAC;QAClB,OAAO,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC;IAC5B,CAAC;IAED,oBAAoB;IACpB,IAAI,OAAO,KAAK,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACjC,OAAO,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC;IAC3C,CAAC;IAED,2BAA2B;IAC3B,uFAAuF;IACvF,IAAI,SAAiB,CAAC;IACtB,IAAI,SAAiB,CAAC;IAEtB,IAAI,SAAS,GAAG,OAAO,EAAE,CAAC;QACxB,uEAAuE;QACvE,SAAS,GAAG,OAAO,CAAC;QACpB,SAAS,GAAG,OAAO,GAAG,CAAC,CAAC;IAC1B,CAAC;SAAM,CAAC;QACN,qEAAqE;QACrE,SAAS,GAAG,OAAO,GAAG,CAAC,CAAC;QACxB,SAAS,GAAG,OAAO,CAAC;IACtB,CAAC;IAED,MAAM,SAAS,GAAG,KAAK,CAAC,SAAS,CAAC,CAAC,KAAK,CAAC;IACzC,MAAM,SAAS,GAAG,KAAK,CAAC,SAAS,CAAC,CAAC,KAAK,CAAC;IAEzC,MAAM,QAAQ,GAAG,CAAC,SAAS,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC;IAE7C,qDAAqD;IACrD,sEAAsE;IACtE,IAAI,QAAQ,KAAK,SAAS,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;QACrD,OAAO,SAAS,GAAG,MAAM,CAAC,OAAO,GAAG,GAAG,CAAC;IAC1C,CAAC;IAED,OAAO,QAAQ,CAAC;AAClB,CAAC"}
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,gFAAgF;AAChF,mBAAmB;AACnB,gFAAgF;AAEhF;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,YAAY,CAAC,CAAS;IACpC,OAAO,CAAC,CAAC,OAAO,CAAC,gBAAgB,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC;AACzF,CAAC;AAED,gFAAgF;AAChF,gBAAgB;AAChB,gFAAgF;AAEhF;;;;;;;GAOG;AACH,MAAM,UAAU,UAAU;IACxB,OAAO,MAAM,CAAC,UAAU,EAAE,CAAC;AAC7B,CAAC;AAED,gFAAgF;AAChF,sBAAsB;AACtB,gFAAgF;AAEhF;;;;;;;;GAQG;AACH,MAAM,UAAU,GAAG;IACjB,OAAO,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;AAClC,CAAC;AAED,gFAAgF;AAChF,qBAAqB;AACrB,gFAAgF;AAEhF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,UAAU,iBAAiB,CAC/B,KAAU,EACV,SAAiB,EACjB,OAAe;IAEf,qDAAqD;IACrD,IAAI,SAAS,KAAK,OAAO,EAAE,CAAC;QAC1B,OAAO,KAAK,CAAC,SAAS,CAAC,CAAC,KAAK,CAAC;IAChC,CAAC;IAED,2EAA2E;IAC3E,IAAI,OAAO,KAAK,CAAC,EAAE,CAAC;QAClB,OAAO,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC;IAC5B,CAAC;IAED,mEAAmE;IACnE,IAAI,OAAO,KAAK,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACjC,OAAO,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC;IAC3C,CAAC;IAED;;;;OAIG;IACH,IAAI,SAAiB,CAAC;IACtB,IAAI,SAAiB,CAAC;IAEtB,IAAI,SAAS,GAAG,OAAO,EAAE,CAAC;QACxB,kEAAkE;QAClE,SAAS,GAAG,OAAO,CAAC;QACpB,SAAS,GAAG,OAAO,GAAG,CAAC,CAAC;IAC1B,CAAC;SAAM,CAAC;QACN,gEAAgE;QAChE,SAAS,GAAG,OAAO,GAAG,CAAC,CAAC;QACxB,SAAS,GAAG,OAAO,CAAC;IACtB,CAAC;IAED,MAAM,SAAS,GAAG,KAAK,CAAC,SAAS,CAAC,CAAC,KAAK,CAAC;IACzC,MAAM,SAAS,GAAG,KAAK,CAAC,SAAS,CAAC,CAAC,KAAK,CAAC;IAEzC,MAAM,QAAQ,GAAG,CAAC,SAAS,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC;IAE7C;;;;;OAKG;IACH,IAAI,QAAQ,KAAK,SAAS,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;QACrD,OAAO,SAAS,GAAG,MAAM,CAAC,OAAO,GAAG,GAAG,CAAC;IAC1C,CAAC;IAED,OAAO,QAAQ,CAAC;AAClB,CAAC"}