hanzio 1.2.0 → 2.1.0

package/src/state/index.ts

@@ -80,6 +80,25 @@ export interface StateMachineConfig<
 	// Global validator that runs for all transitions
 	globalValidator?: ValidatorFn<TState, TContext, TAction>
 
+	// Validators for specific actions, run after the global and state validators
+	actionValidators?: Partial<
+		Record<TAction, ValidatorFn<TState, TContext, TAction>>
+	>
+
+	// State returned by getInitialState(). Defaults to the first key of stateTransitions
+	initialState?: TState
+
+	// Called after a successful action (after its handler). Throwing fails the action
+	onTransition?: (
+		context: TContext,
+		from: TState,
+		to: TState,
+		action: TAction
+	) => void | Promise<void>
+
+	// Write the new state into item[stateKey] after a successful action
+	applyTransition?: boolean
+
 	// Action handlers for each action
 	actions?: {
 		[K in TAction]?: ActionHandlerFn<
@@ -143,20 +162,18 @@ export class SimpleStateMachine<
 		Partial<Record<TAction, ValidationResult>>
 	> {
 		const actionsMap = this.config.stateActionMap[this.getCurrentStatus()] || {}
-		const result: Partial<Record<TAction, ValidationResult>> = {}
-
-		for (const [action, targetState] of Object.entries(actionsMap)) {
-			if (!targetState) continue
-
-			const validationResult = await this.validateTransition(
-				targetState as TState,
-				{ action: action as TAction }
+		const entries = (
+			Object.entries(actionsMap) as [TAction, TState | undefined][]
+		).filter((entry): entry is [TAction, TState] => !!entry[1])
+		const results = await Promise.all(
+			entries.map(([action, targetState]) =>
+				this.validateTransition(targetState, { action })
 			)
+		)
 
-			result[action as TAction] = validationResult
-		}
-
-		return result
+		return Object.fromEntries(
+			entries.map(([action], i) => [action, results[i]])
+		) as Partial<Record<TAction, ValidationResult>>
 	}
 
 	/**
@@ -170,34 +187,48 @@ export class SimpleStateMachine<
 		const possibleTransitions =
 			this.config.stateTransitions[this.getCurrentStatus()] || []
 		const actionsMap = this.config.stateActionMap[this.getCurrentStatus()] || {}
-		const result: Partial<Record<TState, ValidationResult>> = {}
+		const results = await Promise.all(
+			possibleTransitions.map(async (targetState) => {
+				const actionsToTarget = (
+					Object.entries(actionsMap) as [TAction, TState | undefined][]
+				).filter(([, t]) => t === targetState)
+
+				if (actionsToTarget.length === 0) {
+					return this.validateTransition(targetState)
+				}
 
-		for (const targetState of possibleTransitions) {
-			const actionsToTarget = (
-				Object.entries(actionsMap) as [TAction, TState | undefined][]
-			).filter(([, t]) => t === targetState)
+				const rs = await Promise.all(
+					actionsToTarget.map(([action]) =>
+						this.validateTransition(targetState, { action })
+					)
+				)
+				// true if any action validates, otherwise the last action's error
+				return rs.includes(true) ? true : (rs[rs.length - 1] as string)
+			})
+		)
+
+		return Object.fromEntries(
+			possibleTransitions.map((targetState, i) => [targetState, results[i]])
+		) as Partial<Record<TState, ValidationResult>>
+	}
 
-			if (actionsToTarget.length === 0) {
-				result[targetState] = await this.validateTransition(targetState)
-				continue
-			}
+	/**
+	 * Checks whether an action can be executed from the current state
+	 *
+	 * @returns true, or the reason the action is not allowed
+	 */
+	async canExecute(action: TAction): Promise<ValidationResult> {
+		const actionsMap = this.config.stateActionMap[this.getCurrentStatus()]
+		if (!actionsMap) {
+			return `No actions defined for state '${this.getCurrentStatus()}'`
+		}
 
-			let lastError: ValidationResult = true
-			let anyOk = false
-			for (const [actionKey] of actionsToTarget) {
-				const r = await this.validateTransition(targetState, {
-					action: actionKey
-				})
-				if (r === true) {
-					anyOk = true
-					break
-				}
-				lastError = r
-			}
-			result[targetState] = anyOk ? true : lastError
+		const targetState = actionsMap[action]
+		if (!targetState) {
+			return `Action '${action}' not allowed in state '${this.getCurrentStatus()}'`
 		}
 
-		return result
+		return this.validateTransition(targetState, { action })
 	}
 
 	/**
@@ -211,55 +242,35 @@ export class SimpleStateMachine<
 		action: A,
 		data: TActionDataMap[A]
 	): Promise<ActionExecutionResult<TState, TActionResultMap[A]>> {
-		const actionsMap = this.config.stateActionMap[this.getCurrentStatus()]
-		if (!actionsMap) {
-			return {
-				success: false,
-				error: `No actions defined for state '${this.getCurrentStatus()}'`
-			}
+		const fromState = this.getCurrentStatus()
+		const validationResult = await this.canExecute(action)
+		if (validationResult !== true) {
+			return { success: false, error: validationResult }
 		}
 
-		const targetState = actionsMap[action]
-		if (!targetState) {
-			return {
-				success: false,
-				error: `Action '${action}' not allowed in state '${this.getCurrentStatus()}'`
-			}
-		}
+		const targetState = this.config.stateActionMap[fromState][action] as TState
 
-		const validationResult = await this.validateTransition(targetState, {
-			action
-		})
-
-		if (validationResult === true) {
-			// If there's a custom action handler, call it with the provided data
-			if (this.config.actions?.[action]) {
-				try {
-					const result = await this.config.actions[action]!(this.item, data)
-					return {
-						success: true,
-						newState: targetState,
-						result
-					}
-				} catch (error) {
-					return {
-						success: false,
-						error: error instanceof Error ? error.message : String(error)
-					}
-				}
+		try {
+			const result = await this.config.actions?.[action]?.(this.item, data)
+			await this.config.onTransition?.(
+				this.item,
+				fromState,
+				targetState,
+				action
+			)
+			if (this.config.applyTransition) {
+				this.item[this.stateKey] = targetState as TContext[StateKey<
+					TContext,
+					TState
+				>]
 			}
-
-			// Default behavior if no action handler
+			return { success: true, newState: targetState, result }
+		} catch (error) {
 			return {
-				success: true,
-				newState: targetState
+				success: false,
+				error: error instanceof Error ? error.message : String(error)
 			}
 		}
-
-		return {
-			success: false,
-			error: validationResult
-		}
 	}
 
 	/**
@@ -301,7 +312,21 @@ export class SimpleStateMachine<
 		// Run state-specific validator if provided
 		const stateValidator = this.config.validators?.[toState]
 		if (stateValidator) {
-			return await stateValidator(
+			const stateResult = await stateValidator(
+				this.item,
+				this.getCurrentStatus(),
+				toState,
+				action
+			)
+			if (stateResult !== true) {
+				return stateResult
+			}
+		}
+
+		// Run action-specific validator if validating a specific action
+		const actionValidator = action && this.config.actionValidators?.[action]
+		if (actionValidator) {
+			return await actionValidator(
 				this.item,
 				this.getCurrentStatus(),
 				toState,
@@ -324,8 +349,35 @@ export class SimpleStateMachine<
 	 * @returns The initial state
 	 */
 	getInitialState(): TState | undefined {
-		// This implementation just returns the first state
-		// You might want to customize this based on your needs
-		return this.getStates()[0]
+		return this.config.initialState ?? this.getStates()[0]
+	}
+}
+
+/**
+ * Defines a state machine config once and binds it to items on demand
+ *
+ * @example
+ * const orderMachine = createStateMachine<Status, Action, Order>(config)
+ * const machine = orderMachine.for(order, 'status')
+ */
+export function createStateMachine<
+	TState extends string,
+	TAction extends string,
+	TContext,
+	TActionDataMap extends ActionDataMap<TAction> = ActionDataMap<TAction>,
+	TActionResultMap extends ActionResultMap<TAction> = ActionResultMap<TAction>
+>(
+	config: StateMachineConfig<
+		TState,
+		TAction,
+		TContext,
+		TActionDataMap,
+		TActionResultMap
+	>
+) {
+	return {
+		config,
+		for: (item: TContext, stateKey: StateKey<TContext, TState>) =>
+			new SimpleStateMachine(config, item, stateKey)
 	}
 }

package/src/storage/index.ts

@@ -0,0 +1,187 @@
+/** The part of the Web `Storage` API (`localStorage`, `sessionStorage`) used here. */
+export interface SyncStorageLike {
+	getItem(key: string): string | null
+	setItem(key: string, value: string): void
+	removeItem(key: string): void
+}
+
+/** An async key-value store such as React Native's `AsyncStorage`. */
+export interface AsyncStorageLike {
+	getItem(key: string): Promise<string | null>
+	setItem(key: string, value: string): Promise<void>
+	removeItem(key: string): Promise<void>
+}
+
+export interface StorageItemOptions<T> {
+	key: string
+	/** Returned when nothing is stored or the stored value can't be read. */
+	fallback: T
+	/** Validates the deserialized value, e.g. `schema.parse`. Throwing means `fallback`. */
+	parse?: (raw: unknown) => T
+	/** Defaults to `JSON.stringify`. */
+	serialize?: (value: T) => string
+	/** Defaults to `JSON.parse`. */
+	deserialize?: (raw: string) => unknown
+}
+
+export interface StorageItem<T> {
+	readonly key: string
+	get(): T
+	set(value: T): void
+	remove(): void
+	/**
+	 * Calls `listener` when another tab changes this key (the `storage` event).
+	 * A no-op outside browsers. Returns an unsubscribe function.
+	 */
+	subscribe(listener: (value: T) => void): () => void
+}
+
+export interface AsyncStorageItem<T> {
+	readonly key: string
+	get(): Promise<T>
+	set(value: T): Promise<void>
+	remove(): Promise<void>
+}
+
+/** A `Map`-backed `SyncStorageLike`, for tests, SSR, or as a stand-in. */
+export function createMemoryStorage(): SyncStorageLike {
+	const map = new Map<string, string>()
+	return {
+		getItem: (key) => map.get(key) ?? null,
+		setItem: (key, value) => {
+			map.set(key, String(value))
+		},
+		removeItem: (key) => {
+			map.delete(key)
+		}
+	}
+}
+
+type StorageEventLike = { key: string | null; storageArea: unknown }
+type EventTargetLike = Record<
+	'addEventListener' | 'removeEventListener',
+	(type: 'storage', listener: (event: StorageEventLike) => void) => void
+>
+
+let sharedMemoryStorage: SyncStorageLike | undefined
+
+// Reading `localStorage` itself throws in sandboxed iframes and some private modes.
+function defaultStorage(): SyncStorageLike {
+	try {
+		const storage = (globalThis as { localStorage?: SyncStorageLike })
+			.localStorage
+		if (storage) return storage
+	} catch {}
+	sharedMemoryStorage ??= createMemoryStorage()
+	return sharedMemoryStorage
+}
+
+function createCodec<T>(options: StorageItemOptions<T>) {
+	const {
+		fallback,
+		parse = (raw) => raw as T,
+		serialize = JSON.stringify,
+		deserialize = JSON.parse
+	} = options
+	return {
+		serialize,
+		decode(raw: string | null): T {
+			if (raw === null) return fallback
+			try {
+				return parse(deserialize(raw))
+			} catch {
+				return fallback
+			}
+		}
+	}
+}
+
+/**
+ * A typed value persisted in `localStorage` (or any `SyncStorageLike`). Never
+ * throws: missing, corrupt or invalid data reads as `fallback`, and when the
+ * storage throws (quota, Safari private mode, sandboxed iframes) the latest
+ * value is kept in memory for this item, so reads stay consistent this session.
+ */
+export function createStorageItem<T>(
+	options: StorageItemOptions<T> & { storage?: SyncStorageLike }
+): StorageItem<T> {
+	const { key, fallback, storage = defaultStorage() } = options
+	const { serialize, decode } = createCodec(options)
+	// Set when a write failed; wins over whatever the storage still holds.
+	let mirror: { value: T } | undefined
+
+	const write = (value: T, action: () => void) => {
+		try {
+			action()
+			mirror = undefined
+		} catch {
+			mirror = { value }
+		}
+	}
+
+	const get = () => {
+		if (mirror) return mirror.value
+		try {
+			return decode(storage.getItem(key))
+		} catch {
+			return fallback
+		}
+	}
+
+	return {
+		key,
+		get,
+		set: (value) => write(value, () => storage.setItem(key, serialize(value))),
+		remove: () => write(fallback, () => storage.removeItem(key)),
+		subscribe(listener) {
+			const target = globalThis as unknown as Partial<EventTargetLike>
+			if (!target.addEventListener || !target.removeEventListener) {
+				return () => {}
+			}
+			const onStorage = (event: StorageEventLike) => {
+				// `key` is null when the other tab called `storage.clear()`.
+				if (event.storageArea !== storage) return
+				if (event.key !== key && event.key !== null) return
+				mirror = undefined
+				listener(get())
+			}
+			target.addEventListener('storage', onStorage)
+			return () => target.removeEventListener?.('storage', onStorage)
+		}
+	}
+}
+
+/**
+ * `createStorageItem` for async stores such as React Native's `AsyncStorage`.
+ * Never rejects; same fallback and in-memory mirror behavior.
+ */
+export function createAsyncStorageItem<T>(
+	options: StorageItemOptions<T> & { storage: AsyncStorageLike }
+): AsyncStorageItem<T> {
+	const { key, fallback, storage } = options
+	const { serialize, decode } = createCodec(options)
+	let mirror: { value: T } | undefined
+
+	const write = async (value: T, action: () => Promise<void>) => {
+		try {
+			await action()
+			mirror = undefined
+		} catch {
+			mirror = { value }
+		}
+	}
+
+	return {
+		key,
+		async get() {
+			if (mirror) return mirror.value
+			try {
+				return decode(await storage.getItem(key))
+			} catch {
+				return fallback
+			}
+		},
+		set: (value) => write(value, () => storage.setItem(key, serialize(value))),
+		remove: () => write(fallback, () => storage.removeItem(key))
+	}
+}