@daiso-tech/core 0.21.1 → 0.22.1

package/dist/types/lock/contracts/lock.events.d.ts

@@ -0,0 +1,83 @@
+/**
+ * @module Lock
+ */
+import { BaseEvent } from "../../event-bus/contracts/_module";
+import type { IFlexibleSerde } from "../../serde/contracts/_module";
+import type { OneOrMore } from "../../utilities/types";
+import type { TimeSpan } from "../../utilities/_module";
+/**
+ * @group Events
+ */
+export declare class KeyAcquiredLockEvent extends BaseEvent<{
+    key: string;
+    owner: string;
+    ttl: TimeSpan | null;
+}> {
+}
+/**
+ * @group Events
+ */
+export declare class KeyReleasedLockEvent extends BaseEvent<{
+    key: string;
+    owner: string;
+}> {
+}
+/**
+ * @group Events
+ */
+export declare class KeyForceReleasedLockEvent extends BaseEvent<{
+    key: string;
+}> {
+}
+/**
+ * @group Events
+ */
+export declare class UnownedReleaseLockEvent extends BaseEvent<{
+    key: string;
+    owner: string;
+}> {
+}
+/**
+ * @group Events
+ */
+export declare class UnownedRefreshLockEvent extends BaseEvent<{
+    key: string;
+    owner: string;
+}> {
+}
+/**
+ * @group Events
+ */
+export declare class KeyAlreadyAcquiredLockEvent extends BaseEvent<{
+    key: string;
+    owner: string;
+}> {
+}
+/**
+ * @group Events
+ */
+export declare class KeyRefreshedLockEvent extends BaseEvent<{
+    key: string;
+    owner: string;
+    ttl: TimeSpan;
+}> {
+}
+/**
+ * @group Events
+ */
+export declare class UnexpectedErrorLockEvent extends BaseEvent<{
+    key: string;
+    owner: string;
+    ttl: TimeSpan | null;
+    error: unknown;
+}> {
+}
+/**
+ * @group Events
+ */
+export type LockEvents = KeyAcquiredLockEvent | KeyReleasedLockEvent | UnownedReleaseLockEvent | UnownedRefreshLockEvent | KeyAlreadyAcquiredLockEvent | KeyForceReleasedLockEvent | KeyRefreshedLockEvent | UnexpectedErrorLockEvent;
+/**
+ * The <i>registerLockEventsToSerde</i> function registers all <i>{@link ILock}</i> related events with <i>IFlexibleSerde</i>, ensuring they will properly be serialized and deserialized.
+ * @group Events
+ */
+export declare function registerLockEventsToSerde(serde: OneOrMore<IFlexibleSerde>): void;

package/dist/types/lock/implementations/_module.d.ts

@@ -0,0 +1,3 @@
+export * from "../../lock/implementations/_shared/_module";
+export * from "../../lock/implementations/adapters/_module";
+export * from "../../lock/implementations/derivables/_module";

package/dist/types/lock/implementations/_shared/_module.d.ts

@@ -0,0 +1,3 @@
+export * from "../../../lock/implementations/_shared/database-lock-adapter.test-suite";
+export * from "../../../lock/implementations/_shared/lock-adapter.test-suite";
+export * from "../../../lock/implementations/_shared/lock-provider.test-suite";

package/dist/types/lock/implementations/_shared/database-lock-adapter.test-suite.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @module Lock
+ */
+import { type TestAPI, type SuiteAPI, type ExpectStatic, type beforeEach } from "vitest";
+import { type IDatabaseLockAdapter } from "../../../lock/contracts/_module";
+import { type Promisable } from "../../../utilities/_module";
+/**
+ * @group Utilities
+ */
+export type DatabaseLockAdapterTestSuiteSettings = {
+    expect: ExpectStatic;
+    test: TestAPI;
+    describe: SuiteAPI;
+    beforeEach: typeof beforeEach;
+    createAdapter: () => Promisable<IDatabaseLockAdapter>;
+};
+/**
+ * The <i>databaseLockAdapterTestSuite</i> function simplifies the process of testing your custom implementation of <i>{@link IDatabaseLockAdapter}</i> with <i>vitest</i>.
+ * @group Utilities
+ */
+export declare function databaseLockAdapterTestSuite(settings: DatabaseLockAdapterTestSuiteSettings): void;

package/dist/types/lock/implementations/_shared/lock-adapter.test-suite.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @module Lock
+ */
+import { type TestAPI, type SuiteAPI, type ExpectStatic, type beforeEach } from "vitest";
+import { type ILockAdapter } from "../../../lock/contracts/_module";
+import { type Promisable } from "../../../utilities/_module";
+/**
+ * @group Utilities
+ */
+export type LockAdapterTestSuiteSettings = {
+    expect: ExpectStatic;
+    test: TestAPI;
+    describe: SuiteAPI;
+    beforeEach: typeof beforeEach;
+    createAdapter: () => Promisable<ILockAdapter>;
+};
+/**
+ * The <i>lockAdapterTestSuite</i> function simplifies the process of testing your custom implementation of <i>{@link ILockAdapter}</i> with <i>vitest</i>.
+ * @group Utilities
+ */
+export declare function lockAdapterTestSuite(settings: LockAdapterTestSuiteSettings): void;

package/dist/types/lock/implementations/_shared/lock-provider.test-suite.d.ts

@@ -0,0 +1,23 @@
+/**
+ * @module Lock
+ */
+import { type TestAPI, type SuiteAPI, type ExpectStatic, type beforeEach } from "vitest";
+import type { IGroupableLockProvider } from "../../../lock/contracts/_module";
+import { type Promisable } from "../../../utilities/_module";
+import type { ISerde } from "../../../serde/contracts/_module";
+/**
+ * @group Utilities
+ */
+export type LockProviderTestSuiteSettings = {
+    expect: ExpectStatic;
+    test: TestAPI;
+    describe: SuiteAPI;
+    beforeEach: typeof beforeEach;
+    createLockProvider: () => Promisable<IGroupableLockProvider>;
+    serde?: ISerde;
+};
+/**
+ * The <i>lockProviderTestSuite</i> function simplifies the process of testing your custom implementation of <i>{@link ILock}</i> with <i>vitest</i>.
+ * @group Utilities
+ */
+export declare function lockProviderTestSuite(settings: LockProviderTestSuiteSettings): void;

package/dist/types/lock/implementations/adapters/_module.d.ts

@@ -0,0 +1,5 @@
+export * from "../../../lock/implementations/adapters/libsql-lock-adapter/_module";
+export * from "../../../lock/implementations/adapters/memory-lock-adapter/_module";
+export * from "../../../lock/implementations/adapters/mongodb-lock-adapter/_module";
+export * from "../../../lock/implementations/adapters/redis-lock-adapter/_module";
+export * from "../../../lock/implementations/adapters/sqlite-lock-adapter/_module";

package/dist/types/lock/implementations/adapters/kysely-lock-adapter/_module.d.ts

@@ -0,0 +1 @@
+export * from "../../../../lock/implementations/adapters/kysely-lock-adapter/kysely-lock-adapter";

package/dist/types/lock/implementations/adapters/kysely-lock-adapter/kysely-lock-adapter.d.ts

@@ -0,0 +1,52 @@
+/**
+ * @module Lock
+ */
+import type { IDatabaseLockAdapter, ILockData } from "../../../../lock/contracts/_module";
+import type { Kysely } from "kysely";
+import { TimeSpan } from "../../../../utilities/_module";
+/**
+ * @internal
+ */
+type KyselyLockTable = {
+    group: string;
+    key: string;
+    owner: string;
+    expiresAt: number | null;
+};
+/**
+ * @internal
+ */
+type KyselyTables = {
+    lock: KyselyLockTable;
+};
+/**
+ * @internal
+ */
+type KyselySettings = {
+    database: Kysely<KyselyTables>;
+    rootGroup: string;
+    expiredKeysRemovalInterval?: TimeSpan;
+    shouldRemoveExpiredKeys?: boolean;
+};
+/**
+ * @internal
+ */
+export declare class KyselyLockAdapter implements IDatabaseLockAdapter {
+    private readonly group;
+    private readonly database;
+    private readonly expiredKeysRemovalInterval;
+    private readonly shouldRemoveExpiredKeys;
+    private timeoutId;
+    constructor(settings: KyselySettings);
+    deInit(): Promise<void>;
+    init(): Promise<void>;
+    removeExpiredKeys(): Promise<void>;
+    insert(key: string, owner: string, expiration: Date | null): Promise<void>;
+    update(key: string, owner: string, expiration: Date | null): Promise<number>;
+    remove(key: string, owner: string | null): Promise<void>;
+    refresh(key: string, owner: string, expiration: Date): Promise<number>;
+    find(key: string): Promise<ILockData | null>;
+    getGroup(): string;
+    withGroup(group: string): IDatabaseLockAdapter;
+}
+export {};

package/dist/types/lock/implementations/adapters/libsql-lock-adapter/_module.d.ts

@@ -0,0 +1 @@
+export * from "../../../../lock/implementations/adapters/libsql-lock-adapter/libsql-lock-adapter";

package/dist/types/lock/implementations/adapters/libsql-lock-adapter/libsql-lock-adapter.d.ts

@@ -0,0 +1,58 @@
+/**
+ * @module Lock
+ */
+import type { IDatabaseLockAdapter, ILockData } from "../../../../lock/contracts/_module";
+import { TimeSpan } from "../../../../utilities/_module";
+import type { Client } from "@libsql/client/.";
+/**
+ * @group Adapters
+ */
+export type LibsqlLockAdapterSettings = {
+    database: Client;
+    tableName?: string;
+    expiredKeysRemovalInterval?: TimeSpan;
+    shouldRemoveExpiredKeys?: boolean;
+    rootGroup: string;
+};
+/**
+ * To utilize the <i>LibsqlLockAdapter</i>, you must install the <i>"@libsql/client"</i> package.
+ * @group Adapters
+ */
+export declare class LibsqlLockAdapter implements IDatabaseLockAdapter {
+    private databaseLockAdapter;
+    /***
+     * @example
+     * ```ts
+     * import { LibsqlCacheAdapter } from "@daiso-tech/core";
+     * import { createClient } from "@libsql/client";
+     *
+     * (async () => {
+     *   const database = createClient({ url: "file:local.db" });
+     *   const lockAdapter = new LibsqlCacheAdapter({
+     *     database,
+     *     rootGroup: "@global"
+     *   });
+     *   await lockAdapter.init();
+     * })();
+     * ```
+     */
+    constructor(settings: LibsqlLockAdapterSettings);
+    removeExpiredKeys(): Promise<void>;
+    /**
+     * Removes the table where the cache values are stored and removes the table indexes.
+     * Note all cache data will be removed.
+     */
+    deInit(): Promise<void>;
+    /**
+     * Creates the table where the cache values are stored and it's related indexes.
+     * Note the <i>init</i> method needs to be called before using the adapter.
+     */
+    init(): Promise<void>;
+    insert(key: string, owner: string, expiration: Date | null): Promise<void>;
+    update(key: string, owner: string, expiration: Date | null): Promise<number>;
+    remove(key: string, owner: string | null): Promise<void>;
+    refresh(key: string, owner: string, expiration: Date): Promise<number>;
+    find(key: string): Promise<ILockData | null>;
+    getGroup(): string;
+    withGroup(group: string): IDatabaseLockAdapter;
+}

package/dist/types/lock/implementations/adapters/memory-lock-adapter/_module.d.ts

@@ -0,0 +1 @@
+export * from "../../../../lock/implementations/adapters/memory-lock-adapter/memory-lock-adapter";

package/dist/types/lock/implementations/adapters/memory-lock-adapter/memory-lock-adapter.d.ts

@@ -0,0 +1,52 @@
+/**
+ * @module Lock
+ */
+import { TimeSpan } from "../../../../utilities/_module";
+import type { ILockAdapter, ILockData } from "../../../../lock/contracts/_module";
+/**
+ * @group Adapters
+ */
+export type MemoryLockAdapterSettings = {
+    rootGroup: string;
+    map?: Map<string, ILockData>;
+};
+/**
+ * @group Adapters
+ */
+export declare class MemoryLockAdapter implements ILockAdapter {
+    private readonly group;
+    private readonly timeoutMap;
+    private readonly map;
+    /**
+     *  @example
+     * ```ts
+     * import { MemoryLockAdapter } from "@daiso-tech/core";
+     *
+     * const lockAdapter = new MemoryLockAdapter({
+     *   rootGroup: "@cache"
+     * });
+     * ```
+     * You can also provide an <i>Map</i>.
+     * @example
+     * ```ts
+     * import { MemoryLockAdapter } from "@daiso-tech/core";
+     *
+     * const map = new Map<any, any>();
+     * const lockAdapter = new MemoryLockAdapter({
+     *   rootGroup: "@cache",
+     *   map
+     * });
+     * ```
+     */
+    constructor(settings: MemoryLockAdapterSettings);
+    private getPrefix;
+    private withPrefix;
+    acquire(key: string, owner: string, ttl: TimeSpan | null): Promise<boolean>;
+    release(key: string, owner: string): Promise<boolean>;
+    forceRelease(key: string): Promise<void>;
+    isLocked(key: string): Promise<boolean>;
+    getRemainingTime(key: string): Promise<TimeSpan | null>;
+    refresh(key: string, owner: string, time: TimeSpan): Promise<boolean>;
+    getGroup(): string;
+    withGroup(group: string): ILockAdapter;
+}

package/dist/types/lock/implementations/adapters/mongodb-lock-adapter/_module.d.ts

@@ -0,0 +1 @@
+export * from "../../../../lock/implementations/adapters/mongodb-lock-adapter/mongodb-lock-adapter";

package/dist/types/lock/implementations/adapters/mongodb-lock-adapter/mongodb-lock-adapter.d.ts

@@ -0,0 +1,60 @@
+/**
+ * @module Lock
+ */
+import type { IDatabaseLockAdapter, ILockData } from "../../../../lock/contracts/_module";
+import type { CollectionOptions, Db } from "mongodb";
+/**
+ * @group Adapters
+ */
+export type MongodbLockAdapterSettings = {
+    database: Db;
+    rootGroup: string;
+    collectionName?: string;
+    collectionSettings?: CollectionOptions;
+};
+/**
+ * @group Adapters
+ */
+export declare class MongodbLockAdapter implements IDatabaseLockAdapter {
+    private readonly group;
+    private readonly database;
+    private readonly collection;
+    private readonly collectionName;
+    private readonly collectionSettings?;
+    /**
+     * @example
+     * ```ts
+     * import { MongodbLockAdapter } from "@daiso-tech/core";
+     * import { MongoClient } from "mongodb";
+     *
+     * (async () => {
+     *   const client = await MongoClient.connect("YOUR_MONGODB_CONNECTION_STRING");
+     *   const database = client.db("database");
+     *   const lockAdapter = new MongodbLockAdapter({
+     *     database,
+     *     rootGroup: "@global"
+     *   });
+     *   await lockAdapter.init();
+     * })();
+     * ```
+     */
+    constructor({ collectionName, collectionSettings, database, rootGroup, }: MongodbLockAdapterSettings);
+    removeExpiredKeys(): Promise<void>;
+    /**
+     * Creates all related indexes.
+     * Note the <i>init</i> method needs to be called before using the adapter.
+     */
+    init(): Promise<void>;
+    /**
+     * Removes the collection where the cache values are stored and all it's related indexes.
+     * Note all cache data will be removed.
+     */
+    deInit(): Promise<void>;
+    insert(key: string, owner: string, expiration: Date | null): Promise<void>;
+    update(key: string, owner: string, expiration: Date | null): Promise<number>;
+    remove(key: string, owner: string | null): Promise<void>;
+    refresh(key: string, owner: string, expiration: Date): Promise<number>;
+    find(key: string): Promise<ILockData | null>;
+    getGroup(): string;
+    withGroup(group: string): IDatabaseLockAdapter;
+}

package/dist/types/lock/implementations/adapters/redis-lock-adapter/_module.d.ts

@@ -0,0 +1 @@
+export * from "../../../../lock/implementations/adapters/redis-lock-adapter/redis-lock-adapter";

package/dist/types/lock/implementations/adapters/redis-lock-adapter/redis-lock-adapter.d.ts

@@ -0,0 +1,57 @@
+/**
+ * @module Lock
+ */
+import { TimeSpan } from "../../../../utilities/_module";
+import type { ILockAdapter } from "../../../../lock/contracts/_module";
+import type Redis from "ioredis";
+import type { Result } from "ioredis";
+declare module "ioredis" {
+    interface RedisCommander<Context> {
+        daiso_lock_acquire(key: string, owner: string, ttl: string): Result<number, Context>;
+        daiso_lock_release(key: string, owner: string): Result<number, Context>;
+        daiso_lock_refresh(key: string, owner: string, ttl: string): Result<number, Context>;
+    }
+}
+/**
+ * @group Adapters
+ */
+export type RedisLockAdapterSettings = {
+    database: Redis;
+    rootGroup: string;
+};
+/**
+ * @group Adapters
+ */
+export declare class RedisLockAdapter implements ILockAdapter {
+    private readonly group;
+    private readonly database;
+    /**
+     * @example
+     * ```ts
+     * import { RedisLockAdapter, SuperJsonSerde } from "@daiso-tech/core";
+     * import Redis from "ioredis";
+     *
+     * const database = new Redis("YOUR_REDIS_CONNECTION_STRING");
+     * const serde = new SuperJsonSerde();
+     * const lockAdapter = new RedisLockAdapter({
+     *   database,
+     *   serde,
+     *   rootGroup: "@global"
+     * });
+     * ```
+     */
+    constructor(settings: RedisLockAdapterSettings);
+    private initAquireCommand;
+    private initReleaseCommand;
+    private initRefreshComand;
+    private getPrefix;
+    private withPrefix;
+    acquire(key: string, owner: string, ttl: TimeSpan | null): Promise<boolean>;
+    release(key: string, owner: string): Promise<boolean>;
+    forceRelease(key: string): Promise<void>;
+    isLocked(key: string): Promise<boolean>;
+    getRemainingTime(key: string): Promise<TimeSpan | null>;
+    refresh(key: string, owner: string, ttl: TimeSpan): Promise<boolean>;
+    getGroup(): string;
+    withGroup(group: string): ILockAdapter;
+}

package/dist/types/lock/implementations/adapters/sqlite-lock-adapter/_module.d.ts

@@ -0,0 +1 @@
+export * from "../../../../lock/implementations/adapters/sqlite-lock-adapter/sqlite-lock-adapter";

package/dist/types/lock/implementations/adapters/sqlite-lock-adapter/sqlite-lock-adapter.d.ts

@@ -0,0 +1,57 @@
+/**
+ * @module Lock
+ */
+import type { IDatabaseLockAdapter, ILockData } from "../../../../lock/contracts/_module";
+import { TimeSpan } from "../../../../utilities/_module";
+import type { SqliteDatabase } from "kysely";
+/**
+ * @group Adapters
+ */
+export type SqliteLockAdapterSettings = {
+    database: SqliteDatabase;
+    tableName?: string;
+    expiredKeysRemovalInterval?: TimeSpan;
+    shouldRemoveExpiredKeys?: boolean;
+    rootGroup: string;
+};
+/**
+ * @group Adapters
+ */
+export declare class SqliteLockAdapter implements IDatabaseLockAdapter {
+    private databaseLockAdapter;
+    /**
+     * @example
+     * ```ts
+     * import { SqliteLockAdapter } from "@daiso-tech/core";
+     * import Sqlite from "better-sqlite3";
+     *
+     * (async () => {
+     *   const database = new Sqlite("local.db");
+     *   const lockAdapter = new SqliteLockAdapter({
+     *     database,
+     *     rootGroup: "@global"
+     *   });
+     *   await lockAdapter.init();
+     * })();
+     * ```
+     */
+    constructor(settings: SqliteLockAdapterSettings);
+    removeExpiredKeys(): Promise<void>;
+    /**
+     * Removes the table where the cache values are stored and removes the table indexes.
+     * Note all cache data will be removed.
+     */
+    deInit(): Promise<void>;
+    /**
+     * Creates the table where the cache values are stored and it's related indexes.
+     * Note the <i>init</i> method needs to be called before using the adapter.
+     */
+    init(): Promise<void>;
+    insert(key: string, owner: string, expiration: Date | null): Promise<void>;
+    update(key: string, owner: string, expiration: Date | null): Promise<number>;
+    remove(key: string, owner: string | null): Promise<void>;
+    refresh(key: string, owner: string, expiration: Date): Promise<number>;
+    find(key: string): Promise<ILockData | null>;
+    getGroup(): string;
+    withGroup(group: string): IDatabaseLockAdapter;
+}

package/dist/types/lock/implementations/derivables/_module.d.ts

@@ -0,0 +1,2 @@
+export * from "../../../lock/implementations/derivables/lock-provider/_module";
+export * from "../../../lock/implementations/derivables/lock-provider-factory/_module";

package/dist/types/lock/implementations/derivables/lock-provider/_module.d.ts

@@ -0,0 +1 @@
+export * from "../../../../lock/implementations/derivables/lock-provider/lock-provider";

package/dist/types/lock/implementations/derivables/lock-provider/database-lock-adapter.d.ts

@@ -0,0 +1,23 @@
+/**
+ * @module Lock
+ */
+import type { IDeinitizable, IInitizable } from "../../../../_module";
+import { TimeSpan } from "../../../../_module";
+import type { IDatabaseLockAdapter, ILockAdapter } from "../../../../lock/contracts/_module";
+/**
+ * @internal
+ */
+export declare class DatabaseLockAdapter implements ILockAdapter, IDeinitizable, IInitizable {
+    private readonly adapter;
+    constructor(adapter: IDatabaseLockAdapter);
+    init(): Promise<void>;
+    deInit(): Promise<void>;
+    acquire(key: string, owner: string, ttl: TimeSpan | null): Promise<boolean>;
+    release(key: string, owner: string): Promise<boolean>;
+    forceRelease(key: string): Promise<void>;
+    isLocked(key: string): Promise<boolean>;
+    getRemainingTime(key: string): Promise<TimeSpan | null>;
+    refresh(key: string, owner: string, ttl: TimeSpan): Promise<boolean>;
+    getGroup(): string;
+    withGroup(group: string): ILockAdapter;
+}