@bendyline/squisq 0.1.1

package/src/spatial/Haversine.ts

@@ -0,0 +1,59 @@
+/**
+ * Haversine Distance Calculation
+ *
+ * Provides accurate distance calculation between two geographic coordinates
+ * using the Haversine formula, which accounts for Earth's curvature.
+ */
+
+import type { Coordinates } from '../schemas/Types.js';
+
+/**
+ * Calculate distance between two coordinates using Haversine formula.
+ *
+ * @param from Start coordinates
+ * @param to End coordinates
+ * @returns Distance in kilometers
+ */
+export function haversineDistance(from: Coordinates, to: Coordinates): number {
+  const R = 6371; // Earth's radius in kilometers
+
+  const dLat = toRadians(to.lat - from.lat);
+  const dLng = toRadians(to.lng - from.lng);
+
+  const a =
+    Math.sin(dLat / 2) * Math.sin(dLat / 2) +
+    Math.cos(toRadians(from.lat)) *
+      Math.cos(toRadians(to.lat)) *
+      Math.sin(dLng / 2) *
+      Math.sin(dLng / 2);
+
+  const c = 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1 - a));
+
+  return R * c;
+}
+
+/**
+ * Calculate bearing from one coordinate to another.
+ *
+ * @param from Start coordinates
+ * @param to End coordinates
+ * @returns Bearing in degrees (0-360, where 0 = north, 90 = east)
+ */
+export function calculateBearing(from: Coordinates, to: Coordinates): number {
+  const dLng = toRadians(to.lng - from.lng);
+  const lat1 = toRadians(from.lat);
+  const lat2 = toRadians(to.lat);
+
+  const x = Math.sin(dLng) * Math.cos(lat2);
+  const y = Math.cos(lat1) * Math.sin(lat2) - Math.sin(lat1) * Math.cos(lat2) * Math.cos(dLng);
+
+  const bearing = Math.atan2(x, y);
+  return ((bearing * 180) / Math.PI + 360) % 360;
+}
+
+/**
+ * Convert degrees to radians.
+ */
+function toRadians(degrees: number): number {
+  return (degrees * Math.PI) / 180;
+}

package/src/spatial/index.ts

@@ -0,0 +1,2 @@
+export * from './Haversine.js';
+export * from './Geohash.js';

package/src/storage/LocalForageAdapter.ts

@@ -0,0 +1,103 @@
+/**
+ * LocalForage adapter - IndexedDB storage with automatic fallbacks.
+ *
+ * Uses localforage which provides IndexedDB storage with automatic
+ * fallbacks to WebSQL and localStorage. This allows storing much more
+ * data than raw localStorage (which is limited to ~5MB).
+ *
+ * Unlike LocalStorageAdapter, this adapter can store binary data
+ * (ArrayBuffer, Blob, Uint8Array) natively without JSON serialization.
+ *
+ * Ported from qualla-internal/shared/services/StorageAdapters.ts with
+ * configurable store name and key prefix.
+ */
+
+import localforage from 'localforage';
+import type { StorageAdapter } from './Storage.js';
+
+export interface LocalForageAdapterOptions {
+  /** IndexedDB database name (default: 'squisq') */
+  name?: string;
+  /** IndexedDB object store name (default: 'data') */
+  storeName?: string;
+  /** Key prefix for namespacing (default: '') */
+  prefix?: string;
+  /** Human-readable description (default: 'Squisq storage') */
+  description?: string;
+}
+
+export class LocalForageAdapter implements StorageAdapter {
+  readonly supportsEnumeration = true;
+  private store: LocalForage;
+  private prefix: string;
+
+  constructor(options: LocalForageAdapterOptions = {}) {
+    const {
+      name = 'squisq',
+      storeName = 'data',
+      prefix = '',
+      description = 'Squisq storage',
+    } = options;
+
+    this.prefix = prefix;
+    this.store = localforage.createInstance({ name, storeName, description });
+  }
+
+  async get<T>(key: string): Promise<T | null> {
+    try {
+      const value = await this.store.getItem<T>(this.prefix + key);
+      return value;
+    } catch (e: unknown) {
+      console.warn('[Storage] get (IndexedDB) failed:', key, e);
+      return null;
+    }
+  }
+
+  async set<T>(key: string, value: T): Promise<void> {
+    try {
+      await this.store.setItem(this.prefix + key, value);
+    } catch (e: unknown) {
+      console.error('[Storage] set (IndexedDB) failed:', key, e);
+      throw e;
+    }
+  }
+
+  async remove(key: string): Promise<void> {
+    try {
+      await this.store.removeItem(this.prefix + key);
+    } catch (e: unknown) {
+      console.warn('[Storage] remove (IndexedDB) failed:', key, e);
+    }
+  }
+
+  async clear(): Promise<void> {
+    try {
+      if (this.prefix) {
+        // Only remove keys with our prefix
+        const keys = await this.store.keys();
+        const keysToRemove = keys.filter((k) => k.startsWith(this.prefix));
+        await Promise.all(keysToRemove.map((k) => this.store.removeItem(k)));
+      } else {
+        // No prefix — clear the entire store
+        await this.store.clear();
+      }
+    } catch (e: unknown) {
+      console.error('[Storage] clear (IndexedDB) failed:', e);
+    }
+  }
+
+  async keys(): Promise<string[]> {
+    try {
+      const allKeys = await this.store.keys();
+      if (this.prefix) {
+        return allKeys
+          .filter((k) => k.startsWith(this.prefix))
+          .map((k) => k.slice(this.prefix.length));
+      }
+      return allKeys;
+    } catch (e: unknown) {
+      console.warn('[Storage] keys (IndexedDB) failed:', e);
+      return [];
+    }
+  }
+}

package/src/storage/LocalStorageAdapter.ts

@@ -0,0 +1,57 @@
+/**
+ * localStorage adapter for web browsers.
+ * Supports a configurable key prefix to namespace stored data.
+ */
+
+import type { StorageAdapter } from './Storage.js';
+
+export class LocalStorageAdapter implements StorageAdapter {
+  readonly supportsEnumeration = true;
+  private prefix: string;
+
+  constructor(prefix = '') {
+    this.prefix = prefix;
+  }
+
+  async get<T>(key: string): Promise<T | null> {
+    try {
+      const raw = localStorage.getItem(this.prefix + key);
+      if (raw === null) return null;
+      return JSON.parse(raw) as T;
+    } catch {
+      return null;
+    }
+  }
+
+  async set<T>(key: string, value: T): Promise<void> {
+    localStorage.setItem(this.prefix + key, JSON.stringify(value));
+  }
+
+  async remove(key: string): Promise<void> {
+    localStorage.removeItem(this.prefix + key);
+  }
+
+  async clear(): Promise<void> {
+    const keysToRemove: string[] = [];
+    for (let i = 0; i < localStorage.length; i++) {
+      const k = localStorage.key(i);
+      if (k && k.startsWith(this.prefix)) {
+        keysToRemove.push(k);
+      }
+    }
+    for (const k of keysToRemove) {
+      localStorage.removeItem(k);
+    }
+  }
+
+  async keys(): Promise<string[]> {
+    const result: string[] = [];
+    for (let i = 0; i < localStorage.length; i++) {
+      const k = localStorage.key(i);
+      if (k && k.startsWith(this.prefix)) {
+        result.push(k.slice(this.prefix.length));
+      }
+    }
+    return result;
+  }
+}

package/src/storage/MemoryStorageAdapter.ts

@@ -0,0 +1,37 @@
+/**
+ * In-memory storage adapter for testing and SSR environments.
+ * Data does not persist across page reloads.
+ */
+
+import type { StorageAdapter } from './Storage.js';
+
+export class MemoryStorageAdapter implements StorageAdapter {
+  readonly supportsEnumeration = true;
+  private store = new Map<string, string>();
+
+  async get<T>(key: string): Promise<T | null> {
+    const val = this.store.get(key);
+    if (val === undefined) return null;
+    try {
+      return JSON.parse(val) as T;
+    } catch {
+      return null;
+    }
+  }
+
+  async set<T>(key: string, value: T): Promise<void> {
+    this.store.set(key, JSON.stringify(value));
+  }
+
+  async remove(key: string): Promise<void> {
+    this.store.delete(key);
+  }
+
+  async clear(): Promise<void> {
+    this.store.clear();
+  }
+
+  async keys(): Promise<string[]> {
+    return Array.from(this.store.keys());
+  }
+}

package/src/storage/Storage.ts

@@ -0,0 +1,28 @@
+/**
+ * Storage - Abstract persistence interface
+ *
+ * Defines the contract for persistent storage across different environments.
+ * All values are JSON-serialized, so any serializable value can be stored.
+ * Keys can be automatically namespaced with a configurable prefix.
+ */
+
+/** Storage adapter interface - implemented by environment-specific adapters */
+export interface StorageAdapter {
+  /** Get a value by key, returns null if not found */
+  get<T>(key: string): Promise<T | null>;
+
+  /** Set a value for a key */
+  set<T>(key: string, value: T): Promise<void>;
+
+  /** Remove a value by key */
+  remove(key: string): Promise<void>;
+
+  /** Clear all stored values (within our namespace) */
+  clear(): Promise<void>;
+
+  /** Get all keys (within our namespace) */
+  keys(): Promise<string[]>;
+
+  /** Check if this adapter supports enumeration */
+  readonly supportsEnumeration: boolean;
+}

package/src/storage/index.ts

@@ -0,0 +1,5 @@
+export type { StorageAdapter } from './Storage.js';
+export { MemoryStorageAdapter } from './MemoryStorageAdapter.js';
+export { LocalStorageAdapter } from './LocalStorageAdapter.js';
+export { LocalForageAdapter } from './LocalForageAdapter.js';
+export type { LocalForageAdapterOptions } from './LocalForageAdapter.js';