@talelk/newui-data 0.0.0-stage → 1.1.0

package/src/resource/local.test.ts

@@ -0,0 +1,111 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { createLocalStore } from './local'
+
+// jsdom provides a working `localStorage` (vitest sets an http origin), so the
+// default backend is exercised for real; the memory fallback is tested by
+// passing `storage: null` and by hiding the global.
+
+let prefix = 0
+function nextPrefix(): string {
+  prefix += 1
+  return `test-${prefix}:`
+}
+
+beforeEach(() => {
+  localStorage.clear()
+})
+
+afterEach(() => {
+  vi.unstubAllGlobals()
+  localStorage.clear()
+})
+
+describe('createLocalStore', () => {
+  it('round-trips JSON values through localStorage', () => {
+    const store = createLocalStore({ prefix: nextPrefix() })
+
+    store.set('doc', { name: 'T-1', tags: ['a', 'b'] })
+    store.set('count', 3)
+    store.set('flag', false)
+
+    expect(store.persistent).toBe(true)
+    expect(store.get('doc')).toEqual({ name: 'T-1', tags: ['a', 'b'] })
+    expect(store.get('count')).toBe(3)
+    expect(store.get('flag')).toBe(false)
+  })
+
+  it('returns null for a missing or unparseable entry', () => {
+    const store = createLocalStore<unknown>({ prefix: 'broken:' })
+    expect(store.get('nope')).toBe(null)
+
+    // A value written outside the JSON contract must not throw on read.
+    localStorage.setItem('broken:x', 'not json')
+    expect(store.get('x')).toBe(null)
+  })
+
+  it('scopes keys, delete, has, keys and clear to its prefix', () => {
+    const store = createLocalStore({ prefix: 'mine:' })
+    const other = createLocalStore({ prefix: 'other:' })
+
+    store.set('a', 1)
+    store.set('b', 2)
+    other.set('a', 9)
+
+    expect(store.has('a')).toBe(true)
+    expect(store.keys().sort()).toEqual(['a', 'b'])
+    expect(other.keys()).toEqual(['a'])
+
+    store.delete('a')
+    expect(store.has('a')).toBe(false)
+    expect(other.get('a')).toBe(9)
+
+    store.clear()
+    expect(store.keys()).toEqual([])
+    expect(other.get('a')).toBe(9)
+  })
+
+  it('persists across store instances that share a prefix', () => {
+    const first = createLocalStore<{ v: number }>({ prefix: 'shared:' })
+    first.set('k', { v: 1 })
+
+    const second = createLocalStore<{ v: number }>({ prefix: 'shared:' })
+    expect(second.get('k')).toEqual({ v: 1 })
+  })
+
+  it('falls back to memory when storage is explicitly null', () => {
+    const store = createLocalStore({ prefix: nextPrefix(), storage: null })
+
+    expect(store.persistent).toBe(false)
+    store.set('k', 'v')
+    expect(store.get('k')).toBe('v')
+    expect(store.has('k')).toBe(true)
+    expect(store.keys()).toEqual(['k'])
+    store.clear()
+    expect(store.keys()).toEqual([])
+  })
+
+  it('falls back to memory when localStorage is unavailable (SSR)', () => {
+    vi.stubGlobal('localStorage', undefined)
+    const store = createLocalStore({ prefix: nextPrefix() })
+
+    expect(store.persistent).toBe(false)
+    store.set('k', { v: 1 })
+    expect(store.get('k')).toEqual({ v: 1 })
+  })
+
+  it('drops writes when the backing storage throws', () => {
+    const throwing = {
+      length: 0,
+      key: () => null,
+      getItem: () => null,
+      setItem: () => {
+        throw new Error('QuotaExceededError')
+      },
+      removeItem: () => {},
+    } as unknown as Storage
+    const store = createLocalStore({ prefix: nextPrefix(), storage: throwing })
+
+    expect(() => store.set('k', 1)).not.toThrow()
+    expect(store.get('k')).toBe(null)
+  })
+})

package/src/resource/local.ts

@@ -0,0 +1,155 @@
+/**
+ * A `localStorage`-backed key/value store for caching resource data.
+ *
+ * The synchronous sibling of {@link createIdbStore}: values are JSON-encoded, so
+ * anything `JSON.parse(JSON.stringify(value))` round-trips is safe to cache.
+ * Every call is guarded for SSR — with no `localStorage` the store silently
+ * falls back to an in-memory `Map`, so importing and using it on the server
+ * never throws. It is a plain API (no Solid reactivity): a cache is not a view.
+ */
+
+/** The storage backend a {@link LocalStore} reads and writes. */
+type LocalStoreBackend = Storage | null
+
+/** A synchronous, JSON, key/value cache. */
+export interface LocalStore<T = unknown> {
+  /** The stored value, or `null` when the key is absent or not JSON. */
+  get(key: string): T | null
+  /** JSON-encode and persist a value. */
+  set(key: string, value: T): void
+  /** Remove a key. */
+  delete(key: string): void
+  /** Whether the key exists. */
+  has(key: string): boolean
+  /** Every key owned by this store, with the prefix stripped. */
+  keys(): string[]
+  /** Remove every key owned by this store. */
+  clear(): void
+  /** False when the store fell back to memory (SSR, or storage disabled). */
+  readonly persistent: boolean
+}
+
+/** Options for {@link createLocalStore}. */
+export interface LocalStoreOptions {
+  /** Key prefix, so several stores can share one `localStorage`. */
+  prefix?: string
+  /** Storage backend. Defaults to the global `localStorage`. */
+  storage?: LocalStoreBackend
+}
+
+function defaultStorage(): LocalStoreBackend {
+  try {
+    return typeof localStorage === 'undefined' ? null : localStorage
+  } catch {
+    // A sandboxed or disabled `localStorage` throws on access, not on use.
+    return null
+  }
+}
+
+/**
+ * Create a synchronous cache over `localStorage`.
+ *
+ * Keys are namespaced by `prefix` (default `newui:`), so a store owns only the
+ * entries it wrote: `keys()` and `clear()` never touch another store's data.
+ * A storage that throws (quota exceeded, disabled) degrades to a no-op write
+ * rather than failing the caller.
+ */
+export function createLocalStore<T = unknown>(
+  options: LocalStoreOptions = {},
+): LocalStore<T> {
+  const prefix = options.prefix ?? 'newui:'
+  const storage =
+    options.storage === undefined ? defaultStorage() : options.storage
+  const memory = new Map<string, string>()
+
+  const scoped = (key: string): string => `${prefix}${key}`
+
+  function get(key: string): T | null {
+    let raw: string | null
+    if (storage) {
+      try {
+        raw = storage.getItem(scoped(key))
+      } catch {
+        raw = null
+      }
+    } else {
+      raw = memory.get(key) ?? null
+    }
+    if (raw === null) return null
+    try {
+      return JSON.parse(raw) as T
+    } catch {
+      return null
+    }
+  }
+
+  function set(key: string, value: T): void {
+    const raw = JSON.stringify(value)
+    if (storage) {
+      try {
+        storage.setItem(scoped(key), raw)
+      } catch {
+        // Quota or disabled storage: the write is dropped, not fatal.
+      }
+    } else {
+      memory.set(key, raw)
+    }
+  }
+
+  function remove(key: string): void {
+    if (storage) {
+      try {
+        storage.removeItem(scoped(key))
+      } catch {
+        // Nothing to do — the entry is already unreachable.
+      }
+    } else {
+      memory.delete(key)
+    }
+  }
+
+  function has(key: string): boolean {
+    if (storage) {
+      try {
+        return storage.getItem(scoped(key)) !== null
+      } catch {
+        return false
+      }
+    }
+    return memory.has(key)
+  }
+
+  function keys(): string[] {
+    if (!storage) return [...memory.keys()]
+    const owned: string[] = []
+    try {
+      for (let index = 0; index < storage.length; index++) {
+        const key = storage.key(index)
+        if (key?.startsWith(prefix)) {
+          owned.push(key.slice(prefix.length))
+        }
+      }
+    } catch {
+      return []
+    }
+    return owned
+  }
+
+  function clear(): void {
+    if (!storage) {
+      memory.clear()
+      return
+    }
+    for (const key of keys()) remove(key)
+  }
+
+  return {
+    get,
+    set,
+    delete: remove,
+    has,
+    keys,
+    clear,
+    persistent: storage !== null,
+  }
+}

package/src/resource/realtime.test.ts

@@ -0,0 +1,331 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import {
+  createRealtime,
+  type RealtimeListener,
+  type RealtimeSocket,
+  type RealtimeSocketFactory,
+} from './realtime'
+
+/** A minimal socket: records listeners, exposes a manual `fire`. */
+function makeSocket() {
+  const handlers = new Map<string, Set<RealtimeListener>>()
+  const sent: unknown[] = []
+  let closed = false
+
+  const socket: RealtimeSocket = {
+    on(event, listener) {
+      const set = handlers.get(event) ?? new Set<RealtimeListener>()
+      set.add(listener)
+      handlers.set(event, set)
+    },
+    off(event, listener) {
+      handlers.get(event)?.delete(listener)
+    },
+    close() {
+      closed = true
+    },
+    send(data) {
+      sent.push(data)
+    },
+  }
+
+  return {
+    socket,
+    fire(event: string, ...args: unknown[]) {
+      for (const listener of handlers.get(event) ?? []) listener(...args)
+    },
+    count(event: string) {
+      return handlers.get(event)?.size ?? 0
+    },
+    sent,
+    get closed() {
+      return closed
+    },
+  }
+}
+
+type Fake = ReturnType<typeof makeSocket>
+
+function makeHarness() {
+  const sockets: Fake[] = []
+  const factory: RealtimeSocketFactory = () => {
+    const next = makeSocket()
+    sockets.push(next)
+    return next.socket
+  }
+  return { sockets, factory }
+}
+
+function socketAt(sockets: Fake[], index = 0): Fake {
+  const socket = sockets[index]
+  if (!socket) throw new Error(`No socket at index ${index}`)
+  return socket
+}
+
+afterEach(() => {
+  vi.useRealTimers()
+  vi.unstubAllGlobals()
+})
+
+describe('createRealtime', () => {
+  it('connects on creation and tracks the connected signal', () => {
+    const { sockets, factory } = makeHarness()
+    const realtime = createRealtime({
+      url: 'ws://x',
+      factory,
+      reconnect: false,
+    })
+
+    expect(sockets).toHaveLength(1)
+    expect(realtime.connected()).toBe(false)
+
+    socketAt(sockets).fire('open')
+    expect(realtime.connected()).toBe(true)
+
+    socketAt(sockets).fire('close')
+    expect(realtime.connected()).toBe(false)
+  })
+
+  it('accepts socket.io connect/disconnect lifecycle events', () => {
+    const { sockets, factory } = makeHarness()
+    const realtime = createRealtime({
+      url: 'ws://x',
+      factory,
+      reconnect: false,
+    })
+
+    socketAt(sockets).fire('connect')
+    expect(realtime.connected()).toBe(true)
+
+    socketAt(sockets).fire('disconnect', 'io server disconnect')
+    expect(realtime.connected()).toBe(false)
+  })
+
+  it('reflects a socket that is already connected', () => {
+    const socket: RealtimeSocket = {
+      connected: true,
+      on() {},
+      off() {},
+      close() {},
+      send() {},
+    }
+    const realtime = createRealtime({
+      url: 'ws://x',
+      factory: () => socket,
+      reconnect: false,
+    })
+
+    expect(realtime.connected()).toBe(true)
+  })
+
+  it('delivers named events and unsubscribes', () => {
+    const { sockets, factory } = makeHarness()
+    const realtime = createRealtime<{ list_update: { name: string } }>({
+      url: 'ws://x',
+      factory,
+      reconnect: false,
+    })
+    const received: string[] = []
+    const unsubscribe = realtime.on('list_update', (data) =>
+      received.push(data.name),
+    )
+
+    socketAt(sockets).fire('list_update', { name: 'T-1' })
+    expect(received).toEqual(['T-1'])
+    expect(socketAt(sockets).count('list_update')).toBe(1)
+
+    unsubscribe()
+    expect(socketAt(sockets).count('list_update')).toBe(0)
+    socketAt(sockets).fire('list_update', { name: 'T-2' })
+    expect(received).toEqual(['T-1'])
+  })
+
+  it('off() removes a listener registered with on()', () => {
+    const { sockets, factory } = makeHarness()
+    const realtime = createRealtime({
+      url: 'ws://x',
+      factory,
+      reconnect: false,
+    })
+    const listener = vi.fn()
+
+    realtime.on('evt', listener)
+    realtime.off('evt', listener)
+    socketAt(sockets).fire('evt', 1)
+
+    expect(listener).not.toHaveBeenCalled()
+    expect(socketAt(sockets).count('evt')).toBe(0)
+  })
+
+  it('replays subscriptions registered before connecting', () => {
+    const { sockets, factory } = makeHarness()
+    const realtime = createRealtime({
+      url: 'ws://x',
+      factory,
+      auto: false,
+      reconnect: false,
+    })
+    const listener = vi.fn()
+    realtime.on('evt', listener)
+
+    expect(sockets).toHaveLength(0)
+    realtime.connect()
+    expect(sockets).toHaveLength(1)
+    expect(socketAt(sockets).count('evt')).toBe(1)
+
+    socketAt(sockets).fire('evt', 42)
+    expect(listener).toHaveBeenCalledWith(42)
+  })
+
+  it('forwards send to the socket', () => {
+    const { sockets, factory } = makeHarness()
+    const realtime = createRealtime({
+      url: 'ws://x',
+      factory,
+      reconnect: false,
+    })
+
+    realtime.send({ ping: 1 })
+    expect(socketAt(sockets).sent).toEqual([{ ping: 1 }])
+  })
+
+  it('reports lifecycle callbacks', () => {
+    const { sockets, factory } = makeHarness()
+    const onOpen = vi.fn()
+    const onClose = vi.fn()
+    const onError = vi.fn()
+    createRealtime({
+      url: 'ws://x',
+      factory,
+      reconnect: false,
+      onOpen,
+      onClose,
+      onError,
+    })
+
+    socketAt(sockets).fire('open')
+    socketAt(sockets).fire('error', 'boom')
+    socketAt(sockets).fire('close', 'bye')
+
+    expect(onOpen).toHaveBeenCalledOnce()
+    expect(onError).toHaveBeenCalledWith('boom')
+    expect(onClose).toHaveBeenCalledWith('bye')
+  })
+
+  it('reconnects after an unexpected close, with backoff', () => {
+    vi.useFakeTimers()
+    const { sockets, factory } = makeHarness()
+    const realtime = createRealtime({
+      url: 'ws://x',
+      factory,
+      reconnectDelay: 100,
+      maxReconnectDelay: 100,
+    })
+
+    expect(sockets).toHaveLength(1)
+    socketAt(sockets).fire('open')
+    socketAt(sockets).fire('close')
+    expect(realtime.connected()).toBe(false)
+
+    vi.advanceTimersByTime(99)
+    expect(sockets).toHaveLength(1)
+    vi.advanceTimersByTime(1)
+    expect(sockets).toHaveLength(2)
+
+    // A new connection is replayed the current subscriptions.
+    const listener = vi.fn()
+    realtime.on('evt', listener)
+    socketAt(sockets, 1).fire('evt', 'again')
+    expect(listener).toHaveBeenCalledWith('again')
+  })
+
+  it('close() stops reconnecting and closes the socket', () => {
+    vi.useFakeTimers()
+    const { sockets, factory } = makeHarness()
+    const realtime = createRealtime({
+      url: 'ws://x',
+      factory,
+      reconnectDelay: 100,
+    })
+
+    socketAt(sockets).fire('open')
+    realtime.close()
+    expect(socketAt(sockets).closed).toBe(true)
+    expect(realtime.connected()).toBe(false)
+
+    // A late close event must not reopen a socket the caller closed.
+    socketAt(sockets).fire('close')
+    vi.advanceTimersByTime(1000)
+    expect(sockets).toHaveLength(1)
+  })
+
+  it('is a no-op without a WebSocket or factory (SSR-safe)', () => {
+    vi.stubGlobal('WebSocket', undefined)
+    const realtime = createRealtime({ url: 'ws://x' })
+
+    expect(realtime.connected()).toBe(false)
+    expect(() => realtime.connect()).not.toThrow()
+    expect(() => realtime.send('x')).not.toThrow()
+  })
+
+  it('adapts the native WebSocket by default', () => {
+    class FakeWebSocket {
+      static OPEN = 1
+      static instances: FakeWebSocket[] = []
+      readyState = 0
+      listeners = new Map<string, Set<EventListener>>()
+      sent: unknown[] = []
+
+      constructor(
+        readonly url: string,
+        readonly protocols?: string | string[],
+      ) {
+        FakeWebSocket.instances.push(this)
+      }
+
+      addEventListener(type: string, listener: EventListener) {
+        const set = this.listeners.get(type) ?? new Set<EventListener>()
+        set.add(listener)
+        this.listeners.set(type, set)
+      }
+
+      removeEventListener(type: string, listener: EventListener) {
+        this.listeners.get(type)?.delete(listener)
+      }
+
+      close() {
+        this.readyState = 3
+      }
+
+      send(data: unknown) {
+        this.sent.push(data)
+      }
+
+      emit(type: string, event: unknown) {
+        for (const listener of this.listeners.get(type) ?? []) {
+          listener(event as Event)
+        }
+      }
+    }
+
+    vi.stubGlobal('WebSocket', FakeWebSocket)
+    const realtime = createRealtime({ url: 'ws://x', reconnect: false })
+    const ws = FakeWebSocket.instances[0]
+    if (!ws) throw new Error('WebSocket was not constructed')
+
+    expect(ws.url).toBe('ws://x')
+    ws.emit('open', new Event('open'))
+    expect(realtime.connected()).toBe(true)
+
+    realtime.send({ a: 1 })
+    expect(ws.sent).toEqual(['{"a":1}'])
+
+    const received: unknown[] = []
+    realtime.on('message', (data) => received.push(data))
+    ws.emit('message', { data: 'hello' } as MessageEvent)
+    expect(received).toEqual(['hello'])
+
+    realtime.close()
+    expect(ws.readyState).toBe(3)
+  })
+})