iconly 3.0.2 → 4.0.0

package/README.md

@@ -1,44 +1,36 @@
-<div align="center">
-<br>
+# iconly
 
-<h1>iconly</h1>
-
-<p><sup>A lightweight utility to load and cache SVG icons in the browser, using IndexedDB to store the data. It retrieves icons from a given SVG file, stores them in IndexedDB, and inserts them into the DOM for easy access and use.</sup></p>
+A lightweight utility to load and cache SVG icons in the browser, using IndexedDB to store the data.
 
 [![npm](https://img.shields.io/npm/v/iconly.svg?colorB=brightgreen)](https://www.npmjs.com/package/iconly)
-[![GitHub package version](https://img.shields.io/github/package-json/v/ux-ui-pro/iconly.svg)](https://github.com/ux-ui-pro/iconly)
-[![NPM Downloads](https://img.shields.io/npm/dm/iconly.svg?style=flat)](https://www.npmjs.org/package/iconly)
+[![NPM Downloads](https://img.shields.io/npm/dm/iconly.svg?style=flat)](https://www.npmjs.com/package/iconly)
 
-<sup>~2kB gzipped</sup>
+[Demo](https://codepen.io/ux-ui/pen/zYmyqWR)
 
-<a href="https://codepen.io/ux-ui/pen/zYmyqWR">Demo</a>
+---
 
-</div>
-<br>
+## Features
 
-# Install
-```console
-$ npm install iconly
-```
-<br>
+- Factory-based API with `createIconly()`.
+- IndexedDB, memory, or session storage strategies.
+- `init()` returns a `Result` and never throws.
+- ~2kB gzipped.
 
-# Import
-```javascript
-import { createIconly } from 'iconly';
+---
+
+## Installation
+
+```bash
+npm install iconly
 ```
-<br>
 
-# Upgrading to v3
-- The API is now factory-based: use `createIconly()` instead of `new Iconly()`.
-- `init()` returns a `Result<void>` and never throws.
-- The injected sprite wrapper is now `[data-iconly="iconset"]` inside `container` (instead of `#iconset`).
+---
 
-See `CHANGELOG.md` for details.
+## Quick Start
 
-<br>
+```ts
+import { createIconly } from 'iconly';
 
-# Usage
-```javascript
 const iconLoader = createIconly({
   file: './sprite.svg',
   version: '1.0',
@@ -55,44 +47,59 @@ if (!result.ok) {
 
 After `init()`, the SVG sprite is injected into the `container` inside `<div data-iconly="iconset" aria-hidden="true">...</div>`.
 
-```HTML
+```html
 <svg>
   <use href="#icon-name"></use>
 </svg>
 ```
-<sub>File with icons</sub>
-```HTML
+
+Sprite file format:
+
+```html
 <svg xmlns="http://www.w3.org/2000/svg" preserveAspectRatio="none" fill="none">
   <symbol id="icon-name" viewBox="0 0 300 300">
-    <path ... />
+    <path />
   </symbol>
-  ...
 </svg>
 ```
-<br>
-
-# Options
-|       Option       |                  Type                   |     Default     | Description                                                     |
-|:------------------:|:---------------------------------------:|:---------------:|:----------------------------------------------------------------|
-|       `file`       |                `string`                 | `'./icons.svg'` | The URL of the SVG file containing the icons.                   |
-|     `version`      |                `string`                 |     `'1.0'`     | The version of the icon set.                                    |
-|      `debug`       |                `boolean`                |     `false`     | If `true`, debug callbacks and logger debug output are enabled. |
-|    `container`     |         `string \| HTMLElement`         | `document.body` | The container element where the icons will be injected.         |
-|     `storage`      | `'indexeddb' \| 'memory' \| 'session'`  |  `'indexeddb'`  | Storage strategy used for caching icon data.                    |
-|      `dbName`      |                `string`                 |  `'iconlyDB'`   | IndexedDB database name (only for `indexeddb`).                 |
-|    `storeName`     |                `string`                 |    `'icons'`    | IndexedDB store name (only for `indexeddb`).                    |
-| `sessionKeyPrefix` |                `string`                 |   `'iconly'`    | Prefix for SessionStorage keys (only for `session`).            |
-|      `logger`      |          `{ debug?, error? }`           |   `undefined`   | Optional logger implementation for debug/error output.          |
-|     `onError`      |            `(error) => void`            |   `undefined`   | Optional callback invoked on errors.                            |
-|     `onDebug`      |           `(...args) => void`           |   `undefined`   | Optional callback invoked for debug messages.                   |
-<br>
-
-# Error handling
+
+---
+
+## API
+
+- `createIconly(config?)` — creates an icon loader instance.
+- `iconLoader.init()` — fetches (or loads from cache) the sprite and injects it into the DOM; returns `Result<void>`.
+- `iconLoader.abort()` — cancels an in-flight fetch.
+
+---
+
+## Options
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `file` | `string` | `'./icons.svg'` | URL of the SVG file containing the icons. |
+| `version` | `string` | `'1.0'` | Version of the icon set. |
+| `debug` | `boolean` | `false` | Enables debug callbacks and logger debug output. |
+| `container` | `string \| HTMLElement` | `document.body` | Container where icons are injected. |
+| `storage` | `'indexeddb' \| 'memory' \| 'session'` | `'indexeddb'` | Storage strategy for caching icon data. |
+| `dbName` | `string` | `'iconlyDB'` | IndexedDB database name (for `indexeddb`). |
+| `storeName` | `string` | `'icons'` | IndexedDB store name (for `indexeddb`). |
+| `sessionKeyPrefix` | `string` | `'iconly'` | SessionStorage key prefix (for `session`). |
+| `logger` | `{ debug?, error? }` | `undefined` | Optional logger for debug/error output. |
+| `onError` | `(error) => void` | `undefined` | Callback invoked on errors. |
+| `onDebug` | `(...args) => void` | `undefined` | Callback invoked for debug messages. |
+
+---
+
+## Error handling
+
 - `init()` never throws; it returns a `Result` with `ok: false` and `error` details.
-- When `debug` is `false`, debug messages are suppressed (no `onDebug` calls and no `logger.debug`).
+- When `debug` is `false`, debug messages are suppressed.
 - Errors still trigger `onError` and `logger.error` (if provided), even when `debug` is `false`.
-- You can cancel a fetch by calling `iconLoader.abort()`, which results in a `fetch_aborted` error code.
-<br>
+- Call `iconLoader.abort()` to cancel a fetch (`fetch_aborted` error code).
+
+---
+
+## License
 
-# License
 MIT

package/dist/index.cjs

@@ -0,0 +1,258 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+
+//#region src/errors.ts
+const createIconlyError = (code, message, cause) => ({
+	code,
+	message,
+	cause
+});
+
+//#endregion
+//#region src/result.ts
+const ok = (value) => ({
+	ok: true,
+	value
+});
+const err = (error) => ({
+	ok: false,
+	error
+});
+
+//#endregion
+//#region src/dom.ts
+const insertSvg = (container, data) => {
+	const found = container.querySelector("[data-iconly=\"iconset\"]");
+	let iconSetDiv = found instanceof HTMLElement ? found : null;
+	if (!iconSetDiv) {
+		iconSetDiv = document.createElement("div");
+		iconSetDiv.setAttribute("data-iconly", "iconset");
+		iconSetDiv.setAttribute("aria-hidden", "true");
+		iconSetDiv.style.cssText = "width: 0; height: 0; position: absolute; left: -9999px;";
+		container.appendChild(iconSetDiv);
+	}
+	const svgDoc = new DOMParser().parseFromString(data, "image/svg+xml");
+	const parserError = svgDoc.querySelector("parsererror");
+	if (parserError) return err(createIconlyError("parse_error", `SVG parsing error: ${parserError.textContent ?? "Unknown error"}`));
+	iconSetDiv.innerHTML = "";
+	const svgEl = svgDoc.documentElement;
+	if (!svgEl) return err(createIconlyError("parse_error", "No valid SVG content found."));
+	const imported = document.importNode(svgEl, true);
+	iconSetDiv.appendChild(imported);
+	return ok(void 0);
+};
+
+//#endregion
+//#region src/fetcher.ts
+const fetchSvg = async (file, signal) => {
+	try {
+		const response = await fetch(file, { signal });
+		if (!response.ok) return err(createIconlyError("fetch_failed", `Failed to fetch icons from "${file}".`));
+		return ok(await response.text());
+	} catch (error) {
+		if (error instanceof DOMException && error.name === "AbortError") return err(createIconlyError("fetch_aborted", "Fetch request was aborted.", error));
+		return err(createIconlyError("fetch_failed", "Failed to fetch icons.", error));
+	}
+};
+
+//#endregion
+//#region src/storage/indexeddb.ts
+const createIndexedDbStorage = (options = {}) => {
+	const dbName = options.dbName ?? "iconlyDB";
+	const storeName = options.storeName ?? "icons";
+	let dbPromise = null;
+	const openDb = async () => {
+		if (dbPromise) return dbPromise;
+		if (typeof indexedDB === "undefined") throw createIconlyError("indexeddb_not_supported", "IndexedDB is not supported.");
+		dbPromise = new Promise((resolve, reject) => {
+			const request = indexedDB.open(dbName, 1);
+			request.onerror = () => {
+				reject(createIconlyError("indexeddb_open_failed", "Failed to open IndexedDB connection.", request.error));
+			};
+			request.onupgradeneeded = (event) => {
+				const db = event.target.result;
+				if (!db.objectStoreNames.contains(storeName)) db.createObjectStore(storeName, { keyPath: "version" });
+			};
+			request.onsuccess = () => resolve(request.result);
+		});
+		return dbPromise;
+	};
+	const getStore = (db, mode) => db.transaction(storeName, mode).objectStore(storeName);
+	const toIconlyError = (error, fallbackCode, message) => {
+		if (error && typeof error === "object" && "code" in error && "message" in error) return error;
+		return createIconlyError(fallbackCode, message, error);
+	};
+	const get = async (version) => {
+		try {
+			const store = getStore(await openDb(), "readonly");
+			return await new Promise((resolve) => {
+				const request = store.get(version);
+				request.onsuccess = () => resolve(ok(request.result));
+				request.onerror = () => resolve(err(createIconlyError("indexeddb_request_failed", "Failed to read from IndexedDB.", request.error)));
+			});
+		} catch (error) {
+			return err(toIconlyError(error, "indexeddb_open_failed", "Failed to open IndexedDB."));
+		}
+	};
+	const set = async (record) => {
+		try {
+			const store = getStore(await openDb(), "readwrite");
+			return await new Promise((resolve) => {
+				const request = store.put(record);
+				request.onsuccess = () => resolve(ok(void 0));
+				request.onerror = () => resolve(err(createIconlyError("indexeddb_request_failed", "Failed to write to IndexedDB.", request.error)));
+			});
+		} catch (error) {
+			return err(createIconlyError("indexeddb_open_failed", "Failed to open IndexedDB.", error));
+		}
+	};
+	return {
+		get,
+		set
+	};
+};
+
+//#endregion
+//#region src/storage/memory.ts
+const createMemoryStorage = () => {
+	const store = /* @__PURE__ */ new Map();
+	const get = async (version) => {
+		if (!store.has(version)) return ok(void 0);
+		return ok({
+			version,
+			data: store.get(version) ?? ""
+		});
+	};
+	const set = async (record) => {
+		store.set(record.version, record.data);
+		return ok(void 0);
+	};
+	return {
+		get,
+		set
+	};
+};
+
+//#endregion
+//#region src/storage/session.ts
+const createSessionStorage = (options = {}) => {
+	const keyPrefix = options.keyPrefix ?? "iconly";
+	const resolveStorage = () => {
+		if (typeof window === "undefined" || !window.sessionStorage) return err(createIconlyError("storage_unavailable", "SessionStorage is not available."));
+		return ok(window.sessionStorage);
+	};
+	const get = async (version) => {
+		const storageResult = resolveStorage();
+		if (!storageResult.ok) return storageResult;
+		try {
+			const raw = storageResult.value.getItem(`${keyPrefix}:${version}`);
+			if (!raw) return ok(void 0);
+			return ok(JSON.parse(raw));
+		} catch (error) {
+			return err(createIconlyError("storage_read_failed", "Failed to read from SessionStorage.", error));
+		}
+	};
+	const set = async (record) => {
+		const storageResult = resolveStorage();
+		if (!storageResult.ok) return storageResult;
+		try {
+			storageResult.value.setItem(`${keyPrefix}:${record.version}`, JSON.stringify(record));
+			return ok(void 0);
+		} catch (error) {
+			return err(createIconlyError("storage_write_failed", "Failed to write to SessionStorage.", error));
+		}
+	};
+	return {
+		get,
+		set
+	};
+};
+
+//#endregion
+//#region src/storage/index.ts
+const resolveStorage = (strategy, options) => {
+	if (!strategy || strategy === "indexeddb") return createIndexedDbStorage({
+		dbName: options.dbName,
+		storeName: options.storeName
+	});
+	if (strategy === "memory") return createMemoryStorage();
+	if (strategy === "session") return createSessionStorage({ keyPrefix: options.sessionKeyPrefix });
+	return strategy;
+};
+
+//#endregion
+//#region src/core.ts
+const createIconly = (config = {}) => {
+	const resolved = {
+		file: config.file ?? "./icons.svg",
+		version: config.version ?? "1.0",
+		debug: config.debug ?? false,
+		container: config.container,
+		logger: config.logger,
+		onError: config.onError,
+		onDebug: config.onDebug
+	};
+	const storage = resolveStorage(config.storage, {
+		dbName: config.dbName,
+		storeName: config.storeName,
+		sessionKeyPrefix: config.sessionKeyPrefix
+	});
+	let controller = null;
+	const abort = () => {
+		controller?.abort();
+	};
+	const resolveContainer = () => {
+		if (typeof document === "undefined") return err(createIconlyError("container_invalid", "Document is not available in this environment."));
+		if (typeof resolved.container === "string") {
+			const found = document.querySelector(resolved.container);
+			if (!found || !(found instanceof HTMLElement)) return err(createIconlyError("container_invalid", `Invalid container selector: "${resolved.container}".`));
+			return ok(found);
+		}
+		if (resolved.container instanceof HTMLElement) return ok(resolved.container);
+		const fallback = document.body ?? document.documentElement;
+		if (!fallback) return err(createIconlyError("container_invalid", "No valid container element found."));
+		return ok(fallback);
+	};
+	const logDebug = (...messages) => {
+		if (!resolved.debug) return;
+		resolved.onDebug?.(...messages);
+		resolved.logger?.debug?.("[Iconly debug]", ...messages);
+	};
+	const logError = (error) => {
+		resolved.onError?.(error);
+		resolved.logger?.error?.("[Iconly error]", error);
+	};
+	const fail = (error) => {
+		logError(error);
+		return err(error);
+	};
+	const init = async () => {
+		const containerResult = resolveContainer();
+		if (!containerResult.ok) return fail(containerResult.error);
+		const cacheResult = await storage.get(resolved.version);
+		if (!cacheResult.ok) return fail(cacheResult.error);
+		let data = cacheResult.value?.data;
+		if (!data) {
+			controller = new AbortController();
+			const fetchResult = await fetchSvg(resolved.file, controller.signal);
+			if (!fetchResult.ok) return fail(fetchResult.error);
+			data = fetchResult.value;
+			const storeResult = await storage.set({
+				version: resolved.version,
+				data
+			});
+			if (!storeResult.ok) return fail(storeResult.error);
+		} else logDebug("Using cached icon set", resolved.version);
+		const insertResult = insertSvg(containerResult.value, data);
+		if (!insertResult.ok) return fail(insertResult.error);
+		logDebug("Iconly has successfully initialized.");
+		return ok(void 0);
+	};
+	return {
+		init,
+		abort
+	};
+};
+
+//#endregion
+exports.createIconly = createIconly;
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","names":[],"sources":["../src/errors.ts","../src/result.ts","../src/dom.ts","../src/fetcher.ts","../src/storage/indexeddb.ts","../src/storage/memory.ts","../src/storage/session.ts","../src/storage/index.ts","../src/core.ts"],"sourcesContent":["import type { IconlyError, IconlyErrorCode } from './types';\n\nexport const createIconlyError = (\n  code: IconlyErrorCode,\n  message: string,\n  cause?: unknown,\n): IconlyError => ({\n  code,\n  message,\n  cause,\n});\n","import type { IconlyError, Result } from './types';\n\nexport const ok = <T>(value: T): Result<T> => ({ ok: true, value });\n\nexport const err = <T = never>(error: IconlyError): Result<T> => ({ ok: false, error });\n","import { createIconlyError } from './errors';\nimport { err, ok } from './result';\nimport type { Result } from './types';\n\nexport const insertSvg = (container: HTMLElement, data: string): Result<void> => {\n  const found = container.querySelector('[data-iconly=\"iconset\"]');\n  let iconSetDiv: HTMLElement | null = found instanceof HTMLElement ? found : null;\n\n  if (!iconSetDiv) {\n    iconSetDiv = document.createElement('div');\n    iconSetDiv.setAttribute('data-iconly', 'iconset');\n    iconSetDiv.setAttribute('aria-hidden', 'true');\n    iconSetDiv.style.cssText = 'width: 0; height: 0; position: absolute; left: -9999px;';\n    container.appendChild(iconSetDiv);\n  }\n\n  const parser = new DOMParser();\n  const svgDoc = parser.parseFromString(data, 'image/svg+xml');\n  const parserError = svgDoc.querySelector('parsererror');\n\n  if (parserError) {\n    return err(\n      createIconlyError(\n        'parse_error',\n        `SVG parsing error: ${parserError.textContent ?? 'Unknown error'}`,\n      ),\n    );\n  }\n\n  iconSetDiv.innerHTML = '';\n\n  const svgEl = svgDoc.documentElement;\n\n  if (!svgEl) {\n    return err(createIconlyError('parse_error', 'No valid SVG content found.'));\n  }\n\n  const imported = document.importNode(svgEl, true);\n\n  iconSetDiv.appendChild(imported);\n\n  return ok(undefined);\n};\n","import { createIconlyError } from './errors';\nimport { err, ok } from './result';\nimport type { Result } from './types';\n\nexport const fetchSvg = async (file: string, signal?: AbortSignal): Promise<Result<string>> => {\n  try {\n    const response = await fetch(file, { signal });\n\n    if (!response.ok) {\n      return err(createIconlyError('fetch_failed', `Failed to fetch icons from \"${file}\".`));\n    }\n\n    const data = await response.text();\n\n    return ok(data);\n  } catch (error: unknown) {\n    if (error instanceof DOMException && error.name === 'AbortError') {\n      return err(createIconlyError('fetch_aborted', 'Fetch request was aborted.', error));\n    }\n\n    return err(createIconlyError('fetch_failed', 'Failed to fetch icons.', error));\n  }\n};\n","import { createIconlyError } from '../errors';\nimport { err, ok } from '../result';\nimport type { IconlyError, IconRecord, IconStorage, Result } from '../types';\n\ninterface IndexedDbOptions {\n  dbName?: string;\n  storeName?: string;\n}\n\nexport const createIndexedDbStorage = (options: IndexedDbOptions = {}): IconStorage => {\n  const dbName = options.dbName ?? 'iconlyDB';\n  const storeName = options.storeName ?? 'icons';\n\n  let dbPromise: Promise<IDBDatabase> | null = null;\n\n  const openDb = async (): Promise<IDBDatabase> => {\n    if (dbPromise) {\n      return dbPromise;\n    }\n\n    if (typeof indexedDB === 'undefined') {\n      throw createIconlyError('indexeddb_not_supported', 'IndexedDB is not supported.');\n    }\n\n    dbPromise = new Promise<IDBDatabase>((resolve, reject) => {\n      const request = indexedDB.open(dbName, 1);\n\n      request.onerror = (): void => {\n        reject(\n          createIconlyError(\n            'indexeddb_open_failed',\n            'Failed to open IndexedDB connection.',\n            request.error,\n          ),\n        );\n      };\n\n      request.onupgradeneeded = (event): void => {\n        const db = (event.target as IDBOpenDBRequest).result;\n\n        if (!db.objectStoreNames.contains(storeName)) {\n          db.createObjectStore(storeName, { keyPath: 'version' });\n        }\n      };\n\n      request.onsuccess = (): void => resolve(request.result);\n    });\n\n    return dbPromise;\n  };\n\n  const getStore = (db: IDBDatabase, mode: IDBTransactionMode): IDBObjectStore =>\n    db.transaction(storeName, mode).objectStore(storeName);\n\n  const toIconlyError = (\n    error: unknown,\n    fallbackCode: IconlyError['code'],\n    message: string,\n  ): IconlyError => {\n    if (error && typeof error === 'object' && 'code' in error && 'message' in error) {\n      return error as IconlyError;\n    }\n\n    return createIconlyError(fallbackCode, message, error);\n  };\n\n  const get = async (version: string): Promise<Result<IconRecord | undefined>> => {\n    try {\n      const db = await openDb();\n      const store = getStore(db, 'readonly');\n\n      return await new Promise<Result<IconRecord | undefined>>((resolve) => {\n        const request = store.get(version);\n\n        request.onsuccess = (): void => resolve(ok(request.result as IconRecord | undefined));\n        request.onerror = (): void =>\n          resolve(\n            err(\n              createIconlyError(\n                'indexeddb_request_failed',\n                'Failed to read from IndexedDB.',\n                request.error,\n              ),\n            ),\n          );\n      });\n    } catch (error: unknown) {\n      return err(toIconlyError(error, 'indexeddb_open_failed', 'Failed to open IndexedDB.'));\n    }\n  };\n\n  const set = async (record: IconRecord): Promise<Result<void>> => {\n    try {\n      const db = await openDb();\n      const store = getStore(db, 'readwrite');\n\n      return await new Promise<Result<void>>((resolve) => {\n        const request = store.put(record);\n\n        request.onsuccess = (): void => resolve(ok(undefined));\n        request.onerror = (): void =>\n          resolve(\n            err(\n              createIconlyError(\n                'indexeddb_request_failed',\n                'Failed to write to IndexedDB.',\n                request.error,\n              ),\n            ),\n          );\n      });\n    } catch (error: unknown) {\n      return err(createIconlyError('indexeddb_open_failed', 'Failed to open IndexedDB.', error));\n    }\n  };\n\n  return { get, set };\n};\n","import { ok } from '../result';\nimport type { IconRecord, IconStorage, Result } from '../types';\n\nexport const createMemoryStorage = (): IconStorage => {\n  const store = new Map<string, string>();\n\n  const get = async (version: string): Promise<Result<IconRecord | undefined>> => {\n    if (!store.has(version)) {\n      return ok(undefined);\n    }\n\n    return ok({ version, data: store.get(version) ?? '' });\n  };\n\n  const set = async (record: IconRecord): Promise<Result<void>> => {\n    store.set(record.version, record.data);\n\n    return ok(undefined);\n  };\n\n  return { get, set };\n};\n","import { createIconlyError } from '../errors';\nimport { err, ok } from '../result';\nimport type { IconRecord, IconStorage, Result } from '../types';\n\ninterface SessionStorageOptions {\n  keyPrefix?: string;\n}\n\nexport const createSessionStorage = (options: SessionStorageOptions = {}): IconStorage => {\n  const keyPrefix = options.keyPrefix ?? 'iconly';\n\n  const resolveStorage = (): Result<Storage> => {\n    if (typeof window === 'undefined' || !window.sessionStorage) {\n      return err(createIconlyError('storage_unavailable', 'SessionStorage is not available.'));\n    }\n\n    return ok(window.sessionStorage);\n  };\n\n  const get = async (version: string): Promise<Result<IconRecord | undefined>> => {\n    const storageResult = resolveStorage();\n\n    if (!storageResult.ok) {\n      return storageResult;\n    }\n\n    try {\n      const raw = storageResult.value.getItem(`${keyPrefix}:${version}`);\n\n      if (!raw) {\n        return ok(undefined);\n      }\n\n      const parsed = JSON.parse(raw) as IconRecord;\n\n      return ok(parsed);\n    } catch (error: unknown) {\n      return err(\n        createIconlyError('storage_read_failed', 'Failed to read from SessionStorage.', error),\n      );\n    }\n  };\n\n  const set = async (record: IconRecord): Promise<Result<void>> => {\n    const storageResult = resolveStorage();\n\n    if (!storageResult.ok) {\n      return storageResult;\n    }\n\n    try {\n      storageResult.value.setItem(`${keyPrefix}:${record.version}`, JSON.stringify(record));\n\n      return ok(undefined);\n    } catch (error: unknown) {\n      return err(\n        createIconlyError('storage_write_failed', 'Failed to write to SessionStorage.', error),\n      );\n    }\n  };\n\n  return { get, set };\n};\n","import type { IconStorage, StorageStrategy } from '../types';\nimport { createIndexedDbStorage } from './indexeddb';\nimport { createMemoryStorage } from './memory';\nimport { createSessionStorage } from './session';\n\nexport interface StorageFactoryOptions {\n  dbName?: string;\n  storeName?: string;\n  sessionKeyPrefix?: string;\n}\n\nexport const resolveStorage = (\n  strategy: StorageStrategy | undefined,\n  options: StorageFactoryOptions,\n): IconStorage => {\n  if (!strategy || strategy === 'indexeddb') {\n    return createIndexedDbStorage({\n      dbName: options.dbName,\n      storeName: options.storeName,\n    });\n  }\n\n  if (strategy === 'memory') {\n    return createMemoryStorage();\n  }\n\n  if (strategy === 'session') {\n    return createSessionStorage({ keyPrefix: options.sessionKeyPrefix });\n  }\n\n  return strategy;\n};\n","import { insertSvg } from './dom';\nimport { createIconlyError } from './errors';\nimport { fetchSvg } from './fetcher';\nimport { err, ok } from './result';\nimport { resolveStorage } from './storage';\nimport type { IconlyConfig, IconlyError, IconlyInstance, IconStorage, Result } from './types';\n\ninterface ResolvedIconlyConfig {\n  file: string;\n  version: string;\n  debug: boolean;\n  container?: string | HTMLElement;\n  logger?: IconlyConfig['logger'];\n  onError?: IconlyConfig['onError'];\n  onDebug?: IconlyConfig['onDebug'];\n}\n\nexport const createIconly = (config: IconlyConfig = {}): IconlyInstance => {\n  const resolved: ResolvedIconlyConfig = {\n    file: config.file ?? './icons.svg',\n    version: config.version ?? '1.0',\n    debug: config.debug ?? false,\n    container: config.container,\n    logger: config.logger,\n    onError: config.onError,\n    onDebug: config.onDebug,\n  };\n\n  const storage: IconStorage = resolveStorage(config.storage, {\n    dbName: config.dbName,\n    storeName: config.storeName,\n    sessionKeyPrefix: config.sessionKeyPrefix,\n  });\n\n  let controller: AbortController | null = null;\n\n  const abort = (): void => {\n    controller?.abort();\n  };\n\n  const resolveContainer = (): Result<HTMLElement> => {\n    if (typeof document === 'undefined') {\n      return err(\n        createIconlyError('container_invalid', 'Document is not available in this environment.'),\n      );\n    }\n\n    if (typeof resolved.container === 'string') {\n      const found = document.querySelector(resolved.container);\n\n      if (!found || !(found instanceof HTMLElement)) {\n        return err(\n          createIconlyError(\n            'container_invalid',\n            `Invalid container selector: \"${resolved.container}\".`,\n          ),\n        );\n      }\n\n      return ok(found);\n    }\n\n    if (resolved.container instanceof HTMLElement) {\n      return ok(resolved.container);\n    }\n\n    const fallback = document.body ?? document.documentElement;\n\n    if (!fallback) {\n      return err(createIconlyError('container_invalid', 'No valid container element found.'));\n    }\n\n    return ok(fallback);\n  };\n\n  const logDebug = (...messages: unknown[]): void => {\n    if (!resolved.debug) {\n      return;\n    }\n\n    resolved.onDebug?.(...messages);\n    resolved.logger?.debug?.('[Iconly debug]', ...messages);\n  };\n\n  const logError = (error: IconlyError): void => {\n    resolved.onError?.(error);\n    resolved.logger?.error?.('[Iconly error]', error);\n  };\n\n  const fail = (error: IconlyError): Result<void> => {\n    logError(error);\n\n    return err(error);\n  };\n\n  const init = async (): Promise<Result<void>> => {\n    const containerResult = resolveContainer();\n\n    if (!containerResult.ok) {\n      return fail(containerResult.error);\n    }\n\n    const cacheResult = await storage.get(resolved.version);\n\n    if (!cacheResult.ok) {\n      return fail(cacheResult.error);\n    }\n\n    let data = cacheResult.value?.data;\n\n    if (!data) {\n      controller = new AbortController();\n\n      const fetchResult = await fetchSvg(resolved.file, controller.signal);\n\n      if (!fetchResult.ok) {\n        return fail(fetchResult.error);\n      }\n\n      data = fetchResult.value;\n\n      const storeResult = await storage.set({\n        version: resolved.version,\n        data,\n      });\n\n      if (!storeResult.ok) {\n        return fail(storeResult.error);\n      }\n    } else {\n      logDebug('Using cached icon set', resolved.version);\n    }\n\n    const insertResult = insertSvg(containerResult.value, data);\n\n    if (!insertResult.ok) {\n      return fail(insertResult.error);\n    }\n\n    logDebug('Iconly has successfully initialized.');\n\n    return ok(undefined);\n  };\n\n  return { init, abort };\n};\n"],"mappings":"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"}

package/dist/index.d.cts

@@ -0,0 +1,50 @@
+//#region src/types.d.ts
+type Result<T> = {
+  ok: true;
+  value: T;
+} | {
+  ok: false;
+  error: IconlyError;
+};
+type IconlyErrorCode = 'container_invalid' | 'fetch_aborted' | 'fetch_failed' | 'indexeddb_not_supported' | 'indexeddb_open_failed' | 'indexeddb_request_failed' | 'parse_error' | 'storage_read_failed' | 'storage_unavailable' | 'storage_write_failed';
+interface IconlyError {
+  code: IconlyErrorCode;
+  message: string;
+  cause?: unknown;
+}
+interface Logger {
+  debug?: (...messages: unknown[]) => void;
+  error?: (...messages: unknown[]) => void;
+}
+interface IconRecord {
+  version: string;
+  data: string;
+}
+interface IconStorage {
+  get(version: string): Promise<Result<IconRecord | undefined>>;
+  set(record: IconRecord): Promise<Result<void>>;
+}
+interface IconlyInstance {
+  init: () => Promise<Result<void>>;
+  abort: () => void;
+}
+type StorageStrategy = 'indexeddb' | 'memory' | 'session' | IconStorage;
+interface IconlyConfig {
+  file?: string;
+  version?: string;
+  debug?: boolean;
+  container?: string | HTMLElement;
+  storage?: StorageStrategy;
+  dbName?: string;
+  storeName?: string;
+  sessionKeyPrefix?: string;
+  logger?: Logger;
+  onError?: (error: IconlyError) => void;
+  onDebug?: (...messages: unknown[]) => void;
+}
+//#endregion
+//#region src/core.d.ts
+declare const createIconly: (config?: IconlyConfig) => IconlyInstance;
+//#endregion
+export { type IconRecord, type IconStorage, type IconlyConfig, type IconlyError, type IconlyErrorCode, type IconlyInstance, type Logger, type Result, type StorageStrategy, createIconly };
+//# sourceMappingURL=index.d.cts.map

package/dist/index.d.ts

@@ -1,55 +1,50 @@
-export declare const createIconly: (config?: IconlyConfig) => IconlyInstance;
-
-export declare interface IconlyConfig {
-    file?: string;
-    version?: string;
-    debug?: boolean;
-    container?: string | HTMLElement;
-    storage?: StorageStrategy;
-    dbName?: string;
-    storeName?: string;
-    sessionKeyPrefix?: string;
-    logger?: Logger;
-    onError?: (error: IconlyError) => void;
-    onDebug?: (...messages: unknown[]) => void;
-}
-
-export declare interface IconlyError {
-    code: IconlyErrorCode;
-    message: string;
-    cause?: unknown;
-}
-
-export declare type IconlyErrorCode = 'container_invalid' | 'fetch_aborted' | 'fetch_failed' | 'indexeddb_not_supported' | 'indexeddb_open_failed' | 'indexeddb_request_failed' | 'parse_error' | 'storage_read_failed' | 'storage_unavailable' | 'storage_write_failed';
-
-export declare interface IconlyInstance {
-    init: () => Promise<Result<void>>;
-    abort: () => void;
-}
-
-export declare interface IconRecord {
-    version: string;
-    data: string;
-}
-
-export declare interface IconStorage {
-    get(version: string): Promise<Result<IconRecord | undefined>>;
-    set(record: IconRecord): Promise<Result<void>>;
-}
-
-export declare interface Logger {
-    debug?: (...messages: unknown[]) => void;
-    error?: (...messages: unknown[]) => void;
-}
-
-export declare type Result<T> = {
-    ok: true;
-    value: T;
-} | {
-    ok: false;
-    error: IconlyError;
-};
-
-export declare type StorageStrategy = 'indexeddb' | 'memory' | 'session' | IconStorage;
-
-export { }
+//#region src/types.d.ts
+type Result<T> = {
+  ok: true;
+  value: T;
+} | {
+  ok: false;
+  error: IconlyError;
+};
+type IconlyErrorCode = 'container_invalid' | 'fetch_aborted' | 'fetch_failed' | 'indexeddb_not_supported' | 'indexeddb_open_failed' | 'indexeddb_request_failed' | 'parse_error' | 'storage_read_failed' | 'storage_unavailable' | 'storage_write_failed';
+interface IconlyError {
+  code: IconlyErrorCode;
+  message: string;
+  cause?: unknown;
+}
+interface Logger {
+  debug?: (...messages: unknown[]) => void;
+  error?: (...messages: unknown[]) => void;
+}
+interface IconRecord {
+  version: string;
+  data: string;
+}
+interface IconStorage {
+  get(version: string): Promise<Result<IconRecord | undefined>>;
+  set(record: IconRecord): Promise<Result<void>>;
+}
+interface IconlyInstance {
+  init: () => Promise<Result<void>>;
+  abort: () => void;
+}
+type StorageStrategy = 'indexeddb' | 'memory' | 'session' | IconStorage;
+interface IconlyConfig {
+  file?: string;
+  version?: string;
+  debug?: boolean;
+  container?: string | HTMLElement;
+  storage?: StorageStrategy;
+  dbName?: string;
+  storeName?: string;
+  sessionKeyPrefix?: string;
+  logger?: Logger;
+  onError?: (error: IconlyError) => void;
+  onDebug?: (...messages: unknown[]) => void;
+}
+//#endregion
+//#region src/core.d.ts
+declare const createIconly: (config?: IconlyConfig) => IconlyInstance;
+//#endregion
+export { type IconRecord, type IconStorage, type IconlyConfig, type IconlyError, type IconlyErrorCode, type IconlyInstance, type Logger, type Result, type StorageStrategy, createIconly };
+//# sourceMappingURL=index.d.ts.map