@mhmo91/schmancy 0.9.28 → 0.10.2

package/src/state/persist.ts

@@ -0,0 +1,208 @@
+// Storage adapters for the state() module. Lifted from the v1
+// store/storage-manager.ts and tightened — same four backends
+// (memory / local / session / indexeddb), same Map/Set JSON tunnel,
+// gives the state() factory a uniform async interface to load + save.
+//
+// The microtask write-debouncer lives in state.ts (the consumer of
+// this module) — adapters here are plain load/save/clear.
+
+export type StorageBackend = 'memory' | 'local' | 'session' | 'indexeddb'
+
+export interface StorageAdapter<T> {
+	load(): Promise<T | null>
+	save(value: T): Promise<void>
+	clear(): Promise<void>
+	close?(): Promise<void>
+}
+
+export class StateStorageError<T = unknown> extends Error {
+	readonly cause?: T
+	readonly context?: Record<string, unknown>
+	readonly timestamp: Date
+	constructor(message: string, cause?: T, context?: Record<string, unknown>) {
+		super(message)
+		this.name = 'StateStorageError'
+		this.cause = cause
+		this.context = context
+		this.timestamp = new Date()
+	}
+}
+
+// ---------------------------------------------------------------------------
+// JSON tunnel for Map/Set values stored in string-backed storage.
+// IDB stores native objects so doesn't need this — only used by local/session.
+
+const MAP_TAG = '__schmancy_state_Map'
+const SET_TAG = '__schmancy_state_Set'
+
+interface TaggedMap {
+	$kind: typeof MAP_TAG
+	entries: Array<[unknown, unknown]>
+}
+interface TaggedSet {
+	$kind: typeof SET_TAG
+	values: unknown[]
+}
+
+function replacer(_key: string, value: unknown): unknown {
+	if (value instanceof Map) {
+		return { $kind: MAP_TAG, entries: Array.from(value.entries()) } satisfies TaggedMap
+	}
+	if (value instanceof Set) {
+		return { $kind: SET_TAG, values: Array.from(value.values()) } satisfies TaggedSet
+	}
+	return value
+}
+
+function reviver(_key: string, value: unknown): unknown {
+	if (value && typeof value === 'object' && '$kind' in value) {
+		const tagged = value as { $kind: unknown; entries?: unknown; values?: unknown }
+		const kind = tagged.$kind
+		if (kind === MAP_TAG) {
+			if (!Array.isArray(tagged.entries)) return value
+			const ok = tagged.entries.every(e => Array.isArray(e) && e.length === 2)
+			if (!ok) return value
+			return new Map(tagged.entries as Iterable<readonly [unknown, unknown]>)
+		}
+		if (kind === SET_TAG) {
+			if (!Array.isArray(tagged.values)) return value
+			return new Set(tagged.values)
+		}
+	}
+	return value
+}
+
+// ---------------------------------------------------------------------------
+
+class MemoryAdapter<T> implements StorageAdapter<T> {
+	#data: T | null = null
+	async load(): Promise<T | null> {
+		return this.#data
+	}
+	async save(value: T): Promise<void> {
+		this.#data = value
+	}
+	async clear(): Promise<void> {
+		this.#data = null
+	}
+}
+
+class WebStorageAdapter<T> implements StorageAdapter<T> {
+	constructor(
+		private readonly storage: Storage,
+		private readonly key: string,
+		private readonly label: string,
+	) {}
+	async load(): Promise<T | null> {
+		try {
+			const raw = this.storage.getItem(this.key)
+			return raw ? (JSON.parse(raw, reviver) as T) : null
+		} catch (err) {
+			console.error(`[state] ${this.label} load failed (${this.key}):`, err)
+			return null
+		}
+	}
+	async save(value: T): Promise<void> {
+		try {
+			this.storage.setItem(this.key, JSON.stringify(value, replacer))
+		} catch (err) {
+			throw new StateStorageError(
+				`[state] ${this.label} save failed (${this.key})`,
+				err,
+			)
+		}
+	}
+	async clear(): Promise<void> {
+		this.storage.removeItem(this.key)
+	}
+}
+
+class IndexedDBAdapter<T> implements StorageAdapter<T> {
+	private static readonly DB_NAME = 'SchmancyState'
+	private static readonly STORE_NAME = 'states'
+	private static readonly DB_VERSION = 1
+
+	#db: IDBDatabase | null = null
+	#opening: Promise<IDBDatabase> | null = null
+
+	constructor(private readonly key: string) {}
+
+	private openDB(): Promise<IDBDatabase> {
+		if (this.#db) return Promise.resolve(this.#db)
+		if (this.#opening) return this.#opening
+		this.#opening = new Promise<IDBDatabase>((resolve, reject) => {
+			const req = indexedDB.open(IndexedDBAdapter.DB_NAME, IndexedDBAdapter.DB_VERSION)
+			req.onupgradeneeded = () => {
+				const db = req.result
+				if (!db.objectStoreNames.contains(IndexedDBAdapter.STORE_NAME)) {
+					db.createObjectStore(IndexedDBAdapter.STORE_NAME)
+				}
+			}
+			req.addEventListener('success', () => {
+				this.#db = req.result
+				resolve(req.result)
+			}, { once: true })
+			req.addEventListener('error', () => reject(req.error), { once: true })
+		})
+		return this.#opening
+	}
+
+	async load(): Promise<T | null> {
+		try {
+			const db = await this.openDB()
+			return await new Promise<T | null>((resolve, reject) => {
+				const tx = db.transaction(IndexedDBAdapter.STORE_NAME, 'readonly')
+				const req = tx.objectStore(IndexedDBAdapter.STORE_NAME).get(this.key)
+				req.addEventListener('success', () => resolve((req.result ?? null) as T | null), { once: true })
+				req.addEventListener('error', () => reject(req.error), { once: true })
+			})
+		} catch (err) {
+			console.error(`[state] IDB load failed (${this.key}):`, err)
+			return null
+		}
+	}
+
+	async save(value: T): Promise<void> {
+		const db = await this.openDB()
+		return new Promise<void>((resolve, reject) => {
+			const tx = db.transaction(IndexedDBAdapter.STORE_NAME, 'readwrite')
+			const req = tx.objectStore(IndexedDBAdapter.STORE_NAME).put(value, this.key)
+			req.addEventListener('success', () => resolve(), { once: true })
+			req.addEventListener('error', () => reject(
+				new StateStorageError(`[state] IDB save failed (${this.key})`, req.error),
+			), { once: true })
+		})
+	}
+
+	async clear(): Promise<void> {
+		const db = await this.openDB()
+		return new Promise<void>((resolve, reject) => {
+			const tx = db.transaction(IndexedDBAdapter.STORE_NAME, 'readwrite')
+			const req = tx.objectStore(IndexedDBAdapter.STORE_NAME).delete(this.key)
+			req.addEventListener('success', () => resolve(), { once: true })
+			req.addEventListener('error', () => reject(req.error), { once: true })
+		})
+	}
+
+	async close(): Promise<void> {
+		if (this.#db) {
+			this.#db.close()
+			this.#db = null
+		}
+		this.#opening = null
+	}
+}
+
+export function createAdapter<T>(backend: StorageBackend, key: string): StorageAdapter<T> {
+	switch (backend) {
+		case 'local':
+			return new WebStorageAdapter<T>(localStorage, key, 'localStorage')
+		case 'session':
+			return new WebStorageAdapter<T>(sessionStorage, key, 'sessionStorage')
+		case 'indexeddb':
+			return new IndexedDBAdapter<T>(key)
+		case 'memory':
+		default:
+			return new MemoryAdapter<T>()
+	}
+}

package/src/state/schmancy-context.ts

@@ -0,0 +1,130 @@
+// `<schmancy-context provides={[cart, …]}>` — declarative state isolation.
+//
+// Mounts one isolated copy of each provided state under the element. Reads
+// and writes from descendants resolve to the isolated copy via the
+// `@lit/context` request protocol; descendants outside any `<schmancy-context>`
+// continue to read/write the module-scoped global. The isolated copy is
+// initialised with a snapshot of `tmpl.value` at mount time so the subtree
+// starts from "current global state, then diverges."
+//
+// Lifetime: each isolated copy lives exactly as long as this element is
+// connected. `disconnectedCallback` destroys all isolated copies; their
+// pending writes flush, their adapters close.
+
+import { LitElement, html } from 'lit'
+import { property } from 'lit/decorators.js'
+import { ContextProvider, createContext, type Context } from '@lit/context'
+import { _publishEventHost, stateContextKey } from './active-host'
+
+// Curated set of DOM event types that descendants are likely to bind state-
+// mutating handlers to. The capture-phase listener publishes `this` as the
+// active event-host before the event reaches the target; descendants whose
+// inline handlers (or any code reached during the synchronous chain) call a
+// state mutator can resolve back to the isolated copy this context provides.
+const EVENT_TYPES = [
+	'click',
+	'dblclick',
+	'submit',
+	'change',
+	'input',
+	'keydown',
+	'keyup',
+	'keypress',
+	'pointerdown',
+	'pointerup',
+	'mousedown',
+	'mouseup',
+	'focus',
+	'blur',
+	'paste',
+	'drop',
+] as const
+
+/** Duck-typed view of what the `state()` factory hands out, restricted to the
+ *  bits `<schmancy-context>` needs. Kept internal — consumers see the full
+ *  `State<>` type and never refer to this. */
+export interface StateTemplate {
+	readonly namespace: string
+	readonly value: unknown
+	/** Internal hook the factory adds to every state instance. Builds a fresh
+	 *  per-context copy seeded with the current value, sharing nothing with the
+	 *  global instance. The returned object exposes `destroy()` so the context
+	 *  element can flush + close on disconnect. */
+	_isolatedInstance(): { destroy(): void } & Record<string | symbol, unknown>
+}
+
+export class SchmancyContext extends LitElement {
+	/** States to isolate under this subtree. Pass the same instances you import
+	 *  at module scope (e.g. `provides={[cart, menu]}`). Outside this element
+	 *  they continue to behave as module-scoped globals; descendants of this
+	 *  element see a per-element isolated copy. */
+	@property({ attribute: false }) provides: readonly StateTemplate[] = []
+
+	// Per-mount records. Keep both the provider (so we can release it on
+	// disconnect) and the isolated instance (so we can destroy it).
+	private _scoped: Array<{
+		isolated: { destroy(): void }
+		provider: ContextProvider<Context<unknown, unknown>>
+	}> = []
+
+	private _publishEventTargetAsHost = (e: Event): void => {
+		// Publish the deepest event target (across shadow boundaries) rather
+		// than `this`. The downstream `ContextRequestEvent` will be dispatched
+		// from this host and must bubble up through `<schmancy-context>` to
+		// reach our `ContextProvider`. `@lit/context` skips self-registration
+		// (`consumerHost === this.host` ⇒ no-op), so dispatching from
+		// schmancy-context itself would silently fall back to the global.
+		const path = e.composedPath()
+		for (const node of path) {
+			if (node instanceof HTMLElement) {
+				_publishEventHost(node)
+				return
+			}
+		}
+	}
+
+	override connectedCallback(): void {
+		super.connectedCallback()
+		for (const tmpl of this.provides) {
+			const isolated = tmpl._isolatedInstance()
+			const ctx = createContext<unknown>(stateContextKey(tmpl.namespace))
+			// ContextProvider auto-wires via the host's ReactiveControllerHost
+			// interface (LitElement satisfies it). It listens for
+			// `context-request` events and responds with `isolated` for any
+			// requester whose `event.context === ctx`.
+			const provider = new ContextProvider(this, { context: ctx, initialValue: isolated })
+			this._scoped.push({ isolated, provider })
+		}
+		for (const type of EVENT_TYPES) {
+			this.addEventListener(type, this._publishEventTargetAsHost, { capture: true })
+		}
+	}
+
+	override disconnectedCallback(): void {
+		for (const type of EVENT_TYPES) {
+			this.removeEventListener(type, this._publishEventTargetAsHost, { capture: true })
+		}
+		for (const entry of this._scoped) {
+			entry.isolated.destroy()
+		}
+		this._scoped = []
+		super.disconnectedCallback()
+	}
+
+	override render() {
+		return html`<slot></slot>`
+	}
+}
+
+// Imperative define so a second load (source + dist) is a no-op rather than
+// a throw — the registry is process-global; whichever class wins serves the
+// element identity for the page.
+if (!customElements.get('schmancy-context')) {
+	customElements.define('schmancy-context', SchmancyContext)
+}
+
+declare global {
+	interface HTMLElementTagNameMap {
+		'schmancy-context': SchmancyContext
+	}
+}

package/src/state/state.test-d.ts

@@ -0,0 +1,227 @@
+// Type-level tests for the public state() surface.
+//
+// All assertions are compile-time. Each call-site probe is wrapped in
+// a function that's never invoked at runtime — types are extracted via
+// `ReturnType`, so importing this file doesn't claim any namespace.
+//
+// Negative-case strategy: the schmancy pre-edit hook bans the TS
+// directive that asserts "this line should fail to typecheck"
+// (NO_TYPE_ESCAPES rule). Negative cases are expressed as pure
+// type-level predicates over the public surface — never as call
+// sites we expect to fail.
+//
+// Note: schmancy's main tsconfig has `strict: false`, which makes
+// the `Kind<T>` nullable check fragile at the type level (every
+// type is implicitly nullable). The runtime test suite covers the
+// nullable-union dispatch directly; this file focuses on assertions
+// that hold under both strict and non-strict tsconfigs.
+
+import type {
+	AssertNovel,
+	FeatureNamespace,
+	IsAsync,
+	Kind,
+	ObjectAPI,
+	State,
+} from './index'
+import { state } from './index'
+
+// --- Equality / assignability primitives ---------------------------------
+type Equal<X, Y> =
+	(<T>() => T extends X ? 1 : 2) extends <T>() => T extends Y ? 1 : 2 ? true : false
+type Expect<T extends true> = T
+type Assignable<A, B> = A extends B ? true : false
+
+// --- Sample shapes -------------------------------------------------------
+interface CartItem {
+	id: string
+	name: string
+	price: number
+	quantity: number
+}
+interface CartState {
+	items: CartItem[]
+	total: number
+}
+interface PamDoc {
+	id: string
+	amount: number
+}
+
+// =========================================================================
+// Probes — never called. Wrapped in functions so the state() factory
+// runs only at the type level (no namespace registration at import).
+// =========================================================================
+function form1Probe() {
+	const initial: CartState = { items: [], total: 0 }
+	return state('test-d/cart-form-1').session(initial)
+}
+function form2Probe() {
+	return state<CartState>('test-d/cart-form-2').session({ items: [], total: 0 })
+}
+function mapProbe() {
+	return state<Map<string, PamDoc>>('test-d/map-shape').idb(new Map())
+}
+function setProbe() {
+	return state<Set<string>>('test-d/set-shape').memory(new Set())
+}
+function arrayProbe() {
+	return state<number[]>('test-d/items').memory([])
+}
+function flagProbe() {
+	return state<boolean>('test-d/footer').memory(false)
+}
+
+type Form1 = ReturnType<typeof form1Probe>
+type Form2 = ReturnType<typeof form2Probe>
+type Docs = ReturnType<typeof mapProbe>
+type Sel = ReturnType<typeof setProbe>
+type Items = ReturnType<typeof arrayProbe>
+type Flag = ReturnType<typeof flagProbe>
+
+// =========================================================================
+// Kind<T> classifier — Map / Set / Array / primitive checks. (Nullable
+// classification is non-strict-tsconfig-fragile; covered by runtime tests.)
+// =========================================================================
+type _kObject = Expect<Equal<Kind<CartState>, 'object'>>
+type _kMap = Expect<Equal<Kind<Map<string, PamDoc>>, 'map'>>
+type _kSet = Expect<Equal<Kind<Set<string>>, 'set'>>
+type _kArrayReadonly = Expect<Equal<Kind<readonly string[]>, 'array'>>
+type _kArrayMutable = Expect<Equal<Kind<string[]>, 'array'>>
+type _kBoolean = Expect<Equal<Kind<boolean>, 'primitive'>>
+type _kNumber = Expect<Equal<Kind<number>, 'primitive'>>
+type _kString = Expect<Equal<Kind<string>, 'primitive'>>
+
+// IsAsync<S> drives the AsyncDisposable lifecycle for indexeddb only.
+type _idbAsync = Expect<Equal<IsAsync<'indexeddb'>, true>>
+type _memSync = Expect<Equal<IsAsync<'memory'>, false>>
+type _sesSync = Expect<Equal<IsAsync<'session'>, false>>
+type _locSync = Expect<Equal<IsAsync<'local'>, false>>
+
+// =========================================================================
+// Form (1) — typed-const inference (no type arg).
+// =========================================================================
+type _f1Value = Expect<Equal<Form1['value'], CartState>>
+type _f1SetArg0 = Expect<Equal<Parameters<Form1['set']>[0], Partial<CartState>>>
+type _f1SetArg1 = Expect<Equal<Parameters<Form1['set']>[1], boolean | undefined>>
+type _f1Replace = Expect<Equal<Parameters<Form1['replace']>, [CartState]>>
+
+// =========================================================================
+// Form (2) — explicit type arg.
+// =========================================================================
+type _f2SetArg0 = Expect<Equal<Parameters<Form2['set']>[0], Partial<CartState>>>
+type _f2SetArg1 = Expect<Equal<Parameters<Form2['set']>[1], boolean | undefined>>
+type _f2Replace = Expect<Equal<Parameters<Form2['replace']>, [CartState]>>
+type _f2DeleteKeys = Expect<Equal<Parameters<Form2['delete']>[0], keyof CartState>>
+type _f2HasUpdate = Expect<Assignable<Form2, { update: ObjectAPI<CartState>['update'] }>>
+type _f2Value = Expect<Equal<Form2['value'], CartState>>
+type _f2Sync = Expect<Assignable<Form2, Disposable>>
+
+// =========================================================================
+// Map<string, Doc> with idb backend → MapAPI + AsyncDisposable.
+// =========================================================================
+type _docsSetShape = Expect<Equal<Parameters<Docs['set']>, [string, PamDoc]>>
+type _docsDeleteShape = Expect<Equal<Parameters<Docs['delete']>, [string]>>
+type _docsHasClear = Expect<Equal<Parameters<Docs['clear']>, []>>
+type _docsValue = Expect<Equal<Docs['value'], Map<string, PamDoc>>>
+type _docsAsync = Expect<Assignable<Docs, AsyncDisposable>>
+type _docsSync = Expect<Assignable<Docs, Disposable>>
+
+// =========================================================================
+// Set<string> in memory → SetAPI.
+// =========================================================================
+type _selAdd = Expect<Equal<Parameters<Sel['add']>, [string]>>
+type _selToggle = Expect<Equal<Parameters<Sel['toggle']>, [string]>>
+type _selDelete = Expect<Equal<Parameters<Sel['delete']>, [string]>>
+type _selDeleteReturns = Expect<Equal<ReturnType<Sel['delete']>, boolean>>
+type _selValue = Expect<Equal<Sel['value'], Set<string>>>
+type _selSync = Expect<Assignable<Sel, Disposable>>
+
+// =========================================================================
+// Mutable arrays → ArrayAPI.
+// =========================================================================
+type _itemsPush = Expect<Equal<Parameters<Items['push']>, number[]>>
+type _itemsHasUpdate = Expect<Equal<'update' extends keyof Items ? true : false, true>>
+type _itemsHasClear = Expect<Equal<'clear' extends keyof Items ? true : false, true>>
+
+// =========================================================================
+// Primitive boolean → ScalarAPI (no update / no delete).
+// =========================================================================
+type _flagSet = Expect<Equal<Parameters<Flag['set']>, [boolean]>>
+type _flagNoUpdate = Expect<Equal<'update' extends keyof Flag ? true : false, false>>
+type _flagNoDelete = Expect<Equal<'delete' extends keyof Flag ? true : false, false>>
+
+// =========================================================================
+// FeatureNamespace pure type-level checks (no call sites).
+// =========================================================================
+type _slashlessRejected = Expect<Equal<'cart' extends FeatureNamespace ? true : false, false>>
+type _slashedAccepted = Expect<Equal<'a/b' extends FeatureNamespace ? true : false, true>>
+type _twoSlashesAccepted = Expect<Equal<'a/b/c' extends FeatureNamespace ? true : false, true>>
+
+// =========================================================================
+// AssertNovel returns 'fresh' for unregistered names.
+// =========================================================================
+type _assertNovelOnFresh = Expect<Equal<AssertNovel<'test-d/fresh'>, 'test-d/fresh'>>
+
+// =========================================================================
+// State<NS, T, S> alias smoke — verifies the conditional structure resolves.
+// =========================================================================
+type _syncMemoryState = Expect<
+	Assignable<State<'test-d/x', CartState, 'memory'>, { value: CartState }>
+>
+type _asyncIdbState = Expect<Assignable<State<'test-d/x', CartState, 'indexeddb'>, AsyncDisposable>>
+
+// =========================================================================
+// Collect every assertion into one exported tuple. TS still checks each
+// entry; the export consumes the unused locals so noUnusedLocals stops
+// flagging them.
+// =========================================================================
+export type _SchmancyStateTypeSpec = [
+	_kObject,
+	_kMap,
+	_kSet,
+	_kArrayReadonly,
+	_kArrayMutable,
+	_kBoolean,
+	_kNumber,
+	_kString,
+	_idbAsync,
+	_memSync,
+	_sesSync,
+	_locSync,
+	_f1Value,
+	_f1SetArg0,
+	_f1SetArg1,
+	_f1Replace,
+	_f2SetArg0,
+	_f2SetArg1,
+	_f2Replace,
+	_f2DeleteKeys,
+	_f2HasUpdate,
+	_f2Value,
+	_f2Sync,
+	_docsSetShape,
+	_docsDeleteShape,
+	_docsHasClear,
+	_docsValue,
+	_docsAsync,
+	_docsSync,
+	_selAdd,
+	_selToggle,
+	_selDelete,
+	_selDeleteReturns,
+	_selValue,
+	_selSync,
+	_itemsPush,
+	_itemsHasUpdate,
+	_itemsHasClear,
+	_flagSet,
+	_flagNoUpdate,
+	_flagNoDelete,
+	_slashlessRejected,
+	_slashedAccepted,
+	_twoSlashesAccepted,
+	_assertNovelOnFresh,
+	_syncMemoryState,
+	_asyncIdbState,
+]