hanzio 1.0.0

package/src/promise/index.ts

@@ -0,0 +1,73 @@
+export type BackgroundPromiseOptions = {
+	onError?: (error: unknown) => void
+	onSuccess?: () => void
+	scheduler?: (callback: () => void) => void
+}
+
+export type Success<T> = {
+	data: T
+	error: null
+}
+
+export type Failure<E> = {
+	data: null
+	error: E
+}
+
+export type Result<T, E = Error> = Success<T> | Failure<E>
+
+export function isSuccess<T, E>(result: Result<T, E>): result is Success<T> {
+	return result.error === null
+}
+
+export function isFailure<T, E>(result: Result<T, E>): result is Failure<E> {
+	return result.error !== null
+}
+
+export function unwrapResult<T, E>(result: Result<T, E>): T {
+	if (isSuccess(result)) return result.data
+	throw result.error
+}
+
+export function backgroundPromise<T>(
+	promiseFactory: () => Promise<T>,
+	options: BackgroundPromiseOptions = {}
+): void {
+	const run = () => {
+		promiseFactory()
+			.then(() => options.onSuccess?.())
+			.catch((error: unknown) => options.onError?.(error))
+	}
+
+	if (options.scheduler) {
+		options.scheduler(run)
+		return
+	}
+
+	run()
+}
+
+export function backgroundPromiseSync<T>(
+	promiseFactory: () => Promise<T>,
+	options: BackgroundPromiseOptions = {}
+): void {
+	backgroundPromise(promiseFactory, {
+		...options,
+		scheduler: options.scheduler ?? queueMicrotask
+	})
+}
+
+export function promiseTimeout(ms: number): Promise<void> {
+	return new Promise((resolve) => setTimeout(resolve, ms))
+}
+
+export async function tryCatch<T, E = Error>(
+	promise: Promise<T>
+): Promise<Result<T, E>> {
+	try {
+		const data = await promise
+		return { data, error: null }
+	} catch (error) {
+		return { data: null, error: error as E }
+	}
+}

package/src/sitemap/index.ts

@@ -0,0 +1,195 @@
+import PQueue from '../p-queue'
+
+interface SitemapOptions {
+	filterIndexes?: string
+	concurrency?: number
+	maxDepth?: number
+	timeout?: number
+}
+
+interface ProcessedResult {
+	links: Set<string>
+	visited: Set<string>
+}
+
+/**
+ * Creates an AbortController with a timeout
+ */
+const createTimeoutController = (timeout: number): AbortController => {
+	const controller = new AbortController()
+	setTimeout(() => controller.abort(), timeout)
+	return controller
+}
+
+/**
+ * Discovers sitemap URL(s) from a domain by checking common locations and robots.txt
+ */
+const discoverSitemaps = async (domain: string): Promise<string[]> => {
+	const normalizedDomain = domain.replace(/\/$/, '')
+	const commonLocations = [
+		'/sitemap.xml',
+		'/sitemap_index.xml',
+		'/sitemap/',
+		'/sitemaps.xml',
+		'/sitemap/sitemap.xml'
+	]
+
+	const sitemaps: Set<string> = new Set()
+	const requestOptions: RequestInit = {
+		headers: {
+			'User-Agent': 'SitemapCrawler/1.0'
+		},
+		// biome-ignore lint/suspicious/noExplicitAny: AbortSignal types differ between Bun and React Native
+		signal: createTimeoutController(5000).signal as any
+	}
+
+	// Check robots.txt first
+	try {
+		const robotsTxt = await fetch(`${normalizedDomain}/robots.txt`, {
+			...requestOptions
+		})
+
+		if (robotsTxt.ok) {
+			const text = await robotsTxt.text()
+			const sitemapMatches = text.match(/Sitemap: (.*)/gi)
+			if (sitemapMatches) {
+				sitemapMatches.forEach((match: string) => {
+					const url = match.replace('Sitemap:', '').trim()
+					sitemaps.add(url)
+				})
+			}
+
+			// If we found sitemaps in robots.txt, return them immediately
+			if (sitemaps.size > 0) {
+				return [...sitemaps]
+			}
+		}
+	} catch (error) {
+		console.warn(
+			'Could not fetch robots.txt:',
+			error instanceof Error ? error.message : 'Unknown error'
+		)
+	}
+
+	// Check common locations one by one
+	for (const location of commonLocations) {
+		try {
+			const response = await fetch(`${normalizedDomain}${location}`, {
+				...requestOptions,
+				method: 'HEAD'
+			})
+
+			if (response.ok) {
+				return [`${normalizedDomain}${location}`]
+			}
+		} catch (_error) {
+			// Ignore 404s and other errors
+		}
+	}
+
+	return []
+}
+
+/**
+ * Gets all URLs from a domain by discovering and crawling its sitemaps
+ * @param domain - The root domain (e.g., 'https://example.com')
+ * @param options - Configuration options for the crawler
+ * @returns Promise<string[]> - Array of unique URLs found in the sitemap
+ */
+export const getDomainSitemap = async (
+	domain: string,
+	options: SitemapOptions = {}
+): Promise<string[]> => {
+	const {
+		filterIndexes,
+		concurrency = 10,
+		maxDepth = 5,
+		timeout = 10000
+	} = options
+
+	// Normalize domain
+	let normalizedDomain = domain.replace(/\/$/, '')
+	if (!normalizedDomain.startsWith('http')) {
+		normalizedDomain = `https://${normalizedDomain}`
+	}
+
+	// Discover sitemaps
+	const sitemapUrls = await discoverSitemaps(normalizedDomain)
+	if (sitemapUrls.length === 0) {
+		throw new Error('No sitemaps found for the domain')
+	}
+
+	const queue = new PQueue({ concurrency })
+	const result: ProcessedResult = {
+		links: new Set<string>(),
+		visited: new Set<string>()
+	}
+
+	const locRegex = /<loc>([^<]+)<\/loc>/g
+	const isXmlSitemap = (url: string) =>
+		url.endsWith('.xml') || url.toLowerCase().includes('sitemap')
+
+	/**
+	 * Process a single sitemap URL and extract all links
+	 */
+	const processSitemap = async (
+		sitemapUrl: string,
+		depth = 0
+	): Promise<void> => {
+		if (depth > maxDepth || result.visited.has(sitemapUrl)) {
+			return
+		}
+
+		// console.log('Processing sitemap:', sitemapUrl)
+
+		result.visited.add(sitemapUrl)
+
+		try {
+			const controller = createTimeoutController(timeout)
+			const response = await fetch(sitemapUrl, {
+				headers: {
+					'User-Agent': 'SitemapCrawler/1.0'
+				},
+				// biome-ignore lint/suspicious/noExplicitAny: AbortSignal types differ between Bun and React Native
+				signal: controller.signal as any
+			})
+
+			if (!response.ok)
+				throw new Error(`HTTP error! status: ${response.status}`)
+
+			const data = await response.text()
+			const matches = [...data.matchAll(locRegex)]
+				.map((match) => match[1]!.trim())
+				.filter((link) => {
+					if (filterIndexes && isXmlSitemap(link)) {
+						return link.includes(filterIndexes)
+					}
+					return true
+				})
+
+			for (const link of matches) {
+				if (isXmlSitemap(link)) {
+					// Queue nested sitemap for processing
+					queue.add(() => processSitemap(link, depth + 1))
+				} else {
+					result.links.add(link)
+				}
+			}
+		} catch (error) {
+			console.warn(
+				`Failed to process sitemap ${sitemapUrl}:`,
+				error instanceof Error ? error.message : 'Unknown error'
+			)
+		}
+	}
+
+	// Process all discovered sitemaps
+	await Promise.all(
+		sitemapUrls.map((sitemapUrl) => queue.add(() => processSitemap(sitemapUrl)))
+	)
+
+	// Wait for all queued tasks to complete
+	await queue.onIdle()
+
+	return [...result.links]
+}

package/src/state/index.ts

@@ -0,0 +1,331 @@
+/**
+ * Simple State Machine - A lightweight state machine implementation
+ *
+ * This provides a generic state machine abstraction that can be used
+ * for various workflows and business processes.
+ */
+
+/**
+ * Type for validation result
+ * - true: transition is valid
+ * - string: transition is invalid with reason
+ */
+export type ValidationResult = true | string
+
+/**
+ * Type for validation function
+ * @param context The context object containing data needed for validation
+ * @param fromState The state transitioning from
+ * @param toState The state transitioning to
+ * @param action When validating a specific action, the action key (for per-action rules)
+ */
+export type ValidatorFn<
+	TState extends string,
+	TContext,
+	TAction extends string = string
+> = (
+	context: TContext,
+	fromState: TState,
+	toState: TState,
+	action?: TAction
+) => Promise<ValidationResult> | ValidationResult
+
+/**
+ * Type for action handler function
+ * @param context The context object containing data needed for validation
+ * @param data Additional data passed to the action
+ * @returns Result of executing the action
+ */
+export type ActionHandlerFn<TContext, TData = unknown, TResult = unknown> = (
+	context: TContext,
+	data: TData
+) => Promise<TResult> | TResult
+
+export type ActionDataMap<TAction extends string> = Record<TAction, unknown>
+export type ActionResultMap<TAction extends string> = Record<TAction, unknown>
+export type StateKey<TContext, TState extends string> = {
+	[K in keyof TContext]: TContext[K] extends TState ? K : never
+}[keyof TContext]
+
+export type ActionExecutionResult<TState extends string, TResult = unknown> =
+	| {
+			success: true
+			newState: TState
+			result?: TResult
+	  }
+	| {
+			success: false
+			error: string
+	  }
+
+/**
+ * Interface for state machine configuration
+ */
+export interface StateMachineConfig<
+	TState extends string,
+	TAction extends string,
+	TContext,
+	TActionDataMap extends ActionDataMap<TAction> = ActionDataMap<TAction>,
+	TActionResultMap extends ActionResultMap<TAction> = ActionResultMap<TAction>
+> {
+	// Maps states to possible actions and their target states
+	stateActionMap: Record<TState, Partial<Record<TAction, TState>>>
+
+	// Maps states to allowed direct transitions
+	stateTransitions: Record<TState, readonly TState[]>
+
+	// Validation functions for specific states
+	validators?: Partial<Record<TState, ValidatorFn<TState, TContext, TAction>>>
+
+	// Global validator that runs for all transitions
+	globalValidator?: ValidatorFn<TState, TContext, TAction>
+
+	// Action handlers for each action
+	actions?: {
+		[K in TAction]?: ActionHandlerFn<
+			TContext,
+			TActionDataMap[K],
+			TActionResultMap[K]
+		>
+	}
+}
+
+export type ValidateTransitionOptions<TAction extends string> = {
+	action?: TAction
+}
+
+/**
+ * Creates a simple state machine with validation capabilities
+ */
+export class SimpleStateMachine<
+	TState extends string,
+	TAction extends string,
+	TContext,
+	TActionDataMap extends ActionDataMap<TAction> = ActionDataMap<TAction>,
+	TActionResultMap extends ActionResultMap<TAction> = ActionResultMap<TAction>
+> {
+	private config: StateMachineConfig<
+		TState,
+		TAction,
+		TContext,
+		TActionDataMap,
+		TActionResultMap
+	>
+	private item: TContext
+	private stateKey: StateKey<TContext, TState>
+
+	constructor(
+		config: StateMachineConfig<
+			TState,
+			TAction,
+			TContext,
+			TActionDataMap,
+			TActionResultMap
+		>,
+		item: TContext,
+		stateKey: StateKey<TContext, TState>
+	) {
+		this.config = config
+		this.item = item
+		this.stateKey = stateKey
+	}
+
+	getCurrentStatus(): TState {
+		return this.item[this.stateKey] as TState
+	}
+
+	/**
+	 * Get available actions for the current state with validation results
+	 *
+	 * @returns Map of actions to validation results
+	 */
+	async getAvailableActions(): Promise<
+		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 }
+			)
+
+			result[action as TAction] = validationResult
+		}
+
+		return result
+	}
+
+	/**
+	 * Get all possible state transitions from the current state
+	 *
+	 * @returns Map of target states to validation results (true if any action to that state validates)
+	 */
+	async getPossibleTransitions(): Promise<
+		Partial<Record<TState, ValidationResult>>
+	> {
+		const possibleTransitions =
+			this.config.stateTransitions[this.getCurrentStatus()] || []
+		const actionsMap = this.config.stateActionMap[this.getCurrentStatus()] || {}
+		const result: Partial<Record<TState, ValidationResult>> = {}
+
+		for (const targetState of possibleTransitions) {
+			const actionsToTarget = (
+				Object.entries(actionsMap) as [TAction, TState | undefined][]
+			).filter(([, t]) => t === targetState)
+
+			if (actionsToTarget.length === 0) {
+				result[targetState] = await this.validateTransition(targetState)
+				continue
+			}
+
+			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
+		}
+
+		return result
+	}
+
+	/**
+	 * Executes an action with additional data
+	 *
+	 * @param action The action to execute
+	 * @param data The data for the action
+	 * @returns Promise with the execution result
+	 */
+	async executeAction<A extends TAction>(
+		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 targetState = actionsMap[action]
+		if (!targetState) {
+			return {
+				success: false,
+				error: `Action '${action}' not allowed in state '${this.getCurrentStatus()}'`
+			}
+		}
+
+		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)
+					}
+				}
+			}
+
+			// Default behavior if no action handler
+			return {
+				success: true,
+				newState: targetState
+			}
+		}
+
+		return {
+			success: false,
+			error: validationResult
+		}
+	}
+
+	/**
+	 * Validates a transition between states
+	 *
+	 * @param toState The state transitioning to
+	 * @param options When validating a specific action, pass `action` for per-action rules
+	 */
+	async validateTransition(
+		toState: TState,
+		options?: ValidateTransitionOptions<TAction>
+	): Promise<ValidationResult> {
+		const action = options?.action
+
+		// If states are the same, no transition is needed
+		if (this.getCurrentStatus() === toState) return true
+
+		// Check if transition is allowed in the state machine
+		const allowedTransitions =
+			this.config.stateTransitions[this.getCurrentStatus()] || []
+
+		if (!allowedTransitions.includes(toState)) {
+			return `Invalid transition from '${this.getCurrentStatus()}' to '${toState}'`
+		}
+
+		// Run global validator if provided
+		if (this.config.globalValidator) {
+			const globalResult = await this.config.globalValidator(
+				this.item,
+				this.getCurrentStatus(),
+				toState,
+				action
+			)
+			if (globalResult !== true) {
+				return globalResult
+			}
+		}
+
+		// Run state-specific validator if provided
+		const stateValidator = this.config.validators?.[toState]
+		if (stateValidator) {
+			return await stateValidator(
+				this.item,
+				this.getCurrentStatus(),
+				toState,
+				action
+			)
+		}
+
+		return true
+	}
+
+	/**
+	 * Get all states in the state machine
+	 */
+	getStates(): TState[] {
+		return Object.keys(this.config.stateTransitions) as TState[]
+	}
+
+	/**
+	 * Get initial state of the state machine
+	 * @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]
+	}
+}

package/src/string/index.ts

@@ -0,0 +1,86 @@
+export type JsonValue =
+	| string
+	| number
+	| boolean
+	| null
+	| JsonObject
+	| JsonArray
+export type JsonObject = { [key: string]: JsonValue | undefined }
+export type JsonArray = Array<JsonValue | undefined>
+
+export function extractNumber(
+	value: string | null | undefined
+): number | undefined {
+	if (!value?.trim()) return undefined
+
+	const cleanedValue = value.replace(/[^\d.,-]/g, '')
+	if (!cleanedValue) return undefined
+
+	const parsedNumber = Number.parseFloat(cleanedValue)
+	return Number.isNaN(parsedNumber) ? undefined : parsedNumber
+}
+
+export function generateId(input: JsonValue | undefined): string {
+	const data = normalizeIdInput(input)
+	let hash = 0
+
+	for (let index = 0; index < data.length; index++) {
+		const char = data.charCodeAt(index)
+		hash = (hash << 5) - hash + char
+		hash |= 0
+	}
+
+	return Math.abs(hash).toString(16).padStart(8, '0')
+}
+
+export function slugify(value: string): string {
+	const source =
+		'àáâäæãåāăąçćčđďèéêëēėęěğǵḧîïíīįìłḿñńǹňôöòóœøōõṕŕřßśšşșťțûüùúūǘůűųẃẍÿýžźż·/_,:;'
+	const replacement =
+		'aaaaaaaaaacccddeeeeeeeegghiiiiiilmnnnnooooooooprrsssssttuuuuuuuuuwxyyzzz------'
+	const specialCharacterPattern = new RegExp(source.split('').join('|'), 'g')
+
+	return value
+		.toString()
+		.toLowerCase()
+		.replace(/\s+/g, '-')
+		.replace(specialCharacterPattern, (character) =>
+			replacement.charAt(source.indexOf(character))
+		)
+		.replace(/&/g, '-and-')
+		.replace(/[^\w-]+/g, '')
+		.replace(/--+/g, '-')
+		.replace(/^-+/, '')
+		.replace(/-+$/, '')
+}
+
+function normalizeIdInput(input: JsonValue | undefined): string {
+	if (input === undefined) return 'undefined'
+	if (input === null) return 'null'
+	if (typeof input === 'string') {
+		return decodeURIComponent(input).split('&').sort().join('&')
+	}
+	if (typeof input === 'number' || typeof input === 'boolean') {
+		return input.toString()
+	}
+	return JSON.stringify(sortJsonValue(input))
+}
+
+function sortJsonValue(value: JsonValue | undefined): JsonValue | null {
+	if (value === undefined) return null
+
+	if (Array.isArray(value)) {
+		return value.map((item) => sortJsonValue(item))
+	}
+
+	if (typeof value === 'object' && value !== null) {
+		return Object.fromEntries(
+			Object.entries(value)
+				.filter(([, itemValue]) => itemValue !== undefined)
+				.sort(([leftKey], [rightKey]) => leftKey.localeCompare(rightKey))
+				.map(([key, itemValue]) => [key, sortJsonValue(itemValue)])
+		)
+	}
+
+	return value
+}