@adonisjs/lock 1.0.0-0

package/LICENSE.md

@@ -0,0 +1,9 @@
+# The MIT License
+
+Copyright (c) 2023
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the 'Software'), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,33 @@
+# @adonisjs/lock
+
+<br />
+
+[![gh-workflow-image]][gh-workflow-url] [![npm-image]][npm-url] ![][typescript-image] [![license-image]][license-url]
+
+## Introduction
+Atomic locks (mutex) for AdonisJS applications. The package is built on top of [Verrou](https://github.com/Julien-R44/verrou) and provides a simple API to acquire and release locks with support for multiple drivers.
+
+## Official Documentation
+The documentation is available on the [AdonisJS website](https://docs.adonisjs.com/guides/lock/introduction).
+
+## Contributing
+One of the primary goals of AdonisJS is to have a vibrant community of users and contributors who believes in the principles of the framework.
+
+We encourage you to read the [contribution guide](https://github.com/adonisjs/.github/blob/main/docs/CONTRIBUTING.md) before contributing to the framework.
+
+## Code of Conduct
+In order to ensure that the AdonisJS community is welcoming to all, please review and abide by the [Code of Conduct](https://github.com/adonisjs/.github/blob/main/docs/CODE_OF_CONDUCT.md).
+
+## License
+AdonisJS Lucid is open-sourced software licensed under the [MIT license](LICENSE.md).
+
+[gh-workflow-image]: https://img.shields.io/github/actions/workflow/status/adonisjs/lock/test.yml?style=for-the-badge
+[gh-workflow-url]: https://github.com/adonisjs/lock/actions/workflows/test.yml "Github action"
+
+[npm-image]: https://img.shields.io/npm/v/@adonisjs/lock/latest.svg?style=for-the-badge&logo=npm
+[npm-url]: https://www.npmjs.com/package/@adonisjs/lock/v/latest "npm"
+
+[typescript-image]: https://img.shields.io/badge/Typescript-294E80.svg?style=for-the-badge&logo=typescript
+
+[license-url]: LICENSE.md
+[license-image]: https://img.shields.io/github/license/adonisjs/lock?style=for-the-badge

package/build/chunk-6C3VEZWH.js

@@ -0,0 +1,9 @@
+var __defProp = Object.defineProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+
+export {
+  __export
+};

package/build/config/lock.stub

@@ -0,0 +1,42 @@
+{{{
+  exports({ to: app.configPath('lock.ts') })
+}}}
+import env from '#start/env'
+import { defineConfig, stores } from '@adonisjs/lock'
+
+const lockConfig = defineConfig({
+  default: env.get('LOCK_STORE'),
+  stores: {
+    {{#if store === 'redis'}}
+    /**
+     * Redis store to save manage locks
+     */
+    redis: stores.redis({}),
+    {{/if}}
+    {{#if store === 'database'}}
+    /**
+     * Database store to manage locks
+     */
+    database: stores.database({
+      tableName: 'locks'
+    }),
+    {{/if}}
+    {{#if store === 'dynamodb'}}
+    /**
+     * DynamoDB store to manage locks
+     */
+    dynamodb: stores.dynamodb({}),
+    {{/if}}
+    /**
+     * Memory store could be used during
+     * testing
+     */
+    memory: stores.memory()
+  },
+})
+
+export default lockConfig
+
+declare module '@adonisjs/lock/types' {
+  export interface LockStoresList extends InferLockStores<typeof lockConfig> {}
+}

package/build/index.d.ts

@@ -0,0 +1,47 @@
+import { ConfigProvider } from '@adonisjs/core/types';
+import { RedisConnections } from '@adonisjs/redis/types';
+import { StoreFactory, DynamoDbOptions } from '@verrou/core/types';
+import { E_LOCK_ALREADY_ACQUIRED, E_LOCK_NOT_OWNED, E_LOCK_STORAGE_ERROR, E_LOCK_TIMEOUT } from '@verrou/core';
+import Configure from '@adonisjs/core/commands/configure';
+
+/**
+ * Different stores supported by the lock module
+ */
+declare const stores: {
+    memory: () => ConfigProvider<StoreFactory>;
+    redis: (config: {
+        connectionName?: keyof RedisConnections;
+    }) => ConfigProvider<StoreFactory>;
+    database: (config?: {
+        connectionName?: string;
+        tableName?: string;
+    }) => ConfigProvider<StoreFactory>;
+    dynamodb: (config: DynamoDbOptions) => ConfigProvider<StoreFactory>;
+};
+
+/**
+ * Re-exporting verrou errors
+ */
+
+declare const errors_E_LOCK_ALREADY_ACQUIRED: typeof E_LOCK_ALREADY_ACQUIRED;
+declare const errors_E_LOCK_NOT_OWNED: typeof E_LOCK_NOT_OWNED;
+declare const errors_E_LOCK_STORAGE_ERROR: typeof E_LOCK_STORAGE_ERROR;
+declare const errors_E_LOCK_TIMEOUT: typeof E_LOCK_TIMEOUT;
+declare namespace errors {
+  export { errors_E_LOCK_ALREADY_ACQUIRED as E_LOCK_ALREADY_ACQUIRED, errors_E_LOCK_NOT_OWNED as E_LOCK_NOT_OWNED, errors_E_LOCK_STORAGE_ERROR as E_LOCK_STORAGE_ERROR, errors_E_LOCK_TIMEOUT as E_LOCK_TIMEOUT };
+}
+
+declare function configure(command: Configure): Promise<void>;
+
+/**
+ * Define lock configuration
+ */
+declare function defineConfig<KnownStores extends Record<string, ConfigProvider<StoreFactory>>>(config: {
+    default: keyof KnownStores;
+    stores: KnownStores;
+}): {
+    default: keyof KnownStores;
+    stores: KnownStores;
+};
+
+export { configure, defineConfig, errors, stores };

package/build/index.js

@@ -0,0 +1,169 @@
+import {
+  __export
+} from "./chunk-6C3VEZWH.js";
+
+// src/stores.ts
+import { configProvider } from "@adonisjs/core";
+import { RuntimeException } from "@adonisjs/core/exceptions";
+var stores = {
+  /**
+   * Redis store
+   * You must install @adonisjs/redis to use this driver
+   */
+  redis(config) {
+    return configProvider.create(async (app) => {
+      const redis = await app.container.make("redis");
+      const { redisStore } = await import("@verrou/core/drivers/redis");
+      const redisConnection = redis.connection(config.connectionName);
+      const store = redisStore({ connection: redisConnection.ioConnection });
+      return { driver: store };
+    });
+  },
+  /**
+   * Memory store
+   */
+  memory() {
+    return configProvider.create(async () => {
+      const { memoryStore } = await import("@verrou/core/drivers/memory");
+      return { driver: memoryStore() };
+    });
+  },
+  /**
+   * Database store
+   * You must install @adonisjs/lucid to use this driver
+   */
+  database(config) {
+    return configProvider.create(async (app) => {
+      const db = await app.container.make("lucid.db");
+      const connectionName = config?.connectionName || db.primaryConnectionName;
+      const connection = db.manager.get(connectionName);
+      if (!connection) {
+        throw new RuntimeException(
+          `Invalid connection name "${connectionName}" referenced by "config/lock.ts" file. First register the connection inside "config/database.ts" file`
+        );
+      }
+      const dialect = db.connection(connectionName).dialect.name;
+      const supportedDialects = ["postgres", "mysql", "better-sqlite3", "sqlite3"];
+      if (!supportedDialects.includes(dialect)) {
+        throw new Error(`Unsupported dialect "${dialect}"`);
+      }
+      const rawConnection = db.getRawConnection(connectionName);
+      if (!rawConnection?.connection?.client) {
+        throw new Error(`Unable to get raw connection for "${connectionName}"`);
+      }
+      const { knexStore } = await import("@verrou/core/drivers/knex");
+      const store = knexStore({
+        connection: rawConnection.connection.client,
+        tableName: config?.tableName,
+        autoCreateTable: false
+      });
+      return { driver: store };
+    });
+  },
+  /**
+   * DynamoDB store
+   * You must install @aws-sdk/client-dynamodb to use this driver
+   */
+  dynamodb(config) {
+    return configProvider.create(async () => {
+      const { dynamodbStore } = await import("@verrou/core/drivers/dynamodb");
+      return { driver: dynamodbStore(config) };
+    });
+  }
+};
+
+// src/errors.ts
+var errors_exports = {};
+__export(errors_exports, {
+  E_LOCK_ALREADY_ACQUIRED: () => E_LOCK_ALREADY_ACQUIRED,
+  E_LOCK_NOT_OWNED: () => E_LOCK_NOT_OWNED,
+  E_LOCK_STORAGE_ERROR: () => E_LOCK_STORAGE_ERROR,
+  E_LOCK_TIMEOUT: () => E_LOCK_TIMEOUT
+});
+import {
+  E_LOCK_TIMEOUT,
+  E_LOCK_NOT_OWNED,
+  E_LOCK_STORAGE_ERROR,
+  E_LOCK_ALREADY_ACQUIRED
+} from "@verrou/core";
+
+// configure.ts
+import string from "@adonisjs/core/helpers/string";
+
+// stubs/main.ts
+import { getDirname } from "@adonisjs/core/helpers";
+var stubsRoot = getDirname(import.meta.url);
+
+// configure.ts
+var KNOWN_STORES = ["database", "redis", "dynamodb"];
+async function configure(command) {
+  let selectedStore = command.parsedFlags.store;
+  if (!selectedStore) {
+    selectedStore = await command.prompt.choice(
+      "Select the storage layer you want to use",
+      KNOWN_STORES,
+      {
+        validate(value) {
+          return !value ? "Please select a store" : true;
+        }
+      }
+    );
+  }
+  if (!KNOWN_STORES.includes(selectedStore)) {
+    command.exitCode = 1;
+    command.logger.logError(
+      `Invalid lock store "${selectedStore}". Supported stores are: ${string.sentence(
+        KNOWN_STORES
+      )}`
+    );
+    return;
+  }
+  const codemods = await command.createCodemods();
+  await codemods.makeUsingStub(stubsRoot, "config/lock.stub", {
+    store: selectedStore
+  });
+  await codemods.updateRcFile((rcFile) => {
+    rcFile.addProvider("@adonisjs/lock/lock_provider");
+  });
+  if (selectedStore === "database") {
+    await codemods.makeUsingStub(stubsRoot, "make/migration/locks.stub", {
+      entity: command.app.generators.createEntity("locks"),
+      migration: {
+        folder: "database/migrations",
+        fileName: `${(/* @__PURE__ */ new Date()).getTime()}_create_locks_table.ts`
+      }
+    });
+  }
+  await codemods.defineEnvVariables({
+    LOCK_STORE: selectedStore
+  });
+  await codemods.defineEnvValidations({
+    leadingComment: "Variables for configuring the lock package",
+    variables: {
+      LOCK_STORE: `Env.schema.enum(['${selectedStore}', 'memory'] as const)`
+    }
+  });
+}
+
+// src/define_config.ts
+import { InvalidArgumentsException } from "@adonisjs/core/exceptions";
+function defineConfig(config) {
+  if (!config.stores) {
+    throw new InvalidArgumentsException('Missing "stores" property in lock config');
+  }
+  if (!config.default) {
+    throw new InvalidArgumentsException('Missing "default" store in lock config');
+  }
+  if (!config.stores[config.default]) {
+    throw new InvalidArgumentsException(
+      `Missing "stores.${config.default.toString()}" in lock config. It is referenced by the "default" property`
+    );
+  }
+  return config;
+}
+export {
+  configure,
+  defineConfig,
+  errors_exports as errors,
+  stores
+};

package/build/make/migration/locks.stub

@@ -0,0 +1,22 @@
+{{{
+  exports({
+    to: app.makePath(migration.folder, entity.path, migration.fileName)
+  })
+}}}
+import { BaseSchema } from '@adonisjs/lucid/schema'
+
+export default class extends BaseSchema {
+  protected tableName = 'locks'
+
+  async up() {
+    this.schema.createTable(this.tableName, (table) => {
+      table.string('key', 255).notNullable().primary()
+      table.string('owner').notNullable()
+      table.bigint('expiration').unsigned().nullable()
+    })
+  }
+
+  async down() {
+    this.schema.dropTable(this.tableName)
+  }
+}

package/build/providers/lock_provider.d.ts

@@ -0,0 +1,23 @@
+import { Verrou } from '@verrou/core';
+import { ApplicationService } from '@adonisjs/core/types';
+import { LockStoresList } from '../src/types.js';
+import '@verrou/core/types';
+
+/**
+ * Add lock manager type to the container bindings
+ */
+declare module '@adonisjs/core/types' {
+    interface ContainerBindings {
+        'lock.manager': Verrou<LockStoresList>;
+    }
+}
+declare class LockProvider {
+    protected app: ApplicationService;
+    constructor(app: ApplicationService);
+    /**
+     * Registers the lock manager in the application container
+     */
+    register(): void;
+}
+
+export { LockProvider as default };

package/build/providers/lock_provider.js

@@ -0,0 +1,27 @@
+import "../chunk-6C3VEZWH.js";
+
+// providers/lock_provider.ts
+var LockProvider = class {
+  constructor(app) {
+    this.app = app;
+  }
+  /**
+   * Registers the lock manager in the application container
+   */
+  register() {
+    this.app.container.singleton("lock.manager", async () => {
+      const { Verrou } = await import("@verrou/core");
+      const config = this.app.config.get("lock", {});
+      const stores = Object.entries(config.stores).map(async ([name, store]) => {
+        return [name, await store.resolver(this.app)];
+      });
+      return new Verrou({
+        default: config.default,
+        stores: Object.fromEntries(await Promise.all(stores))
+      });
+    });
+  }
+};
+export {
+  LockProvider as default
+};

package/build/services/main.d.ts

@@ -0,0 +1,8 @@
+import { LockService } from '../src/types.js';
+import '@verrou/core';
+import '@verrou/core/types';
+import '@adonisjs/core/types';
+
+declare let lock: LockService;
+
+export { lock as default };

package/build/services/main.js

@@ -0,0 +1,11 @@
+import "../chunk-6C3VEZWH.js";
+
+// services/main.ts
+import app from "@adonisjs/core/services/app";
+var lock;
+await app.booted(async () => {
+  lock = await app.container.make("lock.manager");
+});
+export {
+  lock as default
+};

package/build/src/types.d.ts

@@ -0,0 +1,27 @@
+import { Verrou } from '@verrou/core';
+import { StoreFactory } from '@verrou/core/types';
+export * from '@verrou/core/types';
+import { ConfigProvider } from '@adonisjs/core/types';
+
+/**
+ * A list of known lock stores inferred from the user config
+ */
+interface LockStoresList extends Record<string, StoreFactory> {
+}
+/**
+ * Helper method to resolve configured lock stores
+ * inside user app
+ */
+type InferLockStores<T extends {
+    stores: Record<string, ConfigProvider<StoreFactory>>;
+}> = {
+    [K in keyof T['stores']]: Awaited<ReturnType<T['stores'][K]['resolver']>>;
+};
+/**
+ * Lock service is a singleton instance of Verrou
+ * configured using user app's config
+ */
+interface LockService extends Verrou<LockStoresList> {
+}
+
+export type { InferLockStores, LockService, LockStoresList };

package/build/src/types.js

@@ -0,0 +1,2 @@
+// src/types.ts
+export * from "@verrou/core/types";

package/package.json

@@ -0,0 +1,131 @@
+{
+  "name": "@adonisjs/lock",
+  "description": "Atomic locks (mutex) for AdonisJS applications",
+  "version": "1.0.0-0",
+  "engines": {
+    "node": ">=20.6.0"
+  },
+  "type": "module",
+  "files": [
+    "build"
+  ],
+  "exports": {
+    ".": "./build/index.js",
+    "./lock_provider": "./build/providers/lock_provider.js",
+    "./services/main": "./build/services/main.js",
+    "./types": "./build/src/types.js"
+  },
+  "scripts": {
+    "clean": "del-cli build",
+    "copy:templates": "copyfiles --up 1 \"stubs/**/*.stub\" build",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint . --ext=.ts",
+    "format": "prettier --write .",
+    "quick:test": "node --import=./tsnode.esm.js --enable-source-maps bin/test.ts",
+    "pretest": "npm run lint",
+    "test": "c8 npm run quick:test",
+    "prebuild": "npm run lint && npm run clean",
+    "build": "tsup-node && npm run copy:templates",
+    "release": "np",
+    "version": "npm run build",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "@adonisjs/assembler": "^7.2.3",
+    "@adonisjs/core": "^6.3.1",
+    "@adonisjs/eslint-config": "^1.3.0",
+    "@adonisjs/lucid": "^20.3.1",
+    "@adonisjs/prettier-config": "^1.3.0",
+    "@adonisjs/redis": "^8.0.1",
+    "@adonisjs/tsconfig": "^1.3.0",
+    "@japa/assert": "^2.1.0",
+    "@japa/file-system": "^2.2.0",
+    "@japa/runner": "^3.1.1",
+    "@swc/core": "^1.4.6",
+    "@types/node": "^20.11.25",
+    "better-sqlite3": "^9.4.3",
+    "c8": "^9.1.0",
+    "copyfiles": "^2.4.1",
+    "del-cli": "^5.1.0",
+    "dotenv": "^16.4.5",
+    "eslint": "^8.57.0",
+    "mysql": "^2.18.1",
+    "np": "^10.0.0",
+    "pg": "^8.11.3",
+    "prettier": "^3.2.5",
+    "timekeeper": "^2.3.1",
+    "ts-node": "^10.9.2",
+    "tsup": "^8.0.2",
+    "typescript": "^5.4.2"
+  },
+  "dependencies": {
+    "@verrou/core": "^0.3.0"
+  },
+  "peerDependencies": {
+    "@adonisjs/assembler": "^7.0.0",
+    "@adonisjs/core": "^6.2.0",
+    "@adonisjs/lucid": "^20.0.0",
+    "@adonisjs/redis": "^8.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@adonisjs/redis": {
+      "optional": true
+    },
+    "@adonisjs/lucid": {
+      "optional": true
+    }
+  },
+  "author": "Julien Ripouteau <julien@ripouteau.com>,adonisjs",
+  "license": "MIT",
+  "homepage": "https://github.com/adonisjs/lock#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/adonisjs/lock.git"
+  },
+  "bugs": {
+    "url": "https://github.com/adonisjs/lock/issues"
+  },
+  "keywords": [
+    "locks",
+    "mutexes",
+    "atomic lock",
+    "adonisjs"
+  ],
+  "eslintConfig": {
+    "extends": "@adonisjs/eslint-config/package"
+  },
+  "prettier": "@adonisjs/prettier-config",
+  "publishConfig": {
+    "access": "public",
+    "tag": "latest"
+  },
+  "np": {
+    "message": "chore(release): %s",
+    "tag": "latest",
+    "branch": "main",
+    "anyBranch": false
+  },
+  "c8": {
+    "reporter": [
+      "text",
+      "html"
+    ],
+    "exclude": [
+      "tests/**",
+      "tests_helpers/**"
+    ]
+  },
+  "tsup": {
+    "entry": [
+      "./index.ts",
+      "./src/types.ts",
+      "./providers/lock_provider.ts",
+      "./services/main.ts"
+    ],
+    "outDir": "./build",
+    "clean": true,
+    "format": "esm",
+    "dts": true,
+    "target": "esnext"
+  }
+}