@tstdl/base 0.92.167 → 0.93.0

package/examples/api/streaming.js

@@ -11,7 +11,7 @@ import { compileClient } from '../../api/client/client.js';
 import { defineApi } from '../../api/index.js';
 import { apiController, configureApiServer } from '../../api/server/index.js';
 import { Application } from '../../application/application.js';
-import { CORE_LOGGER, configureTstdl, getGlobalInjector } from '../../core.js';
+import { provideInitializer, provideModules, provideSignalHandler } from '../../application/index.js';
 import { configureUndiciHttpClientAdapter } from '../../http/client/adapters/undici.adapter.js';
 import { configureHttpClient } from '../../http/client/module.js';
 import { HttpServerResponse } from '../../http/server/index.js';
@@ -24,9 +24,7 @@ import { decodeTextStream, encodeUtf8Stream } from '../../utils/encoding.js';
 import { getReadableStreamFromIterable, getReadableStreamIterable } from '../../utils/stream/index.js';
 import { cancelableTimeout, timeout } from '../../utils/timing.js';
 import { isDefined } from '../../utils/type-guards.js';
-configureTstdl();
 configureDefaultSignalsImplementation();
-const logger = getGlobalInjector().resolve(CORE_LOGGER);
 const streamingApiDefinition = defineApi({
     resource: 'streams', // /api/:version/users
     endpoints: {
@@ -66,23 +64,24 @@ let StreamingApi = class StreamingApi {
 StreamingApi = __decorate([
     apiController(streamingApiDefinition)
 ], StreamingApi);
-async function* counter() {
+async function* counter(cancellationSignal) {
     let currentNumber = 0;
-    while (Application.shutdownSignal.isUnset && (currentNumber < 10)) {
-        yield (`${++currentNumber}`).toString();
-        logger.info(`yield: "${currentNumber}"`);
-        await cancelableTimeout(1000, Application.shutdownSignal);
+    while (cancellationSignal.isUnset && (currentNumber < 10)) {
+        yield String(++currentNumber);
+        console.log(`yield: "${currentNumber}"`);
+        await cancelableTimeout(1000, cancellationSignal);
     }
 }
 const StreamingApiClient = compileClient(streamingApiDefinition);
 async function clientTest() {
+    const application = inject(Application);
     const streamingApiClient = inject(StreamingApiClient);
     await timeout(250); // allow server to start
-    const response = await streamingApiClient.echo(undefined, getReadableStreamFromIterable(counter()).pipeThrough(encodeUtf8Stream()));
+    const response = await streamingApiClient.echo(undefined, getReadableStreamFromIterable(counter(application.shutdownSignal)).pipeThrough(encodeUtf8Stream()));
     for await (const responseChunk of getReadableStreamIterable(response.pipeThrough(decodeTextStream()))) {
-        logger.info(`response: "${responseChunk}"\n`);
+        console.log(`response: "${responseChunk}"\n`);
     }
-    await Application.shutdown();
+    await application.shutdown();
 }
 function bootstrap() {
     configureNodeHttpServer();
@@ -90,7 +89,6 @@ function bootstrap() {
     configureUndiciHttpClientAdapter({ dispatcher: new Agent({ keepAliveMaxTimeout: 1 }) });
     configureHttpClient({ baseUrl: 'http://localhost:8000' });
 }
-Application.run({ bootstrap }, WebServerModule, clientTest);
 function eventsSource() {
     const events = new ServerSentEventsSource();
     void (async () => {
@@ -105,3 +103,8 @@ function eventsSource() {
     })().catch((error) => console.error(error));
     return events;
 }
+Application.run('Test', [
+    provideInitializer(bootstrap),
+    provideModules(WebServerModule, clientTest),
+    provideSignalHandler(),
+]);

package/examples/browser/basic.js

@@ -1,12 +1,12 @@
 import '../../polyfills.js';
 import { writeFile } from 'node:fs/promises';
-import { Application } from '../../application/index.js';
+import { Application, provideModules, provideSignalHandler } from '../../application/index.js';
 import { BrowserService } from '../../browser/browser.service.js';
 import { inject, injectAsync } from '../../injector/inject.js';
 import { Logger } from '../../logger/logger.js';
 import { timeout } from '../../utils/timing.js';
 async function main() {
-    const logger = inject(Logger).subModule('BROWSER');
+    const logger = inject(Logger, 'BROWSER');
     const browserService = await injectAsync(BrowserService);
     const browser = await browserService.newBrowser({ headless: false });
     const context = await browser.newContext();
@@ -20,4 +20,7 @@ async function main() {
     await page.navigate('file:///tmp/pdf.pdf');
     await page.waitForClose();
 }
-Application.run(main);
+Application.run('Test', [
+    provideModules(main),
+    provideSignalHandler(),
+]);

package/examples/document-management/main.js

@@ -9,7 +9,7 @@ import { configureAiService } from '../../ai/index.js';
 import { MockApiRequestTokenProvider } from '../../api/server/api-request-token.provider.js';
 import { configureApiServer } from '../../api/server/module.js';
 import { Application } from '../../application/application.js';
-import { configureTstdl } from '../../core.js';
+import { provideInitializer, provideModules, provideSignalHandler } from '../../application/index.js';
 import { DocumentManagementAuthorizationService } from '../../document-management/index.js';
 import { configureDocumentManagement } from '../../document-management/server/configure.js';
 import { DocumentCategoryTypeService, DocumentCollectionService, DocumentManagementAncillaryService, DocumentManagementApiController, DocumentRequestService } from '../../document-management/server/index.js';
@@ -83,7 +83,6 @@ AllowAllDocumentManagementAuthorizationService = __decorate([
 export { AllowAllDocumentManagementAuthorizationService };
 async function bootstrap() {
     const injector = inject(Injector);
-    configureTstdl();
     configureNodeHttpServer();
     configurePostgresQueue();
     configureLocalMessageBus();
@@ -154,4 +153,8 @@ async function main() {
     }
     console.log(`Collections: ${collections.map((collection) => collection.id).join(',')}`);
 }
-Application.run({ bootstrap }, main, WebServerModule);
+Application.run('DocumentManagementTest', [
+    provideInitializer(bootstrap),
+    provideModules(main, WebServerModule),
+    provideSignalHandler(),
+]);

package/examples/http/client.js

@@ -1,5 +1,6 @@
 import '../../polyfills.js';
 import { Application } from '../../application/application.js';
+import { provideModules, provideSignalHandler } from '../../application/index.js';
 import { configureUndiciHttpClientAdapter } from '../../http/client/adapters/undici.adapter.js';
 import { HttpClient } from '../../http/client/index.js';
 import { inject } from '../../injector/inject.js';
@@ -9,10 +10,13 @@ async function main() {
     const response = await httpClient.get('https://httpbin.org/anything/:whatever', {
         parameters: {
             whatever: 'foobar',
-            anotherParameter: 'hello-world'
-        }
+            anotherParameter: 'hello-world',
+        },
     });
     const body = await response.body.readAsJson();
     console.log(response.asObject(), body);
 }
-Application.run(main);
+Application.run('Test', [
+    provideModules(main),
+    provideSignalHandler(),
+]);

package/examples/mail/basic.js

@@ -1,6 +1,7 @@
 import { resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { Application } from '../../application/application.js';
+import { provideModules, provideSignalHandler } from '../../application/index.js';
 import { injectAsync } from '../../injector/inject.js';
 import { NodemailerMailClient } from '../../mail/clients/nodemailer.mail-client.js';
 import { MailService, configureMail } from '../../mail/index.js';
@@ -13,7 +14,6 @@ import { StringTemplateRenderer } from '../../templates/renderers/string.templat
 import { configureFileTemplateResolver } from '../../templates/resolvers/file.template-resolver.js';
 import { StringTemplateResolver } from '../../templates/resolvers/string.template-resolver.js';
 import { integer, string } from '../../utils/config-parser.js';
-import { configureTstdl } from '../../core.js';
 let dirname;
 try {
     dirname = fileURLToPath(new URL('.', import.meta.url));
@@ -21,22 +21,21 @@ try {
 catch {
     dirname = __dirname;
 }
-configureTstdl();
 configureMail({
     defaultClientConfig: {
         host: string('HOST', '127.0.0.01'),
         port: integer('PORT', 25),
         auth: {
             user: string('USER', 'user'),
-            password: string('PASS', 'password')
-        }
+            password: string('PASS', 'password'),
+        },
     },
-    client: NodemailerMailClient
+    client: NodemailerMailClient,
 });
 configureTemplates({
     templateProvider: FileTemplateProvider,
     templateRenderers: [MjmlTemplateRenderer, HandlebarsTemplateRenderer, JsxTemplateRenderer, StringTemplateRenderer],
-    templateResolvers: [StringTemplateResolver]
+    templateResolvers: [StringTemplateResolver],
 });
 configureFileTemplateProvider({ basePath: resolve(dirname, 'templates') });
 configureFileTemplateResolver({ basePath: resolve(dirname.replace('/dist', '/source'), 'templates') });
@@ -45,4 +44,7 @@ async function test() {
     const result = await service.sendTemplate('hello-name', { from: string('FROM', string('USER', 'user@example.com')), to: string('TO', 'user@example.com') }, { name: 'Max Mustermann' });
     console.log(result);
 }
-Application.run(test);
+Application.run('Test', [
+    provideModules(test),
+    provideSignalHandler(),
+]);

package/examples/pdf/basic.js

@@ -2,8 +2,8 @@ import { writeFileSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { Application } from '../../application/application.js';
+import { provideModules, provideSignalHandler } from '../../application/index.js';
 import { BrowserService } from '../../browser/browser.service.js';
-import { configureTstdl } from '../../core.js';
 import { inject } from '../../injector/inject.js';
 import { Injector } from '../../injector/injector.js';
 import { PdfService } from '../../pdf/pdf.service.js';
@@ -21,11 +21,10 @@ try {
 catch {
     dirname = __dirname;
 }
-configureTstdl();
 configureTemplates({
     templateProvider: FileTemplateProvider,
     templateResolvers: [FileTemplateResolver, StringTemplateResolver],
-    templateRenderers: [MjmlTemplateRenderer, HandlebarsTemplateRenderer, StringTemplateRenderer]
+    templateRenderers: [MjmlTemplateRenderer, HandlebarsTemplateRenderer, StringTemplateRenderer],
 });
 configureFileTemplateProvider({ basePath: resolve(dirname, 'templates') });
 configureFileTemplateResolver({ basePath: resolve(dirname.replace('dist', 'source'), 'templates') });
@@ -35,7 +34,7 @@ async function main() {
     const pdfService = await injector.resolveAsync(PdfService);
     const [result1, result2] = await Promise.all([
         pdfService.renderTemplate('hello-name', { name: 'Max Mustermann' }),
-        pdfService.renderUrl('https://google.de')
+        pdfService.renderUrl('https://google.de'),
     ]);
     console.log(`Resulting PDFs have ${result1.length} and ${result2.length} bytes.`);
     writeFileSync('/tmp/template.pdf', result1);
@@ -46,9 +45,12 @@ async function main() {
     const page2 = await context.newPage();
     await Promise.all([
         page1.navigate('file:///tmp/template.pdf'),
-        page2.navigate('file:///tmp/page.pdf')
+        page2.navigate('file:///tmp/page.pdf'),
     ]);
     await page1.waitForClose();
     await page2.waitForClose();
 }
-Application.run(main);
+Application.run('Test', [
+    provideModules(main),
+    provideSignalHandler(),
+]);

package/examples/template/basic.js

@@ -1,7 +1,7 @@
 import { resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { Application } from '../../application/application.js';
-import { configureTstdl } from '../../core.js';
+import { provideModules, provideSignalHandler } from '../../application/index.js';
 import { inject } from '../../injector/inject.js';
 import { configureTemplates, TemplateService } from '../../templates/index.js';
 import { configureFileTemplateProvider, FileTemplateProvider } from '../../templates/providers/file.template-provider.js';
@@ -18,11 +18,10 @@ try {
 catch {
     dirname = __dirname;
 }
-configureTstdl();
 configureTemplates({
     templateProvider: FileTemplateProvider,
     templateResolvers: [FileTemplateResolver, JsxTemplateResolver, StringTemplateResolver],
-    templateRenderers: [HandlebarsTemplateRenderer, JsxTemplateRenderer, StringTemplateRenderer]
+    templateRenderers: [HandlebarsTemplateRenderer, JsxTemplateRenderer, StringTemplateRenderer],
 });
 configureFileTemplateProvider({ basePath: resolve(dirname, 'templates') });
 configureFileTemplateResolver({ basePath: resolve(dirname.replace('dist', 'source'), 'templates') });
@@ -32,7 +31,10 @@ async function test() {
     const jsxResult = await templateService.render('hello-jsx', { name: 'Max Mustermann' });
     console.log({
         handlebars: handlebarsResult.fields,
-        jsx: jsxResult.fields
+        jsx: jsxResult.fields,
     });
 }
-Application.run(test);
+Application.run('Test', [
+    provideModules(test),
+    provideSignalHandler(),
+]);

package/http/client/http-client-request.d.ts

@@ -1,5 +1,4 @@
 import { type CancellationSignal } from '../../cancellation/index.js';
-import { dispose, type Disposable } from '../../disposable/index.js';
 import type { OneOrMany, Record, TypedOmit, UndefinableJson, UndefinableJsonObject } from '../../types/index.js';
 import { HttpForm, type HttpFormObject } from '../http-form.js';
 import { HttpHeaders, type HttpHeadersObject } from '../http-headers.js';
@@ -114,7 +113,7 @@ export declare class HttpClientRequest implements Disposable {
     get abortSignal(): CancellationSignal;
     constructor(url: string, method?: HttpMethod, options?: HttpClientRequestOptions);
     constructor(requestObject: HttpClientRequestObject);
-    [dispose](): void;
+    [Symbol.dispose](): void;
     /** Abort the request */
     abort(): void;
     clone(): HttpClientRequest;

package/http/client/http-client-request.js

@@ -1,5 +1,4 @@
 import { CancellationToken } from '../../cancellation/index.js';
-import { dispose } from '../../disposable/index.js';
 import { clone } from '../../utils/clone.js';
 import { objectEntries } from '../../utils/object/object.js';
 import { isArray, isBlob, isDefined, isString, isUint8Array, isUndefined } from '../../utils/type-guards.js';
@@ -107,7 +106,7 @@ export class HttpClientRequest {
         this.context = requestOptions.context ?? {};
         this.#abortToken = requestOptions.abortSignal?.createChild() ?? new CancellationToken();
     }
-    [dispose]() {
+    [Symbol.dispose]() {
         this.#abortToken.set();
         this.#abortToken.complete();
     }

package/http/server/http-server.d.ts

@@ -1,5 +1,3 @@
-import type { AsyncDisposable } from '../../disposable/index.js';
-import { disposeAsync } from '../../disposable/index.js';
 import type { HttpServerRequest, HttpServerResponse } from '../../http/server/index.js';
 export type HttpServerRequestContext<Context = unknown> = {
     request: HttpServerRequest;
@@ -12,5 +10,5 @@ export declare abstract class HttpServer<Context = unknown> implements AsyncIter
     abstract listen(port: number): Promise<void>;
     abstract close(timeout: number): Promise<void>;
     abstract [Symbol.asyncIterator](): AsyncIterator<HttpServerRequestContext<Context>>;
-    abstract [disposeAsync](): Promise<void>;
+    abstract [Symbol.asyncDispose](): Promise<void>;
 }

package/http/server/http-server.js

@@ -1,3 +1,2 @@
-import { disposeAsync } from '../../disposable/index.js';
 export class HttpServer {
 }

package/http/server/node/node-http-server.d.ts

@@ -1,5 +1,4 @@
 import * as Http from 'node:http';
-import { disposeAsync, type AsyncDisposable } from '../../../disposable/index.js';
 import { afterResolve } from '../../../injector/index.js';
 import { HttpServer, type HttpServerRequestContext } from '../http-server.js';
 export type NodeHttpServerContext = {
@@ -11,7 +10,7 @@ export declare class NodeHttpServer extends HttpServer<NodeHttpServerContext> im
     private untrackConnectedSockets?;
     get connectedSocketsCount(): number;
     [afterResolve](): void;
-    [disposeAsync](): Promise<void>;
+    [Symbol.asyncDispose](): Promise<void>;
     listen(port: number): Promise<void>;
     close(timeout: number): Promise<void>;
     [Symbol.asyncIterator](): AsyncIterator<HttpServerRequestContext<NodeHttpServerContext>>;

package/http/server/node/node-http-server.js

@@ -11,7 +11,6 @@ import { Writable } from 'node:stream';
 import { bindNodeCallback, share } from 'rxjs';
 import { match, P } from 'ts-pattern';
 import { CancellationToken } from '../../../cancellation/index.js';
-import { disposeAsync } from '../../../disposable/index.js';
 import { HttpHeaders } from '../../../http/http-headers.js';
 import { HttpQuery } from '../../../http/http-query.js';
 import { afterResolve, inject, Singleton } from '../../../injector/index.js';
@@ -38,7 +37,7 @@ let NodeHttpServer = NodeHttpServer_1 = class NodeHttpServer extends HttpServer
     [afterResolve]() {
         this.#httpServer.on('request', (request, response) => this.#requestIterable.feed({ request, response }));
     }
-    async [disposeAsync]() {
+    async [Symbol.asyncDispose]() {
         if (this.#httpServer.listening) {
             await this.close(3000);
             this.#requestIterable.end();

package/import.js

@@ -1,3 +1,3 @@
 export async function dynamicImport(id) {
-    return import(/* @vite-ignore */ id);
+    return await import(/* @vite-ignore */ id);
 }

package/injector/injector.d.ts

@@ -1,10 +1,10 @@
-import { type AsyncDisposable } from '../disposable/disposable.js';
 import type { OneOrMany, Record, TypedOmit } from '../types/index.js';
 import { type InjectOptions } from './inject.js';
 import { type ResolveArgument } from './interfaces.js';
 import { type Provider } from './provider.js';
 import { type InjectionToken } from './token.js';
 import type { RegistrationOptions, ResolveOptions } from './types.js';
+export type DisposeHandler = Disposable | AsyncDisposable | (() => PromiseLike<void> | void);
 export type ProvidersItem<T = any, A = any, D extends Record = Record> = Provider<T, A, D> & {
     provide: InjectionToken<T, A>;
     multi?: boolean;

package/injector/types.d.ts

@@ -1,8 +1,7 @@
 import type { CancellationSignal } from '../cancellation/index.js';
-import type { AsyncDisposeHandler } from '../disposable/async-disposer.js';
 import type { Record } from '../types/index.js';
 import type { ForwardRefTypeHint } from '../utils/object/forward-ref.js';
-import type { Injector, ProvidersItem } from './injector.js';
+import type { DisposeHandler, Injector, ProvidersItem } from './injector.js';
 import type { ResolveArgument } from './interfaces.js';
 import type { InjectionToken } from './token.js';
 /**
@@ -15,12 +14,12 @@ export type Lifecycle = 'transient' | 'resolution' | 'injector' | 'singleton';
 export type ResolveContext<D extends Record> = Pick<Injector, 'resolve' | 'resolveAll'> & {
     readonly data: ResolveContextData<D>;
     readonly cancellationSignal: CancellationSignal;
-    addDisposeHandler(handler: AsyncDisposeHandler): void;
+    addDisposeHandler(handler: DisposeHandler): void;
 };
 export type AfterResolveContext<D extends Record> = {
     readonly data: ResolveContextData<D>;
     readonly cancellationSignal: CancellationSignal;
-    addDisposeHandler(handler: AsyncDisposeHandler): void;
+    addDisposeHandler(handler: DisposeHandler): void;
 };
 export type Mapper<T = any, U = unknown> = (value: T) => U;
 export type ArgumentProvider<T = unknown, D extends Record = Record> = (context: ResolveContext<D>) => T;

package/lock/lock.d.ts

@@ -1,25 +1,24 @@
+import type { CancellationSignal } from '../cancellation/index.js';
 import type { Resolvable } from '../injector/index.js';
 import { resolveArgumentType } from '../injector/index.js';
-export type LockedFunction<R> = (controller: LockController) => R | Promise<R>;
-export type AcquireResult<Throw extends boolean> = Throw extends true ? LockController : (LockController | false);
-export type UsingResult<Throw extends boolean, R> = Throw extends true ? ({
+export type LockedFunction<R> = (controller: UseLockController) => R | Promise<R>;
+export type LockTryUseResult<R> = ({
     success: true;
     result: R;
-}) : ({
-    success: true;
-    result: R;
-} | {
+}) | ({
     success: false;
-    result: undefined;
+    result?: undefined;
 });
-export interface LockController {
+export interface UseLockController {
     /**
-     * whether the the lock is lost or not. Can happen for example if it couldn't be renewed
+     * Whether the the lock is lost or not. Can happen for example if it couldn't be renewed
      * because the network connection is lost (depending on implementation)
      */
     readonly lost: boolean;
+}
+export interface LockController extends UseLockController {
     /** manually release lock */
-    release(): void | Promise<void>;
+    release(): Promise<void>;
 }
 /** resource */
 export type LockArgument = string | {
@@ -27,22 +26,42 @@ export type LockArgument = string | {
     resource: string;
 };
 export declare abstract class Lock implements Resolvable<LockArgument> {
+    protected readonly cancellationSignal: CancellationSignal;
     readonly resource: string;
     readonly [resolveArgumentType]: LockArgument;
-    constructor(resource: string);
+    constructor(resource: string, cancellationSignal: CancellationSignal);
+    /**
+     * Tries to acquire a lock for the resource, it must be manually released.
+     * @param timeout How long to try to get a lock in milliseconds. If undefined, it tries only once.
+     * @returns A lock controller if successful, otherwise `false`.
+     */
+    tryAcquire(timeout?: number): Promise<LockController | false>;
+    /**
+     * Acquires a lock for the resource, it must be manually released.
+     * Throws an error if the lock cannot be acquired within the specified timeout.
+     * @param timeout How long to try to get a lock in milliseconds. If undefined, it tries forever.
+     */
+    acquire(timeout?: number): Promise<LockController>;
+    /**
+     * Tries to acquire a lock for the resource and releases it automatically after the provided function has returned or thrown.
+     * @param timeout How long to try to get a lock in milliseconds. If undefined, it tries only once.
+     * @param func Function to run when the lock is acquired.
+     * @returns A result object indicating success and containing the return value of the function.
+     */
+    tryUse<R>(timeout: number | undefined, func: LockedFunction<R>): Promise<LockTryUseResult<R>>;
     /**
-     * acquire a lock for the resource, it must be manually released
-     * @param timeout how long to try to get a lock. If undefined it's tries forever
-     * @param throwOnFail throw if resource is locked and we couldn't acquire it in the specified timeout
+     * Acquires a lock for the resource and releases it automatically after the provided function has returned or thrown.
+     * Throws an error if the lock cannot be acquired within the specified timeout.
+     * @param timeout How long to try to get a lock in milliseconds. If undefined, it tries forever.
+     * @param func Function to run when the lock is acquired.
+     * @returns The return value of the function.
      */
-    abstract acquire<Throw extends boolean>(timeout: number | undefined, throwOnFail: Throw): Promise<AcquireResult<Throw>>;
+    use<R>(timeout: number | undefined, func: LockedFunction<R>): Promise<R>;
     /**
-     * acquire a lock for the resource and release it automatically after the provided function has returned or thrown
-     * @param timeout how long to try to get a lock. If undefined it's tries forever
-     * @param throwOnFail throw if resource is locked and we couldn't acquire it in the specified timeout
-     * @param func function to run when lock is acquired
+     * try to acquire the lock for the resource, returns a controller if successful
+     * returns false if the lock is already held by another process
      */
-    abstract use<Throw extends boolean, R>(timeout: number | undefined, throwOnFail: Throw, func: LockedFunction<R>): Promise<UsingResult<Throw, R>>;
+    abstract tryAcquireOnce(): Promise<LockController | false>;
     /** check if resource is locked */
     abstract exists(): Promise<boolean>;
 }

package/lock/lock.js

@@ -1,7 +1,80 @@
 import { resolveArgumentType } from '../injector/index.js';
+import { Timer } from '../utils/timer.js';
+import { cancelableTimeout } from '../utils/timing.js';
+import { isUndefined } from '../utils/type-guards.js';
 export class Lock {
+    cancellationSignal;
     resource;
-    constructor(resource) {
+    constructor(resource, cancellationSignal) {
+        this.cancellationSignal = cancellationSignal;
         this.resource = resource;
     }
+    /**
+     * Tries to acquire a lock for the resource, it must be manually released.
+     * @param timeout How long to try to get a lock in milliseconds. If undefined, it tries only once.
+     * @returns A lock controller if successful, otherwise `false`.
+     */
+    async tryAcquire(timeout) {
+        if (isUndefined(timeout) || (timeout <= 0)) {
+            return await this.tryAcquireOnce();
+        }
+        const delay = Math.max(50, Math.min(1000, timeout / 10));
+        const timer = new Timer(true);
+        do {
+            const result = await this.tryAcquireOnce();
+            if (result !== false) {
+                return result;
+            }
+            const delayResult = await cancelableTimeout(delay, this.cancellationSignal);
+            if (delayResult == 'canceled') {
+                break;
+            }
+        } while (timer.milliseconds < timeout);
+        return false;
+    }
+    /**
+     * Acquires a lock for the resource, it must be manually released.
+     * Throws an error if the lock cannot be acquired within the specified timeout.
+     * @param timeout How long to try to get a lock in milliseconds. If undefined, it tries forever.
+     */
+    async acquire(timeout) {
+        const result = await this.tryAcquire(timeout);
+        if (result === false) {
+            throw new Error(`Failed to acquire lock for resource '${this.resource}'.`);
+        }
+        return result;
+    }
+    /**
+     * Tries to acquire a lock for the resource and releases it automatically after the provided function has returned or thrown.
+     * @param timeout How long to try to get a lock in milliseconds. If undefined, it tries only once.
+     * @param func Function to run when the lock is acquired.
+     * @returns A result object indicating success and containing the return value of the function.
+     */
+    async tryUse(timeout, func) {
+        const controller = await this.tryAcquire(timeout);
+        if (controller == false) {
+            return { success: false, result: undefined };
+        }
+        try {
+            const result = await func(controller);
+            return { success: true, result };
+        }
+        finally {
+            await controller.release();
+        }
+    }
+    /**
+     * Acquires a lock for the resource and releases it automatically after the provided function has returned or thrown.
+     * Throws an error if the lock cannot be acquired within the specified timeout.
+     * @param timeout How long to try to get a lock in milliseconds. If undefined, it tries forever.
+     * @param func Function to run when the lock is acquired.
+     * @returns The return value of the function.
+     */
+    async use(timeout, func) {
+        const result = await this.tryUse(timeout, func);
+        if (!result.success) {
+            throw new Error(`Failed to acquire lock for resource '${this.resource}'.`);
+        }
+        return result.result;
+    }
 }

package/lock/postgres/drizzle/0000_busy_tattoo.sql

@@ -0,0 +1,7 @@
+CREATE TABLE "lock"."lock" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"resource" text NOT NULL,
+	"key" text NOT NULL,
+	"expiration" timestamp with time zone NOT NULL,
+	CONSTRAINT "lock_resource_unique" UNIQUE("resource")
+);