@nemigo/storage 1.5.0

package/dist/cookie.d.ts

@@ -0,0 +1,50 @@
+import { VeilPrefixStorage } from "./internal/veil.js";
+import type { IStorage, IStorageValue, SetIStorageOptions } from "./types.js";
+import type { SetDocumentCookieOptions } from "@nemigo/helpers/html/cookie";
+/**
+ * Серверные readonly-куки для {@link CookieStorage}
+ */
+export interface ServerCookie {
+    name: string;
+    value: string;
+}
+/**
+ * Опции для {@link CookieStorage.set}
+ */
+export interface SetCookieStorageOptions extends SetDocumentCookieOptions, SetIStorageOptions {
+    prefix?: string;
+}
+/**
+ * Опции для {@link CookieStorage.delete}
+ */
+export interface DeleteCookieStorageOptions {
+    Path?: string;
+    prefix?: string;
+}
+export declare class CookieStorage extends VeilPrefixStorage implements IStorage {
+    __server: Map<string, string>;
+    /**
+     * TTL (time-to-live) хранилища
+     */
+    ttl_seconds?: number | null;
+    /**
+     * @remarks `options.ttl_seconds === null` делает хранение сессионным!
+     */
+    constructor({ cookies, prefix, ttl_seconds }: {
+        cookies?: ServerCookie[];
+        prefix?: string;
+        ttl_seconds?: number | null;
+    });
+    fill(cookies?: ServerCookie[]): void;
+    __unveil<T>(value?: string | null): T | undefined;
+    get<T extends IStorageValue>(name: string, prefix?: string): T | undefined;
+    /**
+     * @remarks `options.ttl_seconds === null` делает хранение сессионным!
+     */
+    set(name: string, value: IStorageValue, options?: SetCookieStorageOptions): void;
+    delete(name: string, options?: DeleteCookieStorageOptions): void;
+    /**
+     * Очистка серверных кук
+     */
+    destroy(): void;
+}

package/dist/cookie.js

@@ -0,0 +1,51 @@
+import { VeilPrefixStorage } from "./internal/veil.js";
+import { isSSR } from "@nemigo/helpers/html";
+import { deleteDocumentCookie, getDocumentCookie, setDocumentCookie } from "@nemigo/helpers/html/cookie";
+import { unveil, veil } from "@nemigo/helpers/veil";
+export class CookieStorage extends VeilPrefixStorage {
+    __server = new Map();
+    /**
+     * TTL (time-to-live) хранилища
+     */
+    ttl_seconds;
+    /**
+     * @remarks `options.ttl_seconds === null` делает хранение сессионным!
+     */
+    constructor({ cookies, prefix, ttl_seconds }) {
+        super(prefix);
+        this.fill(cookies);
+        this.ttl_seconds = ttl_seconds;
+    }
+    fill(cookies = []) {
+        for (const item of cookies)
+            this.__server.set(item.name, item.value);
+    }
+    //...
+    __unveil(value) {
+        return value ? unveil(value) : undefined;
+    }
+    get(name, prefix) {
+        const key = this.__toKey(name, prefix);
+        return this.__unveil(isSSR ? this.__server.get(key) : getDocumentCookie(key));
+    }
+    //...
+    /**
+     * @remarks `options.ttl_seconds === null` делает хранение сессионным!
+     */
+    set(name, value, options = {}) {
+        if (isSSR)
+            return;
+        const MaxAge = options.ttl_seconds !== undefined ? options.ttl_seconds : this.ttl_seconds;
+        setDocumentCookie(this.__toKey(name, options.prefix), veil(value), { ...options, MaxAge });
+    }
+    delete(name, options = {}) {
+        if (!isSSR)
+            deleteDocumentCookie(this.__toKey(name, options.prefix), options.Path);
+    }
+    /**
+     * Очистка серверных кук
+     */
+    destroy() {
+        this.__server.clear();
+    }
+}

package/dist/internal/index.d.ts

@@ -0,0 +1 @@
+export declare const getTTL: (entry_in_seconds?: number | null, storage?: number | null) => number | null | undefined;

package/dist/internal/index.js

@@ -0,0 +1,10 @@
+export const getTTL = (entry_in_seconds, storage) => {
+    if (entry_in_seconds)
+        return Date.now() + entry_in_seconds * 1000;
+    if (entry_in_seconds === null)
+        return null;
+    if (storage)
+        return Date.now() + storage;
+    if (storage === null)
+        return null;
+};

package/dist/internal/veil.d.ts

@@ -0,0 +1,5 @@
+export declare abstract class VeilPrefixStorage {
+    prefix: string;
+    protected constructor(prefix?: string);
+    __toKey(name: string, prefix: string | undefined): string;
+}

package/dist/internal/veil.js

@@ -0,0 +1,10 @@
+import { veil } from "@nemigo/helpers/veil";
+export class VeilPrefixStorage {
+    prefix;
+    constructor(prefix = "") {
+        this.prefix = prefix;
+    }
+    __toKey(name, prefix) {
+        return (prefix === undefined ? this.prefix : prefix) + veil(name);
+    }
+}

package/dist/runtime.d.ts

@@ -0,0 +1,59 @@
+import type { IStorage, IStorageValue, SetIStorageOptions } from "./types.js";
+import type { Timestamp } from "@nemigo/helpers/types";
+interface InternalValue {
+    value: IStorageValue;
+    expired?: Timestamp;
+}
+/**
+ * LRU (Least Recently Used) runtime-хранилище данных, имплементирующее интерфейс {@link IStorage}
+ *
+ * - Значения удаляются при превышении максимального размера или по истечении заданного TTL
+ * - TTL для каждого значения используется из хранилища (если задано), но можно указать и индивидуальное
+ *
+ * @example
+ * ```typescript
+ * const storage = new RuntimeStorage({ max: 2, ttl_minutes: 5 });
+ * storage.set('one', 1);
+ * storage.set('two', 2);
+ * storage.set('three', 3); // Если хранилище переполнено, удалится наименее недавно использованное или устаревшее значение
+ * console.log(storage.get('one')); // undefined, если значение устарело или удалено
+ * console.log(storage.get('two')); // 2
+ * ```
+ */
+export declare class RuntimeStorage implements IStorage {
+    __storage: Map<string, InternalValue>;
+    /**
+     * Максимальное количество значений в хранилище
+     */
+    max: number;
+    /**
+     * TTL (time-to-live) хранилища в миллисекундах
+     */
+    ttl?: number | null;
+    /**
+     * @param options - Настройки хранилища
+     * @param [options.max=200] - Максимальное количество значений в хранилище
+     * @param [options.ttl_seconds] - TTL (time-to-live) хранилища в **секундах**
+     */
+    constructor({ max, ttl_seconds }?: {
+        max?: number;
+        ttl_seconds?: number | null;
+    });
+    __isExpired(entry: InternalValue): boolean;
+    get<T = any>(key: string): T | undefined;
+    /**
+     * Устанавливает значение в кэш
+     *
+     * - Если индивидуальный TTL в **секундах** не указан, используется TTL хранилища (если задано)
+     * - Если ключ уже существует, его значение обновляется и перемещается в конец
+     * - Если размер хранимых значений превышает максимальное значение, производится очистка устаревших
+     * - Если после очистки хранилище всё ещё переполнено, удаляется наименее недавно использованное значение
+     */
+    set(key: string, value: any, options?: SetIStorageOptions): void;
+    size(): number;
+    shake(): void;
+    delete(key: string): boolean;
+    clear(): void;
+    has(key: string): boolean;
+}
+export {};

package/dist/runtime.js

@@ -0,0 +1,116 @@
+import { getTTL } from "./internal/index.js";
+/**
+ * LRU (Least Recently Used) runtime-хранилище данных, имплементирующее интерфейс {@link IStorage}
+ *
+ * - Значения удаляются при превышении максимального размера или по истечении заданного TTL
+ * - TTL для каждого значения используется из хранилища (если задано), но можно указать и индивидуальное
+ *
+ * @example
+ * ```typescript
+ * const storage = new RuntimeStorage({ max: 2, ttl_minutes: 5 });
+ * storage.set('one', 1);
+ * storage.set('two', 2);
+ * storage.set('three', 3); // Если хранилище переполнено, удалится наименее недавно использованное или устаревшее значение
+ * console.log(storage.get('one')); // undefined, если значение устарело или удалено
+ * console.log(storage.get('two')); // 2
+ * ```
+ */
+export class RuntimeStorage {
+    __storage;
+    /**
+     * Максимальное количество значений в хранилище
+     */
+    max;
+    /**
+     * TTL (time-to-live) хранилища в миллисекундах
+     */
+    ttl;
+    /**
+     * @param options - Настройки хранилища
+     * @param [options.max=200] - Максимальное количество значений в хранилище
+     * @param [options.ttl_seconds] - TTL (time-to-live) хранилища в **секундах**
+     */
+    constructor({ max = 200, ttl_seconds } = {}) {
+        this.max = max;
+        this.ttl = ttl_seconds ? ttl_seconds * 1000 : ttl_seconds;
+        this.__storage = new Map();
+    }
+    __isExpired(entry) {
+        return Boolean(entry.expired && Date.now() > entry.expired);
+    }
+    get(key) {
+        const entry = this.__storage.get(key);
+        if (!entry)
+            return undefined;
+        if (this.__isExpired(entry)) {
+            this.__storage.delete(key);
+            return undefined;
+        }
+        // Обновляем порядок использования, чтобы сохранить от LRU-удаления
+        this.__storage.delete(key);
+        this.__storage.set(key, entry);
+        return entry.value;
+    }
+    /**
+     * Устанавливает значение в кэш
+     *
+     * - Если индивидуальный TTL в **секундах** не указан, используется TTL хранилища (если задано)
+     * - Если ключ уже существует, его значение обновляется и перемещается в конец
+     * - Если размер хранимых значений превышает максимальное значение, производится очистка устаревших
+     * - Если после очистки хранилище всё ещё переполнено, удаляется наименее недавно использованное значение
+     */
+    set(key, value, options) {
+        if (this.__storage.has(key)) {
+            this.__storage.delete(key);
+        }
+        else {
+            if (this.__storage.size >= this.max) {
+                // Удаляем устаревшие элементы
+                for (const existingKey of this.__storage.keys()) {
+                    const entry = this.__storage.get(existingKey);
+                    if (!entry || this.__isExpired(entry)) {
+                        this.__storage.delete(existingKey);
+                    }
+                    if (this.__storage.size < this.max)
+                        break;
+                }
+                // Если всё ещё переполнен — удаляем LRU
+                if (this.__storage.size >= this.max) {
+                    const firstKey = this.__storage.keys().next().value;
+                    if (firstKey !== undefined) {
+                        this.__storage.delete(firstKey);
+                    }
+                }
+            }
+        }
+        const expired = getTTL(options?.ttl_seconds, this.ttl);
+        this.__storage.set(key, expired ? { value, expired } : { value });
+    }
+    size() {
+        return this.__storage.size;
+    }
+    shake() {
+        for (const existingKey of this.__storage.keys()) {
+            const entry = this.__storage.get(existingKey);
+            if (!entry || this.__isExpired(entry)) {
+                this.__storage.delete(existingKey);
+            }
+        }
+    }
+    delete(key) {
+        return this.__storage.delete(key);
+    }
+    clear() {
+        this.__storage.clear();
+    }
+    has(key) {
+        const entry = this.__storage.get(key);
+        if (!entry)
+            return false;
+        if (this.__isExpired(entry)) {
+            this.__storage.delete(key);
+            return false;
+        }
+        return true;
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,38 @@
+import type { CanBePromise } from "@nemigo/helpers/types";
+/**
+ * Тип значений, которые могут жить в {@link IStorage}
+ */
+export type IStorageValue = object | string | boolean | number | null;
+/**
+ * Опции для {@link IStorage.set}
+ */
+export interface SetIStorageOptions {
+    /**
+     * @remarks `null` поведение может отличаться у разных имплементаций!
+     */
+    ttl_seconds?: number | null;
+}
+/**
+ * Интерфейс для синхронных хранилищ данных для полиморфизма
+ *
+ * Используется только там, где нельзя использовать {@link IStorage}
+ */
+export interface ISyncStorage {
+    get<T extends IStorageValue>(key: string): T | undefined;
+    set(key: string, value: IStorageValue, options?: SetIStorageOptions): void;
+    /**
+     * @return `true`, если оно существовало. Допускаются имплементации без проверки
+     */
+    delete(key: string): boolean | void;
+}
+/**
+ * Интерфейс для всех хранилищ данных для полиморфизма
+ */
+export interface IStorage {
+    get<T extends IStorageValue>(key: string): CanBePromise<T | undefined>;
+    set(key: string, value: IStorageValue, options?: SetIStorageOptions): CanBePromise;
+    /**
+     * @return `true`, если оно существовало. Допускаются имплементации без проверки
+     */
+    delete(key: string): CanBePromise<boolean | void>;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/web.d.ts

@@ -0,0 +1,28 @@
+import { VeilPrefixStorage } from "./internal/veil.js";
+import type { IStorage, IStorageValue, SetIStorageOptions } from "./types.js";
+export type WebStorageType = "local" | "session";
+export interface WebStorageOptions {
+    type?: WebStorageType;
+    prefix?: string;
+}
+export declare class WebStorage extends VeilPrefixStorage implements IStorage {
+    /**
+     * TTL (time-to-live) хранилища в миллисекундах
+     */
+    ttl?: number | null;
+    /**
+     * @param options - Настройки хранилища
+     * @param [options.ttl_seconds] - TTL (time-to-live) хранилища в **секундах**
+     */
+    constructor({ ttl_seconds, prefix }?: {
+        prefix?: string;
+        ttl_seconds?: number | null;
+    });
+    __get<T>(storage: Storage, key: string): T | undefined;
+    get<T extends IStorageValue>(name: string, options?: WebStorageOptions): T | undefined;
+    set(name: string, value: IStorageValue, options?: SetIStorageOptions & WebStorageOptions): void;
+    delete(name: string, options?: {
+        type?: WebStorageType;
+        prefix?: string;
+    }): boolean | void;
+}

package/dist/web.js

@@ -0,0 +1,64 @@
+import { getTTL } from "./internal/index.js";
+import { VeilPrefixStorage } from "./internal/veil.js";
+import { isSSR } from "@nemigo/helpers/html";
+import { unveil, veil } from "@nemigo/helpers/veil";
+export class WebStorage extends VeilPrefixStorage {
+    /**
+     * TTL (time-to-live) хранилища в миллисекундах
+     */
+    ttl;
+    /**
+     * @param options - Настройки хранилища
+     * @param [options.ttl_seconds] - TTL (time-to-live) хранилища в **секундах**
+     */
+    constructor({ ttl_seconds, prefix } = {}) {
+        super(prefix);
+        this.ttl = ttl_seconds ? ttl_seconds * 1000 : ttl_seconds;
+    }
+    __get(storage, key) {
+        const entry = storage.getItem(key);
+        if (!entry)
+            return;
+        const encoded = unveil(entry);
+        if (encoded.expired && Date.now() > encoded.expired) {
+            storage.removeItem(key);
+        }
+        else {
+            return encoded.value;
+        }
+    }
+    get(name, options = {}) {
+        if (isSSR)
+            return;
+        const key = this.__toKey(name, options.prefix);
+        if (options.type !== "session") {
+            const value = this.__get(localStorage, key);
+            if (value)
+                return value;
+        }
+        if (options.type !== "local") {
+            return this.__get(sessionStorage, key);
+        }
+    }
+    set(name, value, options = {}) {
+        if (isSSR)
+            return;
+        const key = this.__toKey(name, options.prefix);
+        const expired = getTTL(options.ttl_seconds, this.ttl);
+        const internalValue = expired ? { value, expired } : { value };
+        const _value = veil(internalValue);
+        if (options.type === "session")
+            sessionStorage.setItem(key, _value);
+        else
+            localStorage.setItem(key, _value);
+    }
+    delete(name, options = {}) {
+        if (isSSR)
+            return;
+        const key = this.__toKey(name, options.prefix);
+        if (options.type !== "session")
+            localStorage.removeItem(key);
+        if (options.type !== "local")
+            sessionStorage.removeItem(key);
+    }
+}

package/package.json

@@ -0,0 +1,53 @@
+{
+	"name": "@nemigo/storage",
+	"version": "1.5.0",
+	"private": false,
+	"author": {
+		"name": "Vlad Logvin",
+		"email": "vlad.logvin84@gmail.com"
+	},
+	"type": "module",
+	"engines": {
+		"node": ">=22",
+		"pnpm": ">=10.9.0"
+	},
+	"scripts": {
+		"build": "svelte-package && rimraf .svelte-kit",
+		"check": "tsc --noemit",
+		"lint": "eslint ./",
+		"format": "prettier --write ./"
+	},
+	"exports": {
+		"./cookie": {
+			"types": "./dist/cookie.d.ts",
+			"default": "./dist/cookie.js"
+		},
+		"./internal": {
+			"types": "./dist/internal/index.d.ts",
+			"default": "./dist/internal/index.js"
+		},
+		"./internal/veil": {
+			"types": "./dist/internal/veil.d.ts",
+			"default": "./dist/internal/veil.js"
+		},
+		"./runtime": {
+			"types": "./dist/runtime.d.ts",
+			"default": "./dist/runtime.js"
+		},
+		"./types": {
+			"types": "./dist/types.d.ts",
+			"default": "./dist/types.js"
+		},
+		"./web": {
+			"types": "./dist/web.d.ts",
+			"default": "./dist/web.js"
+		}
+	},
+	"peerDependencies": {
+		"@nemigo/helpers": ">=1.5.0"
+	},
+	"devDependencies": {
+		"@nemigo/configs": "workspace:*",
+		"@nemigo/helpers": "workspace:*"
+	}
+}