@rune-hub/utils 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mike Lysikov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,377 @@
+<h1 align="center">
+<a href="https://github.com/d8corp/rune-hub">
+<img src="https://cdn.jsdelivr.net/gh/d8corp/rune-hub@main/logo.svg" width="80">
+</a>
+<br>
+@rune-hub/utils
+</h1>
+
+<div align="center">
+  <a href="https://www.npmjs.com/package/@rune-hub/utils" target="_blank">
+    <img src="https://img.shields.io/npm/v/@rune-hub/utils.svg" alt="rune-hub npm">
+  </a>
+  <a href="https://github.com/d8corp/rune-hub-utils" target="_blank">
+    <img src="https://img.shields.io/badge/-GitHub-181717?logo=github&logoColor=white" alt="rune-hub source code">
+  </a>
+  <a href="https://www.npmtrends.com/@rune-hub/utils" target="_blank">
+    <img src="https://img.shields.io/npm/dm/@rune-hub/utils.svg" alt="rune-hub downloads">
+  </a>
+  <a href="https://github.com/d8corp/rune-hub-utils/tree/main/release" target="_blank">
+    <img src="https://packagephobia.com/badge?p=@rune-hub/utils" alt="rune-hub install size">
+  </a>
+  <a href="https://www.typescriptlang.org" target="_blank">
+    <img src="https://img.shields.io/npm/types/@rune-hub/utils" alt="TypeScript">
+  </a>
+  <a href="https://github.com/d8corp/rune-hub-utils/blob/main/LICENSE" target="_blank">
+    <img src="https://img.shields.io/npm/l/@rune-hub/utils" alt="rune-hub license">
+  </a>
+  <a href="https://github.com/d8corp/rune-hub-utils/blob/main/CHANGELOG.md" target="_blank">
+    <img src="https://img.shields.io/badge/Changelog-⋮-brightgreen" alt="rune-hub changelog">
+  </a>
+  <a href="https://d8corp.github.io/rune-hub-utils/coverage/lcov-report" target="_blank">
+    <img src="https://github.com/d8corp/rune-hub-utils/actions/workflows/tests.yml/badge.svg" alt="rune-hub tests">
+  </a>
+  <a href="https://github.com/d8corp/rune-hub-utils/issues" target="_blank">
+    <img src="https://img.shields.io/github/issues-raw/d8corp/rune-hub-utils" alt="Open issues">
+  </a>
+  <a href="https://github.com/d8corp/rune-hub-utils/pulls" target="_blank">
+    <img src="https://img.shields.io/github/issues-pr-raw/d8corp/rune-hub-utils" alt="Pull requests">
+  </a>
+</div>
+<br>
+
+`@rune-hub/utils` provides utility hooks for [rune-hub](https://www.npmjs.com/package/rune-hub) that simplify common patterns like persistent state management.
+The library includes specialized hooks for browser storage synchronization with automatic encoding/decoding, cross-tab updates, and type-safe interfaces.
+
+[![stars](https://img.shields.io/github/stars/d8corp/rune-hub-utils?style=social)](https://github.com/d8corp/rune-hub-utils/stargazers)
+[![watchers](https://img.shields.io/github/watchers/d8corp/rune-hub-utils?style=social)](https://github.com/d8corp/rune-hub-utils/watchers)
+
+## Index
+
+<sup>**[ [Install](#install) ]**</sup>  
+<sup>**[ [Hooks](#hooks) ]** [persistent](#persistent) • [persistentBool](#persistentbool) • [persistentNum](#persistentnum) • [persistentJSON](#persistentjson)</sup>  
+<sup>**[ [Links](#links) ]**</sup>
+
+## Install
+###### [🏠︎](#index) / Install [↓](#hooks)
+
+**Requires [rune-hub 1.0+](https://www.npmjs.com/package/rune-hub) as a peer dependency.**
+
+These utilities are designed to work with rune-hub's reactive state management system.
+Make sure to install both packages:
+
+```shell
+npm i rune-hub @rune-hub/utils
+```
+
+## Hooks
+###### [🏠︎](#index) / Hooks [↑](#install) [↓](#links)
+
+<sup>[persistent](#persistent) • [persistentBool](#persistentbool) • [persistentNum](#persistentnum) • [persistentJSON](#persistentjson)</sup>
+
+### persistent
+###### [🏠︎](#index) / [Hooks](#hooks) / persistent [↓](#persistentbool)
+
+Creates a persistent [Rune](https://github.com/d8corp/rune-hub#rune) that synchronizes its state with browser storage (`localStorage` by default).
+
+The Rune automatically loads the initial value from storage and saves changes back.
+It also listens to `storage` and `pageshow` events to sync state across tabs and page navigations.
+
+The simplest form accepts only a `key` parameter and works directly with string values.
+The Rune returns `string | null`.
+This approach provides direct one-to-one mapping between your state and storage:
+if there's no value in storage, you get `null`, otherwise you get the exact string stored.
+When you set the value to `null`, it clears the storage entry completely.
+
+```ts
+import { get, set } from 'rune-hub'
+import { persistent } from '@rune-hub/utils'
+
+const state = () => persistent('state')
+
+console.log(get(state)) // null initially
+
+set(state, 'foo')
+console.log(get(state)) // 'foo'
+
+set(state, null)
+console.log(get(state)) // null (storage is clean)
+```
+
+When you provide an `initial` value, it serves as a fallback when storage is empty.
+Note that passing `null` as the initial value works the same as omitting it entirely.
+
+When you provide a string as the `initial` value, the Rune becomes strictly typed and returns `string` (not nullable).
+In this mode, you cannot clear the state by setting it to the initial value — the storage will keep the entry with that value.
+This is useful when you always want a valid string state without null checks.
+
+```ts
+const lang = () => persistent('lang', 'en')
+
+console.log(get(lang)) // 'en' initially
+
+set(lang, 'ru')
+console.log(get(lang)) // 'ru'
+
+set(lang, 'en')
+console.log(get(lang)) // 'en' (storage is not clean)
+```
+
+This approach also allows you to safely change the default value in the future.
+For example, if the default theme was initially `'dark'`, a user changed it to `'light'`, then back to `'dark'`.
+Later, developers change the default to `'auto'` — users who manually selected `'dark'` will keep their choice because it's stored.
+Only users who never changed this setting (no value in storage) will get the new `'auto'` default.
+
+You can specify allowed state variants using generics to get type safety and autocomplete:
+
+```ts
+type Theme = 'dark' | 'light' | 'auto'
+const theme = () => persistent<Theme>('search', 'auto')
+```
+
+By default, `persistent` uses `localStorage`, which persists data permanently across browser sessions and tabs.
+You can use `sessionStorage` instead for temporary data that only exists within the current tab and is cleared when the tab closes.
+Also, you can use simple/proxy object as storage, the storage changes by set or delete value (`storage[key] = value` or `delete storage[key]`).
+
+```ts
+const chatDraft = () => persistent('chatDraft', '', {
+  storage: sessionStorage
+})
+```
+
+When your state type is not `string | null`, you must provide `encode` and `decode` functions to convert between your type and string storage format.
+
+The `encode` function converts your state value to a string (or `null` to clear storage), while `decode` converts the stored string back to your state type.
+
+```ts
+const isEnabled = () => persistent('isEnabled', false, {
+  decode: v => v === '+',
+  encode: v => v ? '+' : '-'
+})
+
+set(isEnabled, true)
+console.log(localStorage.getItem('isEnabled')) // '+'
+```
+
+For `string | null` or `string` state types, you can optionally provide `encode` and `decode` to override the default conversion logic.
+For example, you can make the state clear from storage when set back to the initial value:
+
+```ts
+const lang = () => persistent('lang', '', {
+  encode: v => v ? v : null
+})
+
+set(lang, 'en')
+console.log(localStorage.getItem('lang')) // 'en'
+
+set(lang, '')
+console.log(localStorage.getItem('lang')) // null (storage is clean)
+```
+
+### persistentBool
+###### [🏠︎](#index) / [Hooks](#hooks) / persistentBool [↑](#persistent) [↓](#persistentnum)
+
+Creates a persistent Rune for boolean values with convenient string encoding (`+` for true, `-` for false by default).
+Automatically loads the initial value from storage and saves changes back to it.
+
+The simplest form accepts only a `key` parameter and works with nullable boolean values.
+The Rune returns `boolean | null`.
+If there's no value in storage, you get `null`, otherwise you get the decoded boolean value.
+When you set the value to `null`, it clears the storage entry completely.
+
+```ts
+import { get, set } from 'rune-hub'
+import { persistentBool } from '@rune-hub/utils'
+
+const consent = () => persistentBool('consent')
+
+console.log(get(consent)) // null initially
+
+set(consent, true)
+console.log(get(consent)) // true
+console.log(localStorage.getItem('consent')) // '+' (encoded)
+
+set(consent, null)
+console.log(get(consent)) // null (storage is clean)
+```
+
+When you provide an `initial` value, it serves as a fallback when storage is empty.
+When you provide a boolean as the `initial` value, the Rune becomes strictly typed and returns `boolean` (not nullable).
+In this mode, you cannot clear the state by setting it to `null` — the storage will keep the entry with the encoded value.
+This is useful when you always want a valid boolean state without null checks.
+
+```ts
+const isDarkMode = () => persistentBool('darkMode', false)
+
+console.log(get(isDarkMode)) // false initially
+
+set(isDarkMode, true)
+console.log(localStorage.getItem('darkMode')) // '+' (true encoded)
+
+set(isDarkMode, false)
+console.log(localStorage.getItem('darkMode')) // '-' (false encoded)
+```
+
+You can customize the encoding by specifying what strings represent `true` and `false`:
+
+```ts
+const isAccepted = () => persistentBool('accepted', false, {
+  true: 'yes',
+  false: 'no'
+})
+
+set(isAccepted, true)
+console.log(localStorage.getItem('accepted')) // 'yes'
+```
+
+By default, `persistentBool` uses `localStorage` for permanent persistence across browser sessions.
+You can use `sessionStorage` instead for temporary data that only exists within the current tab and is cleared when the tab closes.
+You can also use a simple/proxy object as storage.
+
+```ts
+const isExpanded = () => persistentBool('expanded', false, {
+  storage: sessionStorage
+})
+```
+
+### persistentNum
+###### [🏠︎](#index) / [Hooks](#hooks) / persistentNum [↑](#persistentbool) [↓](#persistentjson)
+
+Creates a persistent Rune for numeric values with automatic number parsing and string conversion.
+Automatically loads the initial value from storage and saves changes back to it.
+
+The simplest form accepts only a `key` parameter and works with nullable numeric values.
+The Rune returns `number | null`.
+
+If there's no value in storage, you get `null`, otherwise you get the parsed number.
+When you set the value to `null`, it clears the storage entry completely.
+
+```ts
+import { get, set } from 'rune-hub'
+import { persistentNum } from '@rune-hub/utils'
+
+const score = () => persistentNum('score')
+
+console.log(get(score)) // null initially
+
+set(score, 100)
+console.log(get(score)) // 100
+console.log(localStorage.getItem('score')) // '100'
+
+set(score, null)
+console.log(get(score)) // null (storage is clean)
+console.log(localStorage.getItem('score')) // null
+```
+
+When you provide an `initial` value, it serves as a fallback when storage is empty.
+When you provide a number as the `initial` value, the Rune becomes strictly typed and returns `number` (not nullable).
+In this mode, you cannot clear the state by setting it to `null` — the storage will keep the entry with that value.
+This is useful when you always want a valid numeric state without null checks.
+
+```ts
+const count = () => persistentNum('count', 0)
+
+console.log(get(count)) // 0 initially
+
+set(count, 42)
+console.log(localStorage.getItem('count')) // '42'
+
+set(count, 0)
+console.log(localStorage.getItem('count')) // '0' (storage is not clean)
+```
+
+By default, `persistentNum` uses `localStorage` for permanent persistence across browser sessions.
+You can use `sessionStorage` instead for temporary data that only exists within the current tab and is cleared when the tab closes.
+You can also use a simple/proxy object as storage.
+
+```ts
+const tempCounter = () => persistentNum('counter', 0, {
+  storage: sessionStorage
+})
+```
+
+### persistentJSON
+###### [🏠︎](#index) / [Hooks](#hooks) / persistentJSON [↑](#persistentnum)
+
+Creates a persistent Rune with automatic JSON serialization/deserialization for complex data structures.
+Automatically loads the initial value from storage and saves changes back to it.
+
+The simplest form accepts only a `key` parameter and works with nullable values.
+The Rune returns `T | null` where `T` is your data type.
+
+If there's no value in storage, you get `null`, otherwise you get the parsed object.
+When you set the value to `null`, it stores the string `"null"` in storage (unlike other persistent hooks).
+
+```ts
+import { get, set } from 'rune-hub'
+import { persistentJSON } from '@rune-hub/utils'
+
+interface User {
+  name: string
+  age: number
+}
+
+const user = () => persistentJSON<User>('user')
+
+console.log(get(user)) // null initially
+
+set(user, { name: 'John', age: 30 })
+console.log(get(user)) // { name: 'John', age: 30 }
+console.log(localStorage.getItem('user')) // '{"name":"John","age":30}'
+
+set(user, null)
+console.log(localStorage.getItem('user')) // '"null"' (stored as string)
+```
+
+When you provide an `initial` value, it serves as a fallback when storage is empty.
+When you provide an object as the `initial` value, the Rune becomes strictly typed and returns your type `T` (not nullable).
+In this mode, you cannot clear the state by setting it to `null` — the storage will keep the entry with the encoded value.
+This is useful when you always want a valid object state without null checks.
+
+```ts
+import { get, set } from 'rune-hub'
+import { persistentJSON } from '@rune-hub/utils'
+
+const user = () => persistentJSON('user', { name: 'John', age: 30 })
+
+console.log(get(user)) // { name: 'John', age: 30 } initially
+
+set(user, { name: 'Jane', age: 25 })
+console.log(localStorage.getItem('user')) // '{"name":"Jane","age":25}'
+
+set(user, { name: 'John', age: 30 })
+console.log(localStorage.getItem('user')) // '{"name":"John","age":30}' (storage is not clean)
+```
+
+You can also use `persistentJSON` with arrays:
+
+```ts
+const items = () => persistentJSON<string[]>('items', [])
+
+set(items, ['apple', 'banana', 'orange'])
+console.log(get(items)) // ['apple', 'banana', 'orange']
+console.log(localStorage.getItem('items')) // '["apple","banana","orange"]'
+```
+
+By default, `persistentJSON` uses `localStorage` for permanent persistence across browser sessions.
+You can use `sessionStorage` instead for temporary data that only exists within the current tab and is cleared when the tab closes.
+You can also use a simple/proxy object as storage.
+
+```ts
+const tempData = () => persistentJSON<any>('data', null, {
+  storage: sessionStorage
+})
+```
+
+## Links
+###### [🏠︎](#index) / Links [↑](#hooks)
+
+- **Creator**: [Mike Lysikov](http://github.com/d8corp)
+- **Source Code**: [GitHub](https://github.com/d8corp/rune-hub-utils)
+- **Repository**: [npm](https://www.npmjs.com/package/@rune-hub/utils) • [npmx](https://npmx.dev/package/@rune-hub/utils)
+- **Core**: [rune-hub](https://github.com/d8corp/rune-hub)
+
+**Contributions are welcome!** Please feel free to submit [issues](https://github.com/d8corp/rune-hub-utils/issues) and [pull requests](https://github.com/d8corp/rune-hub-utils/pulls).
+
+[![issues](https://img.shields.io/github/issues-raw/d8corp/rune-hub-utils)](https://github.com/d8corp/rune-hub-utils/issues)
+[![pulls](https://img.shields.io/github/issues-pr-raw/d8corp/rune-hub-utils)](https://github.com/d8corp/rune-hub-utils/pulls)

package/hooks/index.d.ts

@@ -0,0 +1,5 @@
+export * from './persistent';
+export * from './persistentBool';
+export * from './persistentJSON';
+export * from './persistentNum';
+export * from './persistentRune';

package/hooks/index.js

@@ -0,0 +1,8 @@
+'use strict';
+
+require('./persistent/index.js');
+require('./persistentBool/index.js');
+require('./persistentJSON/index.js');
+require('./persistentNum/index.js');
+require('./persistentRune/index.js');
+

package/hooks/index.mjs

@@ -0,0 +1,5 @@
+import './persistent/index.mjs';
+import './persistentBool/index.mjs';
+import './persistentJSON/index.mjs';
+import './persistentNum/index.mjs';
+import './persistentRune/index.mjs';

package/hooks/persistent/index.d.ts

@@ -0,0 +1 @@
+export * from './persistent';

package/hooks/persistent/index.js

@@ -0,0 +1,9 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var persistent = require('./persistent.js');
+
+
+
+exports.persistent = persistent.persistent;

package/hooks/persistent/index.mjs

@@ -0,0 +1 @@
+export { persistent } from './persistent.mjs';

package/hooks/persistent/persistent.d.ts

@@ -0,0 +1,69 @@
+import type { PersistentStorage } from '../persistentRune';
+export type PersistentDecode<T> = (v: string) => T;
+export type PersistentEncode<T> = (v: T) => string | null;
+export interface PersistentParams<T> {
+    decode: PersistentDecode<T>;
+    encode: PersistentEncode<T>;
+    storage?: PersistentStorage;
+}
+/**
+ * Creates a persistent Rune that synchronizes its state with browser storage (localStorage by default).
+ *
+ * The Rune automatically loads the initial value from storage and saves changes back.
+ * It also listens to `storage` and `pageshow` events to sync state across tabs and page navigations.
+ *
+ * @param key - Storage key to persist the value under
+ * @returns The current stored value (string | null) when called with only a key
+ *
+ * @example
+ * ```ts
+ * const theme = () => persistent('theme')
+ *
+ * console.log(get(theme)) // null initially
+ * set(theme, 'dark')
+ * console.log(localStorage.getItem('theme')) // 'dark'
+ * ```
+ */
+export declare function persistent(key: string): string | null;
+/**
+ * Creates a persistent Rune with custom encoding/decoding logic.
+ *
+ * @param key - Storage key to persist the value under
+ * @param initial - Initial value to use when storage is empty
+ * @param params - Encoding/decoding parameters and optional storage
+ * @returns The current value (decoded from storage or initial value)
+ *
+ * @example
+ * ```ts
+ * const isEnabled = () => persistent('isEnabled', false, {
+ *   decode: v => v === '+',
+ *   encode: v => v ? '+' : '-'
+ * })
+ *
+ * set(isEnabled, true)
+ * console.log(localStorage.getItem('isEnabled')) // '+'
+ * ```
+ */
+export declare function persistent<T, I = T>(key: string, initial: I, params: PersistentParams<T | I>): I | (unknown extends T ? string : T);
+/**
+ * Creates a persistent Rune of `string | null` with optional params.
+ *
+ * @param key - Storage key to persist the value under
+ * @param initial - Initial value to use when storage is empty
+ * @param params - Optional encoding/decoding parameters and storage
+ * @returns The current value (from storage or initial value)
+ *
+ * @example
+ * ```ts
+ * const lang = () => persistent('lang', 'en')
+ *
+ * console.log(get(lang)) // 'en' initially
+ *
+ * set(lang, 'ru')
+ * console.log(localStorage.getItem('lang')) // 'ru'
+ *
+ * set(lang, 'en')
+ * console.log(localStorage.getItem('lang')) // 'en' (storage is not clean)
+ * ```
+ */
+export declare function persistent<T, I extends string | null = T extends string | null ? T : string | null>(key: string, initial: I, params?: Partial<PersistentParams<T | I>>): I | (unknown extends T ? string : T);

package/hooks/persistent/persistent.js

@@ -0,0 +1,41 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var runeHub = require('rune-hub');
+require('../persistentRune/index.js');
+var persistentRune = require('../persistentRune/persistentRune.js');
+
+const asIs = (v) => v;
+function persistent(key, initial = null, params) {
+    var _a, _b, _c;
+    const ctx = ((_a = runeHub.Hub.cur) !== null && _a !== void 0 ? _a : runeHub.Hub.root).ctx;
+    if (!ctx)
+        return initial;
+    const decode = ((_b = params === null || params === void 0 ? void 0 : params.decode) !== null && _b !== void 0 ? _b : asIs);
+    const initDecode = (value = null) => {
+        return value === null ? initial : decode(value);
+    };
+    const persistentSlot = runeHub.slot(persistentRune.persistentRune(key, params === null || params === void 0 ? void 0 : params.storage));
+    let result = persistentSlot.value;
+    if (!ctx.inited) {
+        const encode = ((_c = params === null || params === void 0 ? void 0 : params.encode) !== null && _c !== void 0 ? _c : asIs);
+        ctx.on('change', () => {
+            result = encode(ctx.cur);
+            persistentSlot.set(result);
+        });
+        ctx.on('get', () => {
+            if (!ctx.up) {
+                const value = persistentSlot.raw;
+                if (result !== value) {
+                    result = value;
+                    ctx.prev = ctx.cur;
+                    ctx.cur = initDecode(result);
+                }
+            }
+        });
+    }
+    return initDecode(result);
+}
+
+exports.persistent = persistent;

package/hooks/persistent/persistent.mjs

@@ -0,0 +1,37 @@
+import { Hub, slot } from 'rune-hub';
+import '../persistentRune/index.mjs';
+import { persistentRune } from '../persistentRune/persistentRune.mjs';
+
+const asIs = (v) => v;
+function persistent(key, initial = null, params) {
+    var _a, _b, _c;
+    const ctx = ((_a = Hub.cur) !== null && _a !== void 0 ? _a : Hub.root).ctx;
+    if (!ctx)
+        return initial;
+    const decode = ((_b = params === null || params === void 0 ? void 0 : params.decode) !== null && _b !== void 0 ? _b : asIs);
+    const initDecode = (value = null) => {
+        return value === null ? initial : decode(value);
+    };
+    const persistentSlot = slot(persistentRune(key, params === null || params === void 0 ? void 0 : params.storage));
+    let result = persistentSlot.value;
+    if (!ctx.inited) {
+        const encode = ((_c = params === null || params === void 0 ? void 0 : params.encode) !== null && _c !== void 0 ? _c : asIs);
+        ctx.on('change', () => {
+            result = encode(ctx.cur);
+            persistentSlot.set(result);
+        });
+        ctx.on('get', () => {
+            if (!ctx.up) {
+                const value = persistentSlot.raw;
+                if (result !== value) {
+                    result = value;
+                    ctx.prev = ctx.cur;
+                    ctx.cur = initDecode(result);
+                }
+            }
+        });
+    }
+    return initDecode(result);
+}
+
+export { persistent };

package/hooks/persistentBool/index.d.ts

@@ -0,0 +1 @@
+export * from './persistentBool';

package/hooks/persistentBool/index.js

@@ -0,0 +1,9 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var persistentBool = require('./persistentBool.js');
+
+
+
+exports.persistentBool = persistentBool.persistentBool;

package/hooks/persistentBool/index.mjs

@@ -0,0 +1 @@
+export { persistentBool } from './persistentBool.mjs';

package/hooks/persistentBool/persistentBool.d.ts

@@ -0,0 +1,66 @@
+import type { PersistentParams } from '../persistent';
+export interface PersistentBoolParams<T extends boolean | null = boolean | null> extends Omit<PersistentParams<T>, 'decode' | 'encode'> {
+    true?: string;
+    false?: string;
+}
+/**
+ * Creates a persistent Rune for boolean values with customizable string representations.
+ *
+ * The Rune automatically loads the initial value from storage (localStorage by default) and saves changes back.
+ * It also listens to `storage` and `pageshow` events to sync state across tabs and page navigations.
+ *
+ * @param key - Storage key to persist the value under.
+ * @param initial - Initial value to use when storage is empty. Can be `boolean` or `null`.
+ * @param params - Optional parameters to customize string representations for `true` and `false` values.
+ * @returns The current value (from storage or initial value). Return type depends on `initial`:
+ * - If `initial` is `null`, returns `boolean | null`.
+ * - Otherwise, returns `boolean`.
+ *
+ * @example Basic usage without initial value
+ * ```ts
+ * const isDarkMode = () => persistentBool('darkMode')
+ *
+ * console.log(get(isDarkMode)) // null initially
+ *
+ * set(isDarkMode, true)
+ * console.log(localStorage.getItem('darkMode')) // '+'
+ *
+ * set(isDarkMode, null)
+ * console.log(localStorage.getItem('darkMode')) // null
+ * ```
+ *
+ * @example Basic usage with initial value
+ * ```ts
+ * const isDarkMode = () => persistentBool('darkMode', false)
+ *
+ * console.log(get(isDarkMode)) // false initially
+ *
+ * set(isDarkMode, true)
+ * console.log(localStorage.getItem('darkMode')) // '+'
+ *
+ * set(isDarkMode, false)
+ * console.log(localStorage.getItem('darkMode')) // '-'
+ * ```
+ *
+ * @example Basic usage with custom storage values
+ * ```ts
+ * const isEnabled = () => persistentBool('isEnabled', false, {
+ *   true: 'enabled',
+ *   false: 'disabled'
+ * })
+ *
+ * set(isEnabled, true)
+ * console.log(localStorage.getItem('isEnabled')) // 'enabled'
+ * ```
+ *
+ * @example Usage with custom storage
+ * ```ts
+ * const isEnabled = () => persistentBool('isEnabled', false, {
+ *   storage: sessionStorage,
+ * })
+ *
+ * set(isEnabled, true)
+ * console.log(sessionStorage.getItem('isEnabled')) // '+'
+ * ```
+ */
+export declare function persistentBool<T extends boolean | null = boolean | null>(key: string, initial?: T, params?: PersistentBoolParams<T>): T extends null ? null | boolean : boolean;