@nemigo/storage 1.6.0 → 1.7.1

package/dist/capacity.d.ts

@@ -1,12 +1,12 @@
 import { RuntimeStorage } from "./runtime.js";
-import type { SetIStorageOptions } from "./types.js";
-export interface ConstructorCapacityStorage {
+import type { IStorageSetOptions } from "./types.js";
+export interface ConstructCapacityStorage {
     capacity: number;
     ttl_seconds?: number;
 }
 export declare class CapacityStorage extends RuntimeStorage {
     capacity: number;
-    constructor({ capacity, ttl_seconds }: ConstructorCapacityStorage);
+    constructor({ capacity, ttl_seconds }: ConstructCapacityStorage);
     get<T = any>(key: string): T | undefined;
-    set(key: string, value: any, options?: SetIStorageOptions): void;
+    set(key: string, value: any, options?: IStorageSetOptions): void;
 }

package/dist/cookie.d.ts

@@ -1,17 +1,17 @@
 import type { ConstructVeilPrefixStorage } from "./internal/veil-prefix.js";
 import { VeilPrefixStorage } from "./internal/veil-prefix.js";
-import type { IStorage, IStorageValue, SetIStorageOptions } from "./types.js";
+import type { IStorage, IStorageValue, IStorageSetOptions } from "./types.js";
 import type { SetDocumentCookieOptions } from "@nemigo/helpers/html/cookie";
 /**
  * Опции для {@link CookieStorage.set}
  */
-export interface SetCookieStorageOptions extends SetDocumentCookieOptions, SetIStorageOptions {
+export interface CookieStorageSetOptions extends SetDocumentCookieOptions, IStorageSetOptions {
     prefix?: string;
 }
 /**
  * Опции для {@link CookieStorage.delete}
  */
-export interface DeleteCookieStorageOptions {
+export interface CookieStorageDeleteOptions {
     Path?: string;
     prefix?: string;
 }
@@ -25,7 +25,7 @@ export interface ServerCookie {
 export interface ConstructCookieStorage extends ConstructVeilPrefixStorage {
     cookies?: ServerCookie[];
 }
-export declare class CookieStorage extends VeilPrefixStorage implements IStorage {
+export declare class CookieStorage extends VeilPrefixStorage implements IStorage<void> {
     __server: Map<string, string>;
     constructor(ctx?: ConstructCookieStorage);
     fill(cookies?: ServerCookie[]): void;
@@ -35,8 +35,8 @@ export declare class CookieStorage extends VeilPrefixStorage implements IStorage
     /**
      * @remarks `options.ttl_seconds === undefined` делает хранение сессионным!
      */
-    set(name: string, value: IStorageValue, options?: SetCookieStorageOptions): void;
-    delete(name: string, options?: DeleteCookieStorageOptions): void;
+    set(name: string, value: IStorageValue, options?: CookieStorageSetOptions): void;
+    delete(name: string, options?: CookieStorageDeleteOptions): void;
     /**
      * Очистка серверных кук
      */

package/dist/derived/vault.d.ts

@@ -0,0 +1,80 @@
+import type { CanBePromise } from "@nemigo/helpers/types";
+import type { IStorage } from "@nemigo/storage/types";
+export interface VaultItem<PayloadData> {
+    /**
+     * Полезная нагрузка
+     */
+    pld: PayloadData;
+    /**
+     * Время создания (timestamp в секундах)
+     */
+    iat: number;
+    /**
+     * Абсолютное время истечения (timestamp в секундах). Если не задано — не устаревает
+     */
+    exp?: number;
+    /**
+     * Абсолютное время, до которого нельзя обновлять (timestamp в секундах)
+     */
+    upd?: number;
+}
+export interface VaultTimings {
+    /**
+     * Срок действия данных (в секундах). Если не задано — данные не устаревают
+     */
+    exp?: number;
+    /**
+     * Минимальный интервал до следующего обновления (в секундах).
+     * Если не задано — обновление разрешено в любой момент
+     */
+    upd?: number;
+    /**
+     * TTL в хранилище (в секундах, дельта от текущего момента)
+     */
+    ttl?: number;
+}
+export interface VaultRunOptions<PayloadData> extends VaultTimings {
+    /**
+     * Использовать иные данные вместо генерации
+     */
+    overload?: PayloadData;
+    /**
+     * Принудительно перегенерировать, игнорируя тайминги
+     */
+    force?: boolean;
+}
+export interface ConstructVault<PayloadData> extends VaultTimings {
+    /**
+     * Функция генерации полезной нагрузки
+     */
+    generate: (delta: VaultTimings, now_seconds: number) => CanBePromise<PayloadData>;
+    /**
+     * Функция сравнения двух полезных нагрузок на эквивалентность
+     */
+    equal: (a: PayloadData, b: PayloadData) => CanBePromise<boolean>;
+}
+/**
+ * @example
+ * ```typescript
+ * export const codeVault = new Vault<string, RedisStorage>(redisStorage, {
+ *   generate: () => rand(),
+ *   equal: (a, b) => a === b,
+ *   exp: 60 * 10,
+ *   ttl: 60 * 10,
+ *   upd: 60,
+ * });
+ *
+ * const result = await codeVault.run("some:key")
+ * ```
+ */
+export declare class Vault<PayloadData, Storage extends IStorage = IStorage> {
+    storage: Storage;
+    ctx: ConstructVault<PayloadData>;
+    constructor(storage: Storage, ctx: ConstructVault<PayloadData>);
+    find(key: string): CanBePromise<VaultItem<PayloadData> | undefined>;
+    check(key: string, pld: PayloadData): Promise<boolean>;
+    run(key: string, options?: VaultRunOptions<PayloadData>): Promise<{
+        generate: boolean;
+        item: VaultItem<PayloadData>;
+    }>;
+}

package/dist/derived/vault.js

@@ -0,0 +1,55 @@
+/**
+ * @example
+ * ```typescript
+ * export const codeVault = new Vault<string, RedisStorage>(redisStorage, {
+ *   generate: () => rand(),
+ *   equal: (a, b) => a === b,
+ *   exp: 60 * 10,
+ *   ttl: 60 * 10,
+ *   upd: 60,
+ * });
+ *
+ * const result = await codeVault.run("some:key")
+ * ```
+ */
+export class Vault {
+    storage;
+    ctx;
+    constructor(storage, ctx) {
+        this.storage = storage;
+        this.ctx = ctx;
+    }
+    find(key) {
+        return this.storage.get(key);
+    }
+    async check(key, pld) {
+        const existed = await this.find(key);
+        if (!existed)
+            return false;
+        return this.ctx.equal(existed.pld, pld);
+    }
+    async run(key, options = {}) {
+        const { ttl = this.ctx.ttl, exp = this.ctx.exp, upd = this.ctx.upd, force = false, overload } = options;
+        // работаем в секундах
+        const nowSec = Math.floor(Date.now() / 1000);
+        const existed = await this.find(key);
+        if (existed && !force) {
+            const expired = existed.exp !== undefined && nowSec > existed.exp;
+            const tooEarlyToUpdate = existed.upd !== undefined && nowSec < existed.upd;
+            if (!expired && !tooEarlyToUpdate) {
+                return { generate: false, item: existed };
+            }
+        }
+        // Вычисляем абсолютные времена для сохранения
+        const newExp = exp !== undefined ? nowSec + exp : undefined;
+        const newUpd = upd !== undefined ? nowSec + upd : undefined;
+        const item = {
+            pld: overload ?? (await this.ctx.generate({ exp, upd }, nowSec)),
+            iat: nowSec,
+            exp: newExp,
+            upd: newUpd,
+        };
+        await this.storage.set(key, item, { ttl_seconds: ttl });
+        return { generate: true, item };
+    }
+}

package/dist/runtime.d.ts

@@ -1,10 +1,10 @@
-import type { IStorage, IStorageValue, SetIStorageOptions } from "./types.js";
+import type { IStorage, IStorageValue, IStorageSetOptions } from "./types.js";
 import type { Timestamp } from "@nemigo/helpers/types";
 export interface EntryValue {
     value: IStorageValue;
     expired?: Timestamp;
 }
-export declare class RuntimeStorage implements IStorage {
+export declare class RuntimeStorage implements IStorage<boolean> {
     __storage: Map<string, EntryValue>;
     /**
      * TTL хранилища для быстрого использования
@@ -15,6 +15,6 @@ export declare class RuntimeStorage implements IStorage {
     __get(key: string): EntryValue | undefined;
     has(key: string): boolean;
     get<T = any>(key: string): T | undefined;
-    set(key: string, value: any, options?: SetIStorageOptions): void;
+    set(key: string, value: any, options?: IStorageSetOptions): void;
     delete(key: string): boolean;
 }

package/dist/types.d.ts

@@ -6,7 +6,7 @@ export type IStorageValue = object | string | boolean | number | null;
 /**
  * Опции для {@link IStorage.set}
  */
-export interface SetIStorageOptions {
+export interface IStorageSetOptions {
     /**
      * @remarks `undefined` поведение может быть особым у разных имплементаций!
      */
@@ -17,13 +17,13 @@ export interface SetIStorageOptions {
  *
  * Используется только там, где нельзя использовать {@link IStorage}
  */
-export interface ISyncStorage {
+export interface ISyncStorage<Delete extends boolean | void = boolean | void> {
     get<T extends IStorageValue>(name: string): T | undefined;
-    set(name: string, value: IStorageValue, options?: SetIStorageOptions): void;
+    set(name: string, value: IStorageValue, options?: IStorageSetOptions): void;
     /**
-     * @return `true`, если оно существовало. Допускаются имплементации без проверки
+     * @return `true`, если оно существовало. Допускаются имплементации без этого
      */
-    delete(name: string): boolean | void;
+    delete(name: string): Delete;
     /**
      * Обычно просто `Boolean(this.get(name))`, но могут быть более производительные способы
      */
@@ -32,15 +32,27 @@ export interface ISyncStorage {
 /**
  * Интерфейс для всех хранилищ данных для полиморфизма
  */
-export interface IStorage {
+export interface IStorage<Delete extends boolean | void = boolean | void> {
     get<T extends IStorageValue>(name: string): CanBePromise<T | undefined>;
-    set(name: string, value: IStorageValue, options?: SetIStorageOptions): CanBePromise;
+    set(name: string, value: IStorageValue, options?: IStorageSetOptions): CanBePromise;
     /**
-     * @return `true`, если оно существовало. Допускаются имплементации без проверки
+     * @return `true`, если оно существовало. Допускаются имплементации без этого
      */
-    delete(name: string): CanBePromise<boolean | void>;
+    delete(name: string): CanBePromise<Delete>;
     /**
      * Обычно просто `Boolean(this.get(name))`, но могут быть более производительные способы
      */
     has(name: string): CanBePromise<boolean>;
 }
+export interface ISyncStoragePanic<Delete extends boolean | void = boolean | void> {
+    onhas?(err: unknown): boolean | never;
+    onget?<V extends IStorageValue = IStorageValue>(err: unknown): V | undefined | never;
+    ondelete?(err: unknown): Delete | never;
+    onset?(err: unknown): undefined | never;
+}
+export interface IStoragePanic<Delete extends boolean | void = boolean | void> {
+    onhas?(err: unknown): CanBePromise<boolean | never>;
+    onget?<V extends IStorageValue = IStorageValue>(err: unknown): CanBePromise<V | undefined | never>;
+    ondelete?(err: unknown): CanBePromise<Delete | never>;
+    onset?(err: unknown): CanBePromise<undefined | never>;
+}

package/dist/web.d.ts

@@ -1,5 +1,5 @@
 import { VeilPrefixStorage } from "./internal/veil-prefix.js";
-import type { IStorage, IStorageValue, SetIStorageOptions } from "./types.js";
+import type { IStorage, IStorageValue, IStorageSetOptions } from "./types.js";
 import type { Timestamp } from "@nemigo/helpers/types";
 export type WebStorageType = "local" | "session";
 export interface WebStorageOptions {
@@ -10,11 +10,11 @@ export interface EntryValue {
     value: IStorageValue;
     expired?: Timestamp;
 }
-export declare class WebStorage extends VeilPrefixStorage implements IStorage {
+export declare class WebStorage extends VeilPrefixStorage implements IStorage<void> {
     __isExpired(entry: EntryValue): boolean;
     __get<T>(storage: Storage, key: string): T | undefined;
     has(name: string, options?: WebStorageOptions): boolean;
     get<T extends IStorageValue>(name: string, options?: WebStorageOptions): T | undefined;
-    set(name: string, value: IStorageValue, options?: SetIStorageOptions & WebStorageOptions): void;
-    delete(name: string, options?: WebStorageOptions): boolean | void;
+    set(name: string, value: IStorageValue, options?: IStorageSetOptions & WebStorageOptions): void;
+    delete(name: string, options?: WebStorageOptions): void;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nemigo/storage",
-	"version": "1.6.0",
+	"version": "1.7.1",
 	"private": false,
 	"author": {
 		"name": "Vlad Logvin",
@@ -26,6 +26,10 @@
 			"types": "./dist/cookie.d.ts",
 			"default": "./dist/cookie.js"
 		},
+		"./derived/vault": {
+			"types": "./dist/derived/vault.d.ts",
+			"default": "./dist/derived/vault.js"
+		},
 		"./internal/veil-prefix": {
 			"types": "./dist/internal/veil-prefix.d.ts",
 			"default": "./dist/internal/veil-prefix.js"