@nemigo/storage 1.7.2 → 1.8.0

package/dist/capacity.d.ts

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

package/dist/cookie.d.ts

@@ -1,11 +1,16 @@
 import type { ConstructVeilPrefixStorage } from "./internal/veil-prefix.js";
 import { VeilPrefixStorage } from "./internal/veil-prefix.js";
-import type { IStorage, IStorageSetOptions, IStorageValue } from "./types.js";
+import type { IStorage, IStorageValue } from "./types.js";
 import type { SetDocumentCookieOptions } from "@nemigo/helpers/html/cookie";
 /**
  * Опции для {@link CookieStorage.set}
  */
-export interface CookieStorageSetOptions extends SetDocumentCookieOptions, IStorageSetOptions {
+export interface CookieStorageSetOptions extends SetDocumentCookieOptions {
+    /**
+     * - при `undefined` будет использован `ttl_seconds` хранилища
+     * - при `null` хранение будет точно сессионным!
+     */
+    ttl_seconds?: number | null;
     prefix?: string;
 }
 /**
@@ -32,9 +37,6 @@ export declare class CookieStorage extends VeilPrefixStorage implements IStorage
     __unveil<T>(value?: string | null): T | undefined;
     has(name: string): boolean;
     get<T extends IStorageValue>(name: string, prefix?: string): T | undefined;
-    /**
-     * @remarks `options.ttl_seconds === undefined` делает хранение сессионным!
-     */
     set(name: string, value: IStorageValue, options?: CookieStorageSetOptions): void;
     delete(name: string, options?: CookieStorageDeleteOptions): void;
     /**

package/dist/cookie.js

@@ -23,12 +23,11 @@ export class CookieStorage extends VeilPrefixStorage {
         const key = this.__toKey(name, prefix);
         return this.__unveil(isSSR ? this.__server.get(key) : getDocumentCookie(key));
     }
-    /**
-     * @remarks `options.ttl_seconds === undefined` делает хранение сессионным!
-     */
     set(name, value, options = {}) {
-        if (!isSSR)
-            setDocumentCookie(this.__toKey(name, options.prefix), veil(value), { ...options, MaxAge: options.ttl_seconds });
+        if (isSSR)
+            return;
+        const MaxAge = options.ttl_seconds === null ? undefined : (options.ttl_seconds ?? options.ttl_seconds);
+        setDocumentCookie(this.__toKey(name, options.prefix), veil(value), { ...options, MaxAge });
     }
     delete(name, options = {}) {
         if (!isSSR)

package/dist/derived/vault.d.ts

@@ -1,5 +1,5 @@
-import type { IStorage } from "../types.js";
-import type { CanBePromise } from "@nemigo/helpers/types";
+import type { IStorageSetOptions } from "../types.js";
+import type { CanBePromise, Return } from "@nemigo/helpers/types";
 export interface VaultItem<PayloadData> {
     /**
      * Полезная нагрузка
@@ -18,21 +18,65 @@ export interface VaultItem<PayloadData> {
      */
     upd?: number;
 }
+export interface IVaultStorage<PayloadData> {
+    get(key: string): CanBePromise<VaultItem<PayloadData> | undefined>;
+    set(name: string, value: VaultItem<PayloadData>, options?: IStorageSetOptions): CanBePromise;
+}
 export interface VaultTimings {
     /**
-     * Срок действия данных (в секундах). Если не задано — данные не устаревают
+     * Срок действия (дельта) данных в секундах
+     *
+     * - при `undefined` будет использован `exp` экземпляра
+     * - при `null` элементы точно не будут устаревать
+     */
+    exp?: number | null;
+    /**
+     * Минимальный интервал (дельта) до следующего обновления в секундах
+     *
+     * - при `undefined` будет использован `upd` экземпляра
+     * - при `null` обновление точно не разрешено в любой момент
+     */
+    upd?: number | null;
+    /**
+     * TTL (дельта) для хранилища в секундах
+     *
+     * - при `undefined` будет использован `ttl` экземпляра
+     * - при `null` хранилищу будет передан `undefined`
+     */
+    ttl?: number | null;
+}
+export interface InternalVaultTimings {
+    /**
+     * Срок действия (дельта) данных в секундах.
+     * Если не задано — данные не устаревают
      */
     exp?: number;
     /**
-     * Минимальный интервал до следующего обновления (в секундах).
+     * Минимальный интервал (дельта) до следующего обновления в секундах.
      * Если не задано — обновление разрешено в любой момент
      */
     upd?: number;
     /**
-     * TTL в хранилище (в секундах, дельта от текущего момента)
+     * TTL (дельта) для хранилища в секундах
      */
     ttl?: number;
 }
+export interface VaultController<PayloadData> {
+    /**
+     * Функция генерации полезной нагрузки
+     */
+    generate: (timings: InternalVaultTimings, now_seconds: number) => CanBePromise<PayloadData>;
+    /**
+     * Функция сравнения двух полезных нагрузок на эквивалентность
+     */
+    equal: (a: PayloadData, b: PayloadData) => CanBePromise<boolean>;
+}
+export interface ConstructVault<PayloadData> extends InternalVaultTimings, VaultController<PayloadData> {
+}
+export type VaultCanBeUpdateResult<PayloadData> = {
+    item: VaultItem<PayloadData>;
+    ready: boolean;
+} | null;
 export interface VaultRunOptions<PayloadData> extends VaultTimings {
     /**
      * Использовать иные данные вместо генерации
@@ -43,20 +87,27 @@ export interface VaultRunOptions<PayloadData> extends VaultTimings {
      */
     force?: boolean;
 }
-export interface ConstructVault<PayloadData> extends VaultTimings {
-    /**
-     * Функция генерации полезной нагрузки
-     */
-    generate: (delta: VaultTimings, now_seconds: number) => CanBePromise<PayloadData>;
-    /**
-     * Функция сравнения двух полезных нагрузок на эквивалентность
-     */
-    equal: (a: PayloadData, b: PayloadData) => CanBePromise<boolean>;
+export interface VaultRunResult<PayloadData> extends VaultTimings {
+    generated: boolean;
+    item: VaultItem<PayloadData>;
 }
 /**
  * @example
  * ```typescript
- * export const codeVault = new Vault<string, RedisStorage>(redisStorage, {
+ * import { rand } from "@nemigo/helpers/random";
+ * import type { RedisStorage } from "@nemigo/server/redis";
+ * import { Vault } from "@nemigo/storage/derived/vault";
+ *
+ * declare const redisStorage: RedisStorage;
+ *
+ * export const redisCodeVault = new Vault<
+ *  string,
+ *  RedisStorage,
+ *  {
+ *    generate: () => string,
+ *    equal: (a: string, b: string) => boolean,
+ *  }
+ * >(redisStorage, {
  *   generate: () => rand(),
  *   equal: (a, b) => a === b,
  *   exp: 60 * 10,
@@ -64,17 +115,31 @@ export interface ConstructVault<PayloadData> extends VaultTimings {
  *   upd: 60,
  * });
  *
- * const result = await codeVault.run("some:key")
+ * // await redisCodeVault.run("some:key");
  * ```
  */
-export declare class Vault<PayloadData, Storage extends IStorage = IStorage> {
+export declare class Vault<PayloadData, Storage extends IVaultStorage<PayloadData> = IVaultStorage<PayloadData>, Controller extends VaultController<PayloadData> = VaultController<PayloadData>> {
     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;
+    ctx: Controller & InternalVaultTimings;
+    constructor(storage: Storage, ctx: Controller & InternalVaultTimings);
+    timings(options?: VaultTimings): InternalVaultTimings;
+    __isExpired(item: VaultItem<PayloadData>, now_sec: number): boolean;
+    __check(existed: VaultItem<PayloadData> | undefined, pld: PayloadData): Return<Controller["equal"]>;
+    __async_check(existed: Promise<VaultItem<PayloadData> | undefined>, pld: PayloadData): Promise<boolean>;
+    check(key: string, pld: PayloadData): Return<Storage["get"]> extends Promise<any> ? Promise<boolean> : Return<Controller["equal"]>;
+    __isTooEarlyToUpdate(item: VaultItem<PayloadData>, now_sec: number): boolean;
+    __canBeUpdate(existed: VaultItem<PayloadData> | undefined, now_sec: number): VaultCanBeUpdateResult<PayloadData>;
+    __async_canBeUpdate(existed: Promise<VaultItem<PayloadData> | undefined>, now_sec: number): Promise<VaultCanBeUpdateResult<PayloadData>>;
+    canBeUpdate(key: string, now_sec?: number): Return<Storage["set"]> extends Promise<any> ? Promise<VaultCanBeUpdateResult<PayloadData>> : VaultCanBeUpdateResult<PayloadData>;
+    __upsert(key: string, pld: PayloadData, timings: InternalVaultTimings, now_sec: number): {
+        item: VaultItem<PayloadData>;
+        transaction: Return<Storage["set"]>;
+    };
+    __async_upsert(temp: {
         item: VaultItem<PayloadData>;
-    }>;
+        transaction: Return<Storage["set"]>;
+    }): Promise<VaultItem<PayloadData>>;
+    upsert(key: string, pld: PayloadData, timings?: InternalVaultTimings, now_sec?: number): Return<Storage["set"]> extends Promise<any> ? Promise<VaultItem<PayloadData>> : VaultItem<PayloadData>;
+    sync(key: string, options?: VaultRunOptions<PayloadData>): Return<Storage["set"]> extends Promise<any> ? never : Return<Storage["get"]> extends Promise<any> ? never : Return<Controller["generate"]> extends Promise<any> ? never : VaultRunResult<PayloadData>;
+    run(key: string, options?: VaultRunOptions<PayloadData>): Promise<VaultRunResult<PayloadData>>;
 }

package/dist/derived/vault.js

@@ -1,7 +1,23 @@
+import { isPromise } from "@nemigo/helpers";
+import { toSeconds } from "@nemigo/helpers/datetime";
+//...
 /**
  * @example
  * ```typescript
- * export const codeVault = new Vault<string, RedisStorage>(redisStorage, {
+ * import { rand } from "@nemigo/helpers/random";
+ * import type { RedisStorage } from "@nemigo/server/redis";
+ * import { Vault } from "@nemigo/storage/derived/vault";
+ *
+ * declare const redisStorage: RedisStorage;
+ *
+ * export const redisCodeVault = new Vault<
+ *  string,
+ *  RedisStorage,
+ *  {
+ *    generate: () => string,
+ *    equal: (a: string, b: string) => boolean,
+ *  }
+ * >(redisStorage, {
  *   generate: () => rand(),
  *   equal: (a, b) => a === b,
  *   exp: 60 * 10,
@@ -9,7 +25,7 @@
  *   upd: 60,
  * });
  *
- * const result = await codeVault.run("some:key")
+ * // await redisCodeVault.run("some:key");
  * ```
  */
 export class Vault {
@@ -19,37 +35,77 @@ export class Vault {
         this.storage = storage;
         this.ctx = ctx;
     }
-    find(key) {
-        return this.storage.get(key);
+    timings(options = {}) {
+        const ttl = options.ttl === null ? undefined : (options.ttl ?? this.ctx.ttl);
+        const exp = options.exp === null ? undefined : (options.exp ?? this.ctx.exp);
+        const upd = options.upd === null ? undefined : (options.upd ?? this.ctx.upd);
+        return { ttl, exp, upd };
     }
-    async check(key, pld) {
-        const existed = await this.find(key);
-        if (!existed)
+    //...
+    __isExpired(item, now_sec) {
+        return item.exp !== undefined && now_sec > item.exp;
+    }
+    __check(existed, pld) {
+        if (!existed || this.__isExpired(existed, toSeconds()))
             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 };
-            }
-        }
+    async __async_check(existed, pld) {
+        return this.__check(await existed, pld);
+    }
+    check(key, pld) {
+        const existed = this.storage.get(key);
+        return (isPromise(existed) ? this.__async_check(existed, pld) : this.__check(existed, pld));
+    }
+    //...
+    __isTooEarlyToUpdate(item, now_sec) {
+        return item.upd !== undefined && now_sec < item.upd;
+    }
+    __canBeUpdate(existed, now_sec) {
+        return existed ? { ready: !this.__isTooEarlyToUpdate(existed, now_sec), item: existed } : null;
+    }
+    async __async_canBeUpdate(existed, now_sec) {
+        return this.__canBeUpdate(await existed, now_sec);
+    }
+    canBeUpdate(key, now_sec = toSeconds()) {
+        const existed = this.storage.get(key);
+        return (isPromise(existed) ? this.__async_canBeUpdate(existed, now_sec) : this.__canBeUpdate(existed, now_sec));
+    }
+    //...
+    __upsert(key, pld, timings, now_sec) {
         // Вычисляем абсолютные времена для сохранения
-        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 };
+        const Exp = timings.exp !== undefined ? now_sec + timings.exp : undefined;
+        const Upd = timings.upd !== undefined ? now_sec + timings.upd : undefined;
+        const item = { pld, iat: now_sec, exp: Exp, upd: Upd };
+        return { item, transaction: this.storage.set(key, item, { ttl_seconds: timings.ttl }) };
+    }
+    async __async_upsert(temp) {
+        await temp.transaction;
+        return temp.item;
+    }
+    upsert(key, pld, timings = this.timings(), now_sec = toSeconds()) {
+        const temp = this.__upsert(key, pld, timings, now_sec);
+        return (isPromise(temp.transaction) ? this.__async_upsert(temp) : temp.item);
+    }
+    //...
+    sync(key, options = {}) {
+        const { force = false, overload } = options;
+        const timings = this.timings(options);
+        const now_sec = toSeconds();
+        const existed = this.canBeUpdate(key, now_sec);
+        if (existed && !existed.ready && !force)
+            return { generated: false, item: existed.item };
+        const item = this.upsert(key, (overload ?? this.ctx.generate(timings, now_sec)), timings, now_sec);
+        return { generated: true, item };
+    }
+    async run(key, options = {}) {
+        const { force = false, overload } = options;
+        const timings = this.timings(options);
+        const now_sec = toSeconds();
+        const existed = await this.canBeUpdate(key, now_sec);
+        if (existed && !existed.ready && !force)
+            return { generated: false, item: existed.item };
+        const item = await this.upsert(key, overload ?? (await this.ctx.generate(timings, now_sec)), timings, now_sec);
+        return { generated: true, item };
     }
 }

package/dist/internal/veil-prefix.d.ts

@@ -3,9 +3,6 @@ export interface ConstructVeilPrefixStorage {
     ttl_seconds?: number;
 }
 export declare abstract class VeilPrefixStorage {
-    /**
-     * TTL хранилища для быстрого использования
-     */
     ttl_seconds?: number;
     prefix: string;
     constructor({ ttl_seconds, prefix }?: ConstructVeilPrefixStorage);

package/dist/internal/veil-prefix.js

@@ -1,8 +1,5 @@
 import { veil } from "@nemigo/helpers/veil";
 export class VeilPrefixStorage {
-    /**
-     * TTL хранилища для быстрого использования
-     */
     ttl_seconds;
     prefix;
     // noinspection TypeScriptAbstractClassConstructorCanBeMadeProtected

package/dist/runtime.d.ts

@@ -1,20 +1,24 @@
-import type { IStorage, IStorageSetOptions, IStorageValue } from "./types.js";
+import type { IStorage, IStorageValue } from "./types.js";
 import type { Timestamp } from "@nemigo/helpers/types";
 export interface EntryValue {
     value: IStorageValue;
     expired?: Timestamp;
 }
-export declare class RuntimeStorage implements IStorage<boolean> {
-    __storage: Map<string, EntryValue>;
+export interface IRuntimeStorageSetOptions {
     /**
-     * TTL хранилища для быстрого использования
+     * - при `undefined` будет использован `ttl_seconds` хранилища
+     * - при `null` элементы точно не будут устаревать
      */
+    ttl_seconds?: number | null;
+}
+export declare class RuntimeStorage implements IStorage<boolean> {
+    __storage: Map<string, EntryValue>;
     ttl_seconds?: number;
     constructor(ttl_seconds?: number);
     __isExpired(entry: EntryValue): boolean;
     __get(key: string): EntryValue | undefined;
     has(key: string): boolean;
     get<T = any>(key: string): T | undefined;
-    set(key: string, value: any, options?: IStorageSetOptions): void;
+    set(key: string, value: any, options?: IRuntimeStorageSetOptions): void;
     delete(key: string): boolean;
 }

package/dist/runtime.js

@@ -1,8 +1,5 @@
 export class RuntimeStorage {
     __storage;
-    /**
-     * TTL хранилища для быстрого использования
-     */
     ttl_seconds;
     constructor(ttl_seconds) {
         this.__storage = new Map();
@@ -28,8 +25,9 @@ export class RuntimeStorage {
     get(key) {
         return this.__get(key)?.value;
     }
-    set(key, value, options) {
-        this.__storage.set(key, options?.ttl_seconds ? { value, expired: options.ttl_seconds * 1000 } : { value });
+    set(key, value, options = {}) {
+        const ttl_seconds = options.ttl_seconds === null ? undefined : (options.ttl_seconds ?? options.ttl_seconds);
+        this.__storage.set(key, ttl_seconds ? { value, expired: ttl_seconds * 1000 } : { value });
     }
     delete(key) {
         return this.__storage.delete(key);

package/dist/web.d.ts

@@ -1,20 +1,27 @@
 import { VeilPrefixStorage } from "./internal/veil-prefix.js";
-import type { IStorage, IStorageSetOptions, IStorageValue } from "./types.js";
+import type { IStorage, IStorageValue } from "./types.js";
 import type { Timestamp } from "@nemigo/helpers/types";
 export type WebStorageType = "local" | "session";
 export interface WebStorageOptions {
     type?: WebStorageType;
     prefix?: string;
 }
+export interface IWebStorageSetOptions extends WebStorageOptions {
+    /**
+     * - при `undefined` будет использован `ttl_seconds` хранилища
+     * - при `null` элементы точно не будут устаревать
+     */
+    ttl_seconds?: number | null;
+}
 export interface EntryValue {
     value: IStorageValue;
     expired?: Timestamp;
 }
 export declare class WebStorage extends VeilPrefixStorage implements IStorage<void> {
-    __isExpired(entry: EntryValue): boolean;
+    __isExpired(entry: EntryValue, now: number): 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?: IStorageSetOptions & WebStorageOptions): void;
+    set(name: string, value: IStorageValue, options?: IWebStorageSetOptions): void;
     delete(name: string, options?: WebStorageOptions): void;
 }

package/dist/web.js

@@ -2,15 +2,15 @@ import { VeilPrefixStorage } from "./internal/veil-prefix.js";
 import { isSSR } from "@nemigo/helpers/html";
 import { unveil, veil } from "@nemigo/helpers/veil";
 export class WebStorage extends VeilPrefixStorage {
-    __isExpired(entry) {
-        return Boolean(entry.expired && Date.now() > entry.expired);
+    __isExpired(entry, now) {
+        return entry.expired !== undefined && now > entry.expired;
     }
     __get(storage, key) {
         const entry = storage.getItem(key);
         if (!entry)
             return;
         const unveiled = unveil(entry);
-        if (this.__isExpired(unveiled)) {
+        if (this.__isExpired(unveiled, Date.now())) {
             storage.removeItem(key);
         }
         else {
@@ -37,7 +37,8 @@ export class WebStorage extends VeilPrefixStorage {
         if (isSSR)
             return;
         const key = this.__toKey(name, options.prefix);
-        const veiled = veil(options.ttl_seconds ? { value, expired: options.ttl_seconds * 1000 } : { value });
+        const ttl_seconds = options.ttl_seconds === null ? undefined : (options.ttl_seconds ?? options.ttl_seconds);
+        const veiled = veil(ttl_seconds ? { value, expired: ttl_seconds * 1000 } : { value });
         if (options.type === "session")
             sessionStorage.setItem(key, veiled);
         else

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nemigo/storage",
-	"version": "1.7.2",
+	"version": "1.8.0",
 	"private": false,
 	"author": {
 		"name": "Vlad Logvin",
@@ -48,7 +48,7 @@
 		}
 	},
 	"peerDependencies": {
-		"@nemigo/helpers": ">=1.6.0"
+		"@nemigo/helpers": ">=1.6.2"
 	},
 	"devDependencies": {
 		"@nemigo/configs": "workspace:*",