Skip to main content

Configuring Lock adapters

MemoryLockAdapter​

To use the MemoryLockAdapter you only need to create instance of it:

./samples/memory-lock-adapter.ts
import { MemoryLockAdapter } from "eridu-tech/lock/memory-lock-adapter";

export const memoryLockAdapter = new MemoryLockAdapter();

You can also provide an Map that will be used for storing the data in memory:

./samples/memory-lock-adapter-with-map.ts
import { MemoryLockAdapter } from "eridu-tech/lock/memory-lock-adapter";

const map = new Map<any, any>();
const memoryLockAdapter = new MemoryLockAdapter(map);
info

MemoryLockAdapter lets you test your app without external dependencies like Redis, ideal for local development, unit tests, integration tests and fast E2E test for the backend application.

danger

Note the MemoryLockAdapter is limited to single process usage and cannot be shared across multiple servers or processes.

Settings​

To clean up expired lock keys, call removeAllExpired at a regular interval (for example, using a cron job):

./samples/memory-lock-remove-all-expired.ts
import { MemoryLockAdapter } from "eridu-tech/lock/memory-lock-adapter";

const memoryLockAdapter = new MemoryLockAdapter();

// Remove all expired lock keys manually.
await memoryLockAdapter.removeAllExpired();
info

To remove the lock map and all stored lock data, use deInit method:

./samples/memory-lock-adapter-deinit.ts
import { memoryLockAdapter } from "./memory-lock-adapter.js";

await memoryLockAdapter.deInit();

MongodbLockAdapter​

To use the MongodbLockAdapter, you'll need to:

  1. Install the required dependency: mongodb package.

Setup​

Connect to MongoDB:

./samples/mongodb-lock-adapter-setup.ts
import { MongoClient } from "mongodb";

const client = await MongoClient.connect("YOUR_MONGODB_CONNECTION_STRING");
export const database = client.db("database");
info

The database setting also accepts a TransactionContext, which makes the adapter transaction aware. Adapters given the same instance share the same transaction when available.

Usage​

Create the adapter:

./samples/mongodb-lock-adapter.ts
import { MongodbLockAdapter } from "eridu-tech/lock/mongodb-lock-adapter";
import { database } from "./mongodb-lock-adapter-setup.js";

export const mongodbLockAdapter = new MongodbLockAdapter({
    database,
});

// You need initialize the adapter once before using it.
// During the initialization the indexes will be created
await mongodbLockAdapter.init();

You can change the collection name:

./samples/mongodb-lock-collection-name.ts
import { MongodbLockAdapter } from "eridu-tech/lock/mongodb-lock-adapter";
import { database } from "./mongodb-lock-adapter-setup.js";

const mongodbLockAdapter = new MongodbLockAdapter({
    database,
    // By default "lock" is used as collection name
    collectionName: "my-lock",
});

await mongodbLockAdapter.init();

You can change the collection settings:

./samples/mongodb-lock-collection-settings.ts
import { MongodbLockAdapter } from "eridu-tech/lock/mongodb-lock-adapter";
import { database } from "./mongodb-lock-adapter-setup.js";

const mongodbLockAdapter = new MongodbLockAdapter({
    database,
    // You configure additional collection settings
    collectionSettings: {},
});

await mongodbLockAdapter.init();
info

To remove the lock collection and all stored lock data, use deInit method:

./samples/mongodb-lock-adapter-deinit.ts
import { mongodbLockAdapter } from "./mongodb-lock-adapter.js";

await mongodbLockAdapter.deInit();
danger

Note in order to use MongodbLockAdapter correctly, ensure you use a single, consistent database across all server instances or processes.

RedisLockAdapter​

To use the RedisLockAdapter, you'll need to:

  1. Install the required dependency: ioredis package.

Setup​

Connect to Redis:

./samples/redis-lock-adapter-setup.ts
import { Redis } from "ioredis";

export const database = new Redis("YOUR_REDIS_CONNECTION_STRING");

Usage​

Create the adapter:

./samples/redis-lock-adapter.ts
import { RedisLockAdapter } from "eridu-tech/lock/redis-lock-adapter";
import { database } from "./redis-lock-adapter-setup.js";

const redisLockAdapter = new RedisLockAdapter(database);
danger

Note in order to use RedisLockAdapter correctly, ensure you use a single, consistent database across all server instances or processes.

KyselyLockAdapter​

To use the KyselyLockAdapter, you'll need to:

  1. Use database provider that has support for transactions.
  2. Install the required dependency: kysely package.

Setup​

Create a function that creates the TransactionContext by wrapping a Kysely instance in a KyselyTransactionAdapter:

./samples/kysely-lock-adapter-setup.ts
import { ExecutionContext } from "eridu-tech/execution-context";
import { AlsExecutionContextAdapter } from "eridu-tech/execution-context/als-execution-context-adapter";
import { contextToken } from "eridu-tech/execution-context/contracts";
import { TransactionContext } from "eridu-tech/transaction-context";
import { KyselyTransactionAdapter } from "eridu-tech/transaction-context/kysely-transaction-adapter";
import type { ITransactionContext } from "eridu-tech/transaction-context/contracts";
import type { Kysely } from "kysely";

const executionContext = new ExecutionContext(new AlsExecutionContextAdapter());

// `KyselyLockAdapter` is transaction aware: it runs every lock operation
// through the `current` client of this context, which is the transaction-scoped
// client while a transaction is active and the base client otherwise.
export function createTransactionContext(
    kysely: Kysely<any>,
): ITransactionContext<Kysely<any>> {
    return new TransactionContext<Kysely<any>>({
        token: contextToken("kysely"),
        adapter: new KyselyTransactionAdapter({
            database: kysely,
        }),
        executionContext,
    });
}
info

The transactionContext setting makes the adapter transaction aware. Adapters given the same instance share the same transaction when available.

With Sqlite​

You will need to install better-sqlite3 package:

./samples/kysely-lock-sqlite.ts
import { KyselyLockAdapter } from "eridu-tech/lock/kysely-lock-adapter";
import Sqlite from "better-sqlite3";
import { Kysely, SqliteDialect } from "kysely";
import { createTransactionContext } from "./kysely-lock-adapter-setup.js";

const database = new Sqlite("DATABASE_NAME.db");
const kysely = new Kysely<any>({
    dialect: new SqliteDialect({
        database,
    }),
});
const transactionContext = createTransactionContext(kysely);
export const kyselyLockAdapter = new KyselyLockAdapter({
    transactionContext,
});

// You need initialize the adapter once before using it.
// During the initialization the schema will be created
await kyselyLockAdapter.init();
danger

Note using KyselyLockAdapter with sqlite is limited to single server usage and cannot be shared across multiple servers but it can be shared between different processes. To use it correctly, ensure all process instances access the same persisted database.

With Postgres​

You will need to install pg package:

./samples/kysely-lock-postgres.ts
import { KyselyLockAdapter } from "eridu-tech/lock/kysely-lock-adapter";
import { Pool } from "pg";
import { Kysely, PostgresDialect } from "kysely";
import { createTransactionContext } from "./kysely-lock-adapter-setup.js";

const database = new Pool({
    database: "DATABASE_NAME",
    host: "DATABASE_HOST",
    user: "DATABASE_USER",
    // DATABASE port
    port: 5432,
    password: "DATABASE_PASSWORD",
    max: 10,
});
const kysely = new Kysely<any>({
    dialect: new PostgresDialect({
        pool: database,
    }),
});
const transactionContext = createTransactionContext(kysely);
const kyselyLockAdapter = new KyselyLockAdapter({
    transactionContext,
});

// You need initialize the adapter once before using it.
// During the initialization the schema will be created
await kyselyLockAdapter.init();
danger

Note in order to use KyselyLockAdapter with postgres correctly, ensure you use a single, consistent database across all server instances. This means you can't use replication.

With Mysql​

You will need to install mysql2 package:

./samples/kysely-lock-mysql.ts
import { KyselyLockAdapter } from "eridu-tech/lock/kysely-lock-adapter";
import { createPool } from "mysql2";
import { Kysely, MysqlDialect } from "kysely";
import { createTransactionContext } from "./kysely-lock-adapter-setup.js";

const database = createPool({
    host: "DATABASE_HOST",
    // Database port
    port: 3306,
    database: "DATABASE_NAME",
    user: "DATABASE_USER",
    password: "DATABASE_PASSWORD",
    connectionLimit: 10,
});
const kysely = new Kysely<any>({
    dialect: new MysqlDialect({
        pool: database,
    }),
});
const transactionContext = createTransactionContext(kysely);
const kyselyLockAdapter = new KyselyLockAdapter({
    transactionContext,
});

// You need initialize the adapter once before using it.
// During the initialization the schema will be created
await kyselyLockAdapter.init();
danger

Note in order to use KyselyLockAdapter with mysql correctly, ensure you use a single, consistent database across all server instances. This means you can't use replication.

With Libsql​

You will need to install @libsql/kysely-libsql package:

./samples/kysely-lock-libsql.ts
import { KyselyLockAdapter } from "eridu-tech/lock/kysely-lock-adapter";
import { LibsqlDialect } from "@libsql/kysely-libsql";
import { Kysely } from "kysely";
import { createTransactionContext } from "./kysely-lock-adapter-setup.js";

const kysely = new Kysely<any>({
    dialect: new LibsqlDialect({
        url: "DATABASE_URL",
    }),
});
const transactionContext = createTransactionContext(kysely);
const kyselyLockAdapter = new KyselyLockAdapter({
    transactionContext,
});

// You need initialize the adapter once before using it.
// During the initialization the schema will be created
await kyselyLockAdapter.init();
danger

Note in order to use KyselyLockAdapter with libsql correctly, ensure you use a single, consistent database across all server instances. This means you can't use libsql embedded replicas.

Settings​

To clean up expired lock keys, call removeAllExpired at a regular interval (for example, using a cron job):

./samples/kysely-lock-remove-all-expired.ts
import { kyselyLockAdapter } from "./kysely-lock-sqlite.js";

// Remove all expired lock keys manually.
await kyselyLockAdapter.removeAllExpired();
info

To remove the lock table and all stored lock data, use deInit method:

./samples/kysely-lock-adapter-deinit.ts
import { kyselyLockAdapter } from "./kysely-lock-sqlite.js";

await kyselyLockAdapter.deInit();

NoOpLockAdapter​

The NoOpLockAdapter is a no-operation implementation, it performs no actions when called:

./samples/no-op-lock-adapter.ts
import { NoOpLockAdapter } from "eridu-tech/lock/no-op-lock-adapter";

const noOpLockAdapter = new NoOpLockAdapter();
info

The NoOpLockAdapter is useful when you want to mock out or disable your LockFactory instance.

Further information​

For further information refer to eridu-tech/lock API docs.