@delphington/persistent-buckets 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Delph
+
+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,48 @@
+# persistent-buckets
+
+Versioned `localStorage` buckets backed by shared Vue refs.
+
+## Usage
+
+```ts
+import { defineBucket } from '@delphington/persistent-buckets';
+
+type Preferences = {
+  theme: 'light' | 'dark';
+};
+
+export const preferences = defineBucket<Preferences>({
+  key: 'example:preferences',
+  version: 0,
+  initial: { theme: 'light' },
+  migrate(version, stored) {
+    if (version !== 0) throw new Error('Unsupported preferences version');
+    return stored as Preferences;
+  },
+});
+```
+
+`state` is a shared Vue ref. Changes must be saved explicitly:
+
+```ts
+const state = preferences.state;
+state.value.theme = 'dark';
+preferences.save();
+```
+
+Bucket modules self-register when they are imported. Import every bucket at the application's entry point so aggregate operations always use the complete set:
+
+```ts
+import './persistence/buckets/history';
+import './persistence/buckets/preferences';
+```
+
+Vite applications can instead eagerly import a bucket directory:
+
+```ts
+import.meta.glob('./persistence/buckets/*.ts', { eager: true });
+```
+
+Only imported buckets are included by `persistence.dump()`, `persistence.restore()`, `persistence.reset()`, and `persistence.prune()`.
+
+Bucket data must be JSON-serializable. If `localStorage` is unavailable, data is kept in memory and `persistence.ephemeral` is `true`.

package/dist/bucket.d.ts

@@ -0,0 +1,69 @@
+import { type Ref } from 'vue';
+/** Defines a bucket */
+export type BucketDefinition<T> = {
+    /** A unique localStorage key. */
+    readonly key: string;
+    /** The schema version written by `save`. */
+    readonly version: number;
+    /** The value returned when no valid stored value exists. */
+    readonly initial: T;
+    /**
+     * Validates stored data and migrates older versions to the current shape.
+     * @param version The schema version of the stored data
+     * @param stored The untrusted value read from storage
+     * @returns Data in the current bucket shape
+     */
+    migrate: (version: number, stored: unknown) => T;
+    /**
+     * Removes obsolete data in place.
+     * @returns The number of removed records
+     */
+    prune?: (data: T) => number;
+};
+/** A user-operatable bucket */
+export type Bucket<T> = {
+    /** The bucket's key */
+    readonly key: string;
+    readonly state: Ref<T>;
+    dump: () => PersistedBucket<T>;
+    prune: () => number;
+    reset: () => T;
+    restore: (stored: unknown) => T;
+    save: () => void;
+};
+/**
+ * Record of what a bucket is for syncronise operations across all buckets
+ */
+export type RegisteredBucket = {
+    /** The bucket's storage key */
+    readonly key: string;
+    /** The function to dump/export the bucket */
+    dump: () => PersistedBucket<unknown>;
+    /** The function which parses an unknown JSON object, migrates if necessary */
+    parse: (stored: unknown) => unknown;
+    /** The user-provided callback function of how to prune records (for operations like soft-deletion handling) */
+    prune: () => number;
+    /** Clears the bucket */
+    reset: () => unknown;
+    /** Restores the bucket's state to the provided value */
+    restore: (stored: unknown) => unknown;
+    /** Same as restore */
+    restoreData: (data: unknown) => unknown;
+};
+/**
+ * The versioned envelope used to store a bucket.
+ */
+export type PersistedBucket<T> = {
+    version: number;
+    data: T;
+};
+export declare const buckets: Map<string, RegisteredBucket>;
+/**
+ * Creates a persistent bucket and registers it for aggregate operations.
+ * `state` returns one shared Vue ref. Mutating that ref does not write to
+ * storage until `save()` is called.
+ * @param bucket The bucket definition
+ * @returns Operations for the defined bucket
+ */
+export declare function defineBucket<T>(bucket: BucketDefinition<T>): Bucket<T>;
+//# sourceMappingURL=bucket.d.ts.map

package/dist/bucket.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bucket.d.ts","sourceRoot":"","sources":["../src/bucket.ts"],"names":[],"mappings":"AAAA,OAAO,EAAO,KAAK,GAAG,EAAE,MAAM,KAAK,CAAC;AAIpC,uBAAuB;AACvB,MAAM,MAAM,gBAAgB,CAAC,CAAC,IAAI;IAChC,iCAAiC;IACjC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IAErB,4CAA4C;IAC5C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAEzB,4DAA4D;IAC5D,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC;IAEpB;;;;;OAKG;IACH,OAAO,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,KAAK,CAAC,CAAC;IAEjD;;;OAGG;IACH,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,MAAM,CAAC;CAC7B,CAAC;AAEF,+BAA+B;AAC/B,MAAM,MAAM,MAAM,CAAC,CAAC,IAAI;IACtB,uBAAuB;IACvB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC;IACvB,IAAI,EAAE,MAAM,eAAe,CAAC,CAAC,CAAC,CAAC;IAC/B,KAAK,EAAE,MAAM,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC,CAAC;IACf,OAAO,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,CAAC,CAAC;IAChC,IAAI,EAAE,MAAM,IAAI,CAAC;CAClB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,+BAA+B;IAC/B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,6CAA6C;IAC7C,IAAI,EAAE,MAAM,eAAe,CAAC,OAAO,CAAC,CAAC;IACrC,8EAA8E;IAC9E,KAAK,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,OAAO,CAAC;IACpC,+GAA+G;IAC/G,KAAK,EAAE,MAAM,MAAM,CAAC;IACpB,wBAAwB;IACxB,KAAK,EAAE,MAAM,OAAO,CAAC;IACrB,wDAAwD;IACxD,OAAO,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,OAAO,CAAC;IACtC,sBAAsB;IACtB,WAAW,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,OAAO,CAAC;CACzC,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,eAAe,CAAC,CAAC,IAAI;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,CAAC,CAAC;CACT,CAAC;AAEF,eAAO,MAAM,OAAO,+BAAsC,CAAC;AAY3D;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,MAAM,EAAE,gBAAgB,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,CAoHtE"}

package/dist/bucket.js

@@ -0,0 +1,119 @@
+import { ref } from 'vue';
+import { storage } from './storage';
+import { bytesToBase64Url, base64UrlToBytes, gzip, gunzip } from './text';
+export const buckets = new Map();
+function isPersistedBucket(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        'version' in value &&
+        'data' in value &&
+        typeof value.version === 'number');
+}
+/**
+ * Creates a persistent bucket and registers it for aggregate operations.
+ * `state` returns one shared Vue ref. Mutating that ref does not write to
+ * storage until `save()` is called.
+ * @param bucket The bucket definition
+ * @returns Operations for the defined bucket
+ */
+export function defineBucket(bucket) {
+    const state = ref(_load());
+    /**
+     * returns a copy of the initial data
+     */
+    function initial() {
+        return deepcopy(bucket.initial);
+    }
+    /**
+     * Loads the bucket data, if the data can't be loaded for any reason, loads the initial data
+     * @returns the loaded bucket data
+     */
+    function _load() {
+        try {
+            const raw = storage.getItem(bucket.key);
+            if (raw === null)
+                return initial();
+            const parsed = JSON.parse(raw);
+            if (!isPersistedBucket(parsed))
+                return initial();
+            return bucket.migrate(parsed.version, parsed.data);
+        }
+        catch {
+            return initial();
+        }
+    }
+    function _save(data) {
+        try {
+            const value = JSON.stringify({
+                version: bucket.version,
+                data: data,
+            });
+            storage.setItem(bucket.key, value);
+        }
+        catch (error) {
+            state.value = _load();
+            throw error;
+        }
+    }
+    function save() {
+        _save(state.value);
+    }
+    function prune() {
+        if (!bucket.prune)
+            return 0;
+        const data = deepcopy(state.value);
+        const removed = bucket.prune(data);
+        if (removed === 0)
+            return 0;
+        _save(data);
+        state.value = data;
+        return removed;
+    }
+    function dump() {
+        return {
+            version: bucket.version,
+            data: _load(),
+        };
+    }
+    function parse(stored) {
+        if (!isPersistedBucket(stored))
+            throw new Error(`Invalid persisted bucket ${bucket.key}`);
+        return bucket.migrate(stored.version, stored.data);
+    }
+    function restoreData(data) {
+        _save(data);
+        state.value = data;
+        return data;
+    }
+    function restore(stored) {
+        return restoreData(parse(stored));
+    }
+    function reset() {
+        storage.removeItem(bucket.key);
+        const value = _load();
+        state.value = value;
+        return value;
+    }
+    buckets.set(bucket.key, {
+        key: bucket.key,
+        dump,
+        parse,
+        prune,
+        reset,
+        restore,
+        restoreData: (data) => restoreData(data),
+    });
+    return {
+        key: bucket.key,
+        state,
+        dump,
+        prune,
+        reset,
+        restore,
+        save,
+    };
+}
+function deepcopy(data) {
+    return JSON.parse(JSON.stringify(data));
+}
+//# sourceMappingURL=bucket.js.map

package/dist/bucket.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bucket.js","sourceRoot":"","sources":["../src/bucket.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { defineBucket, type Bucket } from './bucket';
+export { persistence } from './persistence';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,KAAK,MAAM,EAAE,MAAM,UAAU,CAAC;AACrD,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC"}

package/dist/index.js

@@ -0,0 +1,3 @@
+export { defineBucket } from './bucket';
+export { persistence } from './persistence';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAe,MAAM,UAAU,CAAC;AACrD,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC"}

package/dist/persistence.d.ts

@@ -0,0 +1,55 @@
+import { type PersistedBucket } from './bucket';
+/**
+ * The portable representation of all registered buckets.
+ */
+export type PersistedDump = {
+    version: 0;
+    exportedAt: string;
+    buckets: Record<string, PersistedBucket<unknown>>;
+};
+/**
+ * Reads and exports every registered bucket from the active storage backend.
+ */
+declare function dump(): PersistedDump;
+/**
+ * Resets every registered bucket to its initial value.
+ */
+declare function reset(): void;
+/**
+ * Prunes every registered bucket.
+ * @returns The total number of removed records
+ */
+declare function prune(): number;
+/**
+ * Restores known buckets from a persistence dump. Registered buckets omitted
+ * from the dump are reset, and unknown buckets in the dump are ignored. If a
+ * write fails, the function attempts to restore the previous data.
+ * @param data The untrusted persistence dump to restore
+ */
+declare function restore(data: unknown): void;
+/**
+ * Exports registered buckets as gzip-compressed text when compression is
+ * available, or as formatted JSON otherwise.
+ * @param prefix The namespace prepended to compressed exports
+ */
+declare function exportText(prefix?: string): Promise<string>;
+/**
+ * Restores registered buckets from compressed export text or plain JSON.
+ * @param value The exported text to import
+ * @param prefix The namespace used by compressed exports
+ */
+declare function importText(value: string, prefix?: string): Promise<void>;
+export declare const persistence: {
+    /**
+     * if true, we've had to fall back to a shim with no persistence
+     */
+    ephemeral: boolean;
+    dump: typeof dump;
+    reset: typeof reset;
+    restore: typeof restore;
+    prune: typeof prune;
+    exportText: typeof exportText;
+    importText: typeof importText;
+};
+export {};
+//# sourceMappingURL=persistence.d.ts.map

package/dist/persistence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"persistence.d.ts","sourceRoot":"","sources":["../src/persistence.ts"],"names":[],"mappings":"AACA,OAAO,EAAW,KAAK,eAAe,EAAyB,MAAM,UAAU,CAAC;AAOhF;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B,OAAO,EAAE,CAAC,CAAC;IACX,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,OAAO,CAAC,CAAC,CAAC;CACnD,CAAC;AAEF;;GAEG;AACH,iBAAS,IAAI,IAAI,aAAa,CAQ7B;AAED;;GAEG;AACH,iBAAS,KAAK,SAEb;AAED;;;GAGG;AACH,iBAAS,KAAK,WAKb;AAED;;;;;GAKG;AACH,iBAAS,OAAO,CAAC,IAAI,EAAE,OAAO,QAkC7B;AAED;;;;GAIG;AACH,iBAAe,UAAU,CAAC,MAAM,SAAY,mBAQ3C;AAED;;;;GAIG;AACH,iBAAe,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,SAAY,iBAQ1D;AAED,eAAO,MAAM,WAAW;IACtB;;OAEG;;;;;;;;CAUJ,CAAC"}

package/dist/persistence.js

@@ -0,0 +1,104 @@
+import { storage, MemoryStorage } from './storage';
+import { buckets } from './bucket';
+import { bytesToBase64Url, base64UrlToBytes, gzip, gunzip } from './text';
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * Reads and exports every registered bucket from the active storage backend.
+ */
+function dump() {
+    return {
+        version: 0,
+        exportedAt: new Date().toISOString(),
+        buckets: Object.fromEntries([...buckets.values()].map((bucket) => [bucket.key, bucket.dump()])),
+    };
+}
+/**
+ * Resets every registered bucket to its initial value.
+ */
+function reset() {
+    for (const bucket of buckets.values())
+        bucket.reset();
+}
+/**
+ * Prunes every registered bucket.
+ * @returns The total number of removed records
+ */
+function prune() {
+    return [...buckets.values()].reduce((removed, bucket) => removed + bucket.prune(), 0);
+}
+/**
+ * Restores known buckets from a persistence dump. Registered buckets omitted
+ * from the dump are reset, and unknown buckets in the dump are ignored. If a
+ * write fails, the function attempts to restore the previous data.
+ * @param data The untrusted persistence dump to restore
+ */
+function restore(data) {
+    if (!isRecord(data) || data.version !== 0 || !isRecord(data.buckets))
+        throw new Error('Invalid persistence dump');
+    const restored = Object.entries(data.buckets)
+        .map(([key, stored]) => {
+        const bucket = buckets.get(key);
+        if (!bucket)
+            return;
+        return [bucket, bucket.parse(stored)];
+    })
+        .filter((entry) => entry !== undefined);
+    const previous = [...buckets.values()].map((bucket) => [bucket, bucket.dump()]);
+    try {
+        reset();
+        for (const [bucket, value] of restored)
+            bucket.restoreData(value);
+    }
+    catch (error) {
+        try {
+            reset();
+            for (const [bucket, value] of previous)
+                bucket.restore(value);
+        }
+        catch {
+            throw new Error('Import failed and previous data could not be restored');
+        }
+        throw error;
+    }
+}
+/**
+ * Exports registered buckets as gzip-compressed text when compression is
+ * available, or as formatted JSON otherwise.
+ * @param prefix The namespace prepended to compressed exports
+ */
+async function exportText(prefix = 'buckets') {
+    const data = dump();
+    const json = JSON.stringify(data);
+    const compressed = await gzip(json);
+    if (!compressed)
+        return JSON.stringify(data, null, 2);
+    return `${prefix}:gzip:${bytesToBase64Url(compressed)}`;
+}
+/**
+ * Restores registered buckets from compressed export text or plain JSON.
+ * @param value The exported text to import
+ * @param prefix The namespace used by compressed exports
+ */
+async function importText(value, prefix = 'buckets') {
+    const text = value.trim();
+    const header = `${prefix}:gzip:`;
+    const json = text.startsWith(header)
+        ? await gunzip(base64UrlToBytes(text.slice(header.length)))
+        : text;
+    restore(JSON.parse(json));
+}
+export const persistence = {
+    /**
+     * if true, we've had to fall back to a shim with no persistence
+     */
+    ephemeral: storage instanceof MemoryStorage,
+    dump,
+    reset,
+    restore,
+    prune,
+    exportText,
+    importText,
+};
+//# sourceMappingURL=persistence.js.map

package/dist/persistence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"persistence.js","sourceRoot":"","sources":["../src/persistence.ts"],"names":[],"mappings":"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"}

package/dist/storage.d.ts

@@ -0,0 +1,18 @@
+/**
+ * A in-memory storage backend for when localStorage is not available
+ */
+export declare class MemoryStorage implements Storage {
+    private items;
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+    clear(): void;
+    key(index: number): string | null;
+    get length(): number;
+}
+/**
+ * The active storage backend. This falls back to in-memory storage when
+ * localStorage cannot be accessed.
+ */
+export declare const storage: MemoryStorage | Storage;
+//# sourceMappingURL=storage.d.ts.map

package/dist/storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../src/storage.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,qBAAa,aAAc,YAAW,OAAO;IAC3C,OAAO,CAAC,KAAK,CAA6B;IAE1C,OAAO,CAAC,GAAG,EAAE,MAAM;IAInB,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM;IAIlC,UAAU,CAAC,GAAG,EAAE,MAAM;IAItB,KAAK;IAIL,GAAG,CAAC,KAAK,EAAE,MAAM;IAIjB,IAAI,MAAM,WAET;CACF;AAED;;;GAGG;AACH,eAAO,MAAM,OAAO,yBAMhB,CAAC"}

package/dist/storage.js

@@ -0,0 +1,37 @@
+/**
+ * A in-memory storage backend for when localStorage is not available
+ */
+export class MemoryStorage {
+    items = new Map();
+    getItem(key) {
+        return this.items.get(key) ?? null;
+    }
+    setItem(key, value) {
+        this.items.set(key, value);
+    }
+    removeItem(key) {
+        this.items.delete(key);
+    }
+    clear() {
+        this.items.clear();
+    }
+    key(index) {
+        return [...this.items.keys()][index] ?? null;
+    }
+    get length() {
+        return this.items.size;
+    }
+}
+/**
+ * The active storage backend. This falls back to in-memory storage when
+ * localStorage cannot be accessed.
+ */
+export const storage = (() => {
+    try {
+        return globalThis.localStorage ?? new MemoryStorage();
+    }
+    catch {
+        return new MemoryStorage();
+    }
+})();
+//# sourceMappingURL=storage.js.map

package/dist/storage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.js","sourceRoot":"","sources":["../src/storage.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,OAAO,aAAa;IAChB,KAAK,GAAG,IAAI,GAAG,EAAkB,CAAC;IAE1C,OAAO,CAAC,GAAW;QACjB,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC;IACrC,CAAC;IAED,OAAO,CAAC,GAAW,EAAE,KAAa;QAChC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IAC7B,CAAC;IAED,UAAU,CAAC,GAAW;QACpB,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IACzB,CAAC;IAED,KAAK;QACH,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;IACrB,CAAC;IAED,GAAG,CAAC,KAAa;QACf,OAAO,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,IAAI,IAAI,CAAC;IAC/C,CAAC;IAED,IAAI,MAAM;QACR,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC;IACzB,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG,CAAC,GAAG,EAAE;IAC3B,IAAI,CAAC;QACH,OAAO,UAAU,CAAC,YAAY,IAAI,IAAI,aAAa,EAAE,CAAC;IACxD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,aAAa,EAAE,CAAC;IAC7B,CAAC;AACH,CAAC,CAAC,EAAE,CAAC"}

package/dist/text.d.ts

@@ -0,0 +1,5 @@
+export declare function bytesToBase64Url(bytes: Uint8Array): string;
+export declare function base64UrlToBytes(value: string): Uint8Array<ArrayBuffer>;
+export declare function gzip(value: string): Promise<Uint8Array<ArrayBuffer> | null>;
+export declare function gunzip(bytes: Uint8Array): Promise<string>;
+//# sourceMappingURL=text.d.ts.map

package/dist/text.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"text.d.ts","sourceRoot":"","sources":["../src/text.ts"],"names":[],"mappings":"AAAA,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,UAAU,UAWjD;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,2BAW7C;AAED,wBAAsB,IAAI,CAAC,KAAK,EAAE,MAAM,2CAOvC;AAED,wBAAsB,MAAM,CAAC,KAAK,EAAE,UAAU,mBAS7C"}

package/dist/text.js

@@ -0,0 +1,39 @@
+export function bytesToBase64Url(bytes) {
+    let binary = '';
+    const chunkSize = 0x8000;
+    for (let i = 0; i < bytes.length; i += chunkSize)
+        binary += String.fromCharCode(...bytes.subarray(i, i + chunkSize));
+    return btoa(binary)
+        .replaceAll('+', '-')
+        .replaceAll('/', '_')
+        .replaceAll('=', '');
+}
+export function base64UrlToBytes(value) {
+    const base64 = value
+        .replaceAll('-', '+')
+        .replaceAll('_', '/')
+        .padEnd(Math.ceil(value.length / 4) * 4, '=');
+    const binary = atob(base64);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++)
+        bytes[i] = binary.charCodeAt(i);
+    return bytes;
+}
+export async function gzip(value) {
+    if (typeof CompressionStream === 'undefined')
+        return null;
+    const stream = new Blob([value])
+        .stream()
+        .pipeThrough(new CompressionStream('gzip'));
+    return new Uint8Array(await new Response(stream).arrayBuffer());
+}
+export async function gunzip(bytes) {
+    if (typeof DecompressionStream === 'undefined')
+        throw new Error('Compressed imports are not supported by this browser');
+    const buffer = new Uint8Array(bytes).buffer;
+    const stream = new Blob([buffer])
+        .stream()
+        .pipeThrough(new DecompressionStream('gzip'));
+    return await new Response(stream).text();
+}
+//# sourceMappingURL=text.js.map

package/dist/text.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"text.js","sourceRoot":"","sources":["../src/text.ts"],"names":[],"mappings":"AAAA,MAAM,UAAU,gBAAgB,CAAC,KAAiB;IAChD,IAAI,MAAM,GAAG,EAAE,CAAC;IAChB,MAAM,SAAS,GAAG,MAAM,CAAC;IAEzB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,IAAI,SAAS;QAC9C,MAAM,IAAI,MAAM,CAAC,YAAY,CAAC,GAAG,KAAK,CAAC,QAAQ,CAAC,CAAC,EAAE,CAAC,GAAG,SAAS,CAAC,CAAC,CAAC;IAErE,OAAO,IAAI,CAAC,MAAM,CAAC;SAChB,UAAU,CAAC,GAAG,EAAE,GAAG,CAAC;SACpB,UAAU,CAAC,GAAG,EAAE,GAAG,CAAC;SACpB,UAAU,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;AACzB,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,KAAa;IAC5C,MAAM,MAAM,GAAG,KAAK;SACjB,UAAU,CAAC,GAAG,EAAE,GAAG,CAAC;SACpB,UAAU,CAAC,GAAG,EAAE,GAAG,CAAC;SACpB,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,GAAG,CAAC,EAAE,GAAG,CAAC,CAAC;IAChD,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC;IAC5B,MAAM,KAAK,GAAG,IAAI,UAAU,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAE5C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,EAAE;QAAE,KAAK,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;IAExE,OAAO,KAAK,CAAC;AACf,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,IAAI,CAAC,KAAa;IACtC,IAAI,OAAO,iBAAiB,KAAK,WAAW;QAAE,OAAO,IAAI,CAAC;IAE1D,MAAM,MAAM,GAAG,IAAI,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC;SAC7B,MAAM,EAAE;SACR,WAAW,CAAC,IAAI,iBAAiB,CAAC,MAAM,CAAC,CAAC,CAAC;IAC9C,OAAO,IAAI,UAAU,CAAC,MAAM,IAAI,QAAQ,CAAC,MAAM,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC;AAClE,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,MAAM,CAAC,KAAiB;IAC5C,IAAI,OAAO,mBAAmB,KAAK,WAAW;QAC5C,MAAM,IAAI,KAAK,CAAC,sDAAsD,CAAC,CAAC;IAE1E,MAAM,MAAM,GAAG,IAAI,UAAU,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC;IAC5C,MAAM,MAAM,GAAG,IAAI,IAAI,CAAC,CAAC,MAAM,CAAC,CAAC;SAC9B,MAAM,EAAE;SACR,WAAW,CAAC,IAAI,mBAAmB,CAAC,MAAM,CAAC,CAAC,CAAC;IAChD,OAAO,MAAM,IAAI,QAAQ,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,CAAC;AAC3C,CAAC"}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@delphington/persistent-buckets",
+  "version": "0.1.0",
+  "description": "Versioned localStorage buckets with shared Vue state",
+  "license": "MIT",
+  "author": "Delph",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Delph/persistent-buckets.git"
+  },
+  "homepage": "https://github.com/Delph/persistent-buckets#readme",
+  "keywords": [
+    "localstorage",
+    "persistence",
+    "vue",
+    "typescript"
+  ],
+  "type": "module",
+  "private": false,
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "packageManager": "bun@1.2.12",
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "prepack": "bun run check",
+    "check": "bun run format:check && bun run typecheck && bun run test && bun run build",
+    "format": "prettier . --write",
+    "format:check": "prettier . --check",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "vue": "^3.5.0"
+  },
+  "devDependencies": {
+    "prettier": "^3.9.6",
+    "typescript": "~6.0.2",
+    "vitest": "^4.1.11",
+    "vue": "^3.5.40"
+  }
+}