alepha 0.8.1 → 0.9.0

package/datetime.d.ts

@@ -1,167 +1,141 @@
-import { Async, HookDescriptor, Logger } from "alepha";
+import * as _alepha_core0$1 from "alepha";
+import * as _alepha_core0 from "alepha";
+import { Alepha, Descriptor, KIND } from "alepha";
 import dayjs, { Dayjs, ManipulateType } from "dayjs";
 import dayjsDuration from "dayjs/plugin/duration.js";
 
-//#region src/helpers/Interval.d.ts
-declare class Interval {
-  private timer;
-  private readonly run;
-  private duration;
-  private options;
-  constructor(duration: number, options: IntervalDescriptorOptions);
-  /**
-  * Start the interval.
-  */
-  start(): Promise<void>;
-  /**
-  * Add time to the interval.
-  *
-  * @param amountMs
-  */
-  add(amountMs: number): Promise<void>;
-  /**
-  * Clear the interval.
-  */
-  clear(): void;
-}
-//#endregion
-//#region src/helpers/Timeout.d.ts
-declare class Timeout {
-  private timer;
-  private duration;
-  private readonly now;
-  private readonly callback;
-  constructor(now: number, duration: number, callback: () => void);
-  /**
-  * Add time to the timeout.
-  */
-  add(amountMs: number): void;
-  /**
-  * Clear the timeout.
-  */
-  clear(): void;
-  /**
-  * Start the timeout.
-  *
-  * @private
-  */
-  private start;
-}
-//#endregion
 //#region src/providers/DateTimeProvider.d.ts
+type DateTimeApi = typeof dayjs;
 type DateTime = dayjs.Dayjs;
 type Duration = dayjsDuration.Duration;
 type DurationLike = number | dayjsDuration.Duration | [number, ManipulateType];
 declare class DateTimeProvider {
-  protected log: Logger;
+  protected alepha: Alepha;
+  protected log: _alepha_core0$1.Logger;
   protected ref: DateTime | null;
   protected readonly timeouts: Timeout[];
   protected readonly intervals: Interval[];
   constructor();
-  protected readonly start: HookDescriptor<"start">;
-  protected readonly stop: HookDescriptor<"stop">;
   /**
-  * Create a new DateTime instance.
-  */
+   * Load Day.js plugins.
+   *
+   * You can override this method to add custom plugins.
+   */
+  protected plugins(api: DateTimeApi): void;
+  protected readonly start: _alepha_core0$1.HookDescriptor<"start">;
+  protected readonly stop: _alepha_core0$1.HookDescriptor<"stop">;
+  /**
+   * Create a new DateTime instance.
+   */
   of(date: string | number | Date | Dayjs | null | undefined): DateTime;
   /**
-  * Get the current date.
-  */
+   * Get the current date.
+   */
   now(): DateTime;
   /**
-  * Get the current date as a string.
-  *
-  * @param date
-  */
+   * Get the current date as a string.
+   *
+   * @param date
+   */
   toISOString(date?: Date | string | DateTime): string;
   /**
-  * Get the current date as a string.
-  */
+   * Get the current date as a string.
+   */
   nowISOString(): string;
   /**
-  * Get the current date as a string.
-  *
-  * @protected
-  */
+   * Get the current date as a string.
+   *
+   * @protected
+   */
   protected getCurrentDate(): DateTime;
   /**
-  * Create a new Duration instance.
-  */
+   * Create a new Duration instance.
+   */
   duration: (duration: DurationLike, unit?: ManipulateType) => Duration;
   isDurationLike(value: unknown): value is DurationLike;
   /**
-  * Return a promise that resolves after a next tick.
-  * It uses `setTimeout` with 0ms delay.
-  */
+   * Return a promise that resolves after the next tick.
+   * It uses `setTimeout` with 0 ms delay.
+   */
   tick(): Promise<void>;
   /**
-  * Wait for a certain duration.
-  *
-  * You can clear the timeout by using the `AbortSignal` API.
-  * Aborted signal will resolve the promise immediately, it does not reject it.
-  */
+   * Wait for a certain duration.
+   *
+   * You can clear the timeout by using the `AbortSignal` API.
+   * Aborted signal will resolve the promise immediately, it does not reject it.
+   */
   wait(duration: DurationLike, options?: {
     signal?: AbortSignal;
     now?: number;
   }): Promise<void>;
+  createInterval(run: () => unknown, distance: DurationLike): Interval;
   /**
-  * Run a callback after a certain duration.
-  */
-  timeout(callback: () => void, duration: DurationLike, now?: number): Timeout;
-  /**
-  * Create an interval.
-  *
-  * @param args
-  */
-  interval(args: IntervalDescriptorOptions): Interval;
+   * Run a callback after a certain duration.
+   */
+  createTimeout(callback: () => void, duration: DurationLike, now?: number): Timeout;
+  clearTimeout(timeout: Timeout): void;
   /**
-  * Run a function with a deadline.
-  */
+   * Run a function with a deadline.
+   */
   deadline<T>(fn: (signal: AbortSignal) => Promise<T>, duration: DurationLike): Promise<T>;
-  // Testing
   /**
-  * Add time to the current date.
-  */
+   * Add time to the current date.
+   */
   travel(duration: DurationLike, unit?: ManipulateType): Promise<void>;
   /**
-  * Stop the time.
-  */
+   * Stop the time.
+   */
   pause(): DateTime;
   /**
-  * Reset the reference date.
-  */
+   * Reset the reference date.
+   */
   reset(): void;
 }
+interface Interval {
+  timer?: any;
+  duration: number;
+  run: () => unknown;
+}
+interface Timeout {
+  now: number;
+  timer?: any;
+  duration: number;
+  callback: () => void;
+  clear: () => void;
+}
+//# sourceMappingURL=DateTimeProvider.d.ts.map
 //#endregion
 //#region src/descriptors/$interval.d.ts
 /**
-* Registers a new interval.
-*/
-declare const $interval: (options: IntervalDescriptorOptions) => Interval;
+ * Run a function periodically.
+ * It uses the `setInterval` internally.
+ * It starts by default when the context starts and stops when the context stops.
+ */
+declare const $interval: {
+  (options: IntervalDescriptorOptions): IntervalDescriptor;
+  [KIND]: typeof IntervalDescriptor;
+};
 interface IntervalDescriptorOptions {
   /**
-  * Whether to start the interval immediately.
-  *
-  * @default false
-  */
-  run?: boolean;
-  /**
-  * Whether to attach the interval to the context.
-  *
-  * Attached intervals are automatically started when the context starts and stopped when the context stops.
-  *
-  * @default true
-  */
-  attach?: boolean;
-  /**
-  * The interval handler.
-  */
-  handler: () => Async<void>;
-  /**
-  * The interval duration.
-  */
+   * The interval handler.
+   */
+  handler: () => unknown;
+  /**
+   * The interval duration.
+   */
   duration: DurationLike;
 }
+declare class IntervalDescriptor extends Descriptor<IntervalDescriptorOptions> {
+  protected readonly dateTimeProvider: DateTimeProvider;
+  called: number;
+  protected onInit(): void;
+}
+//# sourceMappingURL=$interval.d.ts.map
+//#endregion
+//#region src/index.d.ts
+declare const AlephaDateTime: _alepha_core0.ModuleDescriptor;
+//# sourceMappingURL=index.d.ts.map
+
 //#endregion
-export { $interval, DateTime, DateTimeProvider, Duration, DurationLike, Interval, IntervalDescriptorOptions, Timeout };
+export { $interval, AlephaDateTime, DateTime, DateTimeApi, DateTimeProvider, Duration, DurationLike, Interval, IntervalDescriptor, IntervalDescriptorOptions, Timeout };
 //# sourceMappingURL=index.d.ts.map

package/file.d.ts

@@ -1,9 +1,15 @@
 import { FileLike, StreamLike } from "alepha";
 
 //#region src/helpers/createFile.d.ts
-declare const createFile: (source: string | Buffer | ArrayBuffer | StreamLike, options?: {
+declare const createFile: (source: string | Buffer | ArrayBuffer | StreamLike | File, options?: {
   type?: string;
   name?: string;
+  size?: number;
+}) => FileLike;
+declare const createFileFromWebFile: (source: File, options?: {
+  type?: string;
+  name?: string;
+  size?: number;
 }) => FileLike;
 declare const createFileFromBuffer: (source: Buffer, options?: {
   type?: string;
@@ -12,6 +18,7 @@ declare const createFileFromBuffer: (source: Buffer, options?: {
 declare const createFileFromStream: (source: StreamLike, options?: {
   type?: string;
   name?: string;
+  size?: number;
 }) => FileLike & {
   _buffer: null | Buffer;
 };
@@ -20,27 +27,30 @@ declare const createFileFromUrl: (url: string, options?: {
   name?: string;
 }) => FileLike;
 /**
-* Converts a stream-like object to a Buffer.
-*/
+ * Converts a stream-like object to a Buffer.
+ */
 declare const streamToBuffer: (streamLike: StreamLike) => Promise<Buffer>;
 /**
-* Converts a Node.js Buffer to an ArrayBuffer.
-*/
+ * Converts a Node.js Buffer to an ArrayBuffer.
+ */
 declare const bufferToArrayBuffer: (buffer: Buffer) => ArrayBuffer;
 declare const isReadableStream: (obj: unknown) => obj is NodeJS.ReadableStream;
+//# sourceMappingURL=createFile.d.ts.map
 //#endregion
 //#region src/helpers/getContentType.d.ts
 /**
-* Can be used to get the content type of file based on its extension.
-*
-* Feel free to add more mime types in your project!
-*/
+ * Can be used to get the content type of file based on its extension.
+ *
+ * Feel free to add more mime types in your project!
+ */
 declare const mimeMap: Record<string, string>;
 /**
-* Returns the content type of file based on its filename.
-* @see {mimeMap}
-*/
+ * Returns the content type of file based on its filename.
+ * @see {mimeMap}
+ */
 declare const getContentType: (filename: string) => string;
+//# sourceMappingURL=getContentType.d.ts.map
+
 //#endregion
-export { bufferToArrayBuffer, createFile, createFileFromBuffer, createFileFromStream, createFileFromUrl, getContentType, isReadableStream, mimeMap, streamToBuffer };
+export { bufferToArrayBuffer, createFile, createFileFromBuffer, createFileFromStream, createFileFromUrl, createFileFromWebFile, getContentType, isReadableStream, mimeMap, streamToBuffer };
 //# sourceMappingURL=index.d.ts.map

package/lock/redis.d.ts

@@ -1,5 +1,6 @@
+import * as _alepha_core0 from "alepha";
+import { Logger } from "alepha";
 import { LockProvider } from "alepha/lock";
-import { Alepha, Logger } from "alepha";
 import { RedisProvider } from "alepha/redis";
 
 //#region src/providers/RedisLockProvider.d.ts
@@ -9,19 +10,18 @@ declare class RedisLockProvider implements LockProvider {
   set(key: string, value: string, nx?: boolean, px?: number): Promise<string>;
   del(...keys: string[]): Promise<void>;
 }
+//# sourceMappingURL=RedisLockProvider.d.ts.map
 //#endregion
 //#region src/index.d.ts
-// ---------------------------------------------------------------------------------------------------------------------
 /**
-* Plugin for Alepha that provides a locking mechanism.
-*
-* @see {@link RedisLockProvider}
-* @module alepha.lock.redis
-*/
-declare class AlephaLockRedis {
-  readonly name = "alepha.lock.redis";
-  readonly $services: (alepha: Alepha) => Alepha;
-}
+ * Plugin for Alepha that provides a locking mechanism.
+ *
+ * @see {@link RedisLockProvider}
+ * @module alepha.lock.redis
+ */
+declare const AlephaLockRedis: _alepha_core0.ModuleDescriptor;
+//# sourceMappingURL=index.d.ts.map
+
 //#endregion
 export { AlephaLockRedis, RedisLockProvider };
 //# sourceMappingURL=index.d.ts.map

package/lock.d.ts

@@ -1,160 +1,170 @@
-import { Alepha, AsyncFn, HookDescriptor, KIND, Logger, OPTIONS, Static, TObject, TString } from "alepha";
-import { TopicDescriptor, TopicProvider } from "alepha/topic";
+import * as _alepha_core1 from "alepha";
+import * as _alepha_core0$1 from "alepha";
+import * as _alepha_core0 from "alepha";
+import { AsyncFn, Descriptor, KIND, Static } from "alepha";
+import * as _alepha_topic0 from "alepha/topic";
+import { TopicProvider } from "alepha/topic";
 import { DateTime, DateTimeProvider, DurationLike, Timeout } from "alepha/datetime";
+import * as dayjs_plugin_duration0 from "dayjs/plugin/duration";
 
+//#region src/providers/LockProvider.d.ts
+/**
+ * Store Provider Interface
+ */
+declare abstract class LockProvider {
+  /**
+   * Set the string value of a key.
+   *
+   * @param key The key of the value to set.
+   * @param value The value to set.
+   * @param nx If set to true, the key will only be set if it does not already exist.
+   * @param px Set the specified expire time, in milliseconds.
+   */
+  abstract set(key: string, value: string, nx?: boolean, px?: number): Promise<string>;
+  /**
+   * Remove the specified keys.
+   *
+   * @param keys The keys to delete.
+   */
+  abstract del(...keys: string[]): Promise<void>;
+}
+//# sourceMappingURL=LockProvider.d.ts.map
+//#endregion
 //#region src/descriptors/$lock.d.ts
-declare const KEY = "LOCK";
 /**
-* Lock descriptor
-*
-* Make sure that only one instance of the handler is running at a time.
-*
-* When connected to a remote store, the lock is shared across all processes.
-*
-* @param options
-*/
+ * Lock descriptor
+ *
+ * Make sure that only one instance of the handler is running at a time.
+ *
+ * When connected to a remote store, the lock is shared across all processes.
+ *
+ * @param options
+ */
 declare const $lock: {
   <TFunc extends AsyncFn>(options: LockDescriptorOptions<TFunc>): LockDescriptor<TFunc>;
-  [KIND]: string;
+  [KIND]: typeof LockDescriptor;
 };
 interface LockDescriptorOptions<TFunc extends AsyncFn> {
   /**
-  * Function executed when the lock is acquired.
-  */
+   * Function executed when the lock is acquired.
+   */
   handler: TFunc;
   /**
-  * If true, the handler will wait for the lock to be released.
-  *
-  * @default false
-  */
+   * If true, the handler will wait for the lock to be released.
+   *
+   * To understand:
+   *
+   * ### wait = false
+   * You have 3 servers running scheduled tasks, you want to ensure that only one of them runs the task at a time.
+   * But you don't want the other servers to wait for the lock to be released before they run the task.
+   *
+   * Problem with not waiting:
+   * If the lock is released before a new late trigger, handler will be executed multiple times.
+   * Aka, if you have 3 servers but not clock synchronized.
+   *
+   * ### wait = true
+   * You have 3 servers running a migration script on startup, migration script must be run only once.
+   * You want to wait the end of migration for each server as they all require the migration to be completed.
+   *
+   *
+   * @default false
+   */
   wait?: boolean;
-  key?: string | ((...args: Parameters<TFunc>) => string);
-  maxDuration?: DurationLike;
-  gracePeriod?: (...args: Parameters<TFunc>) => DurationLike | undefined;
-}
-interface LockDescriptor<TFunc extends AsyncFn> {
-  [KIND]: typeof KEY;
-  [OPTIONS]: LockDescriptorOptions<TFunc>;
   /**
-  * Apply the lock.
-  *
-  * @param args
-  */
-  (...args: Parameters<TFunc>): Promise<void>;
-}
-//#endregion
-//#region src/providers/LockProvider.d.ts
-/**
-* Store Provider Interface
-*/
-declare abstract class LockProvider {
+   * Create you own unique key for the lock.
+   */
+  name?: string | ((...args: Parameters<TFunc>) => string);
   /**
-  * Set the string value of a key.
-  *
-  * @param key The key of the value to set.
-  * @param value The value to set.
-  * @param nx If set to true, the key will only be set if it does not already exist.
-  * @param px Set the specified expire time, in milliseconds.
-  */
-  abstract set(key: string, value: string, nx?: boolean, px?: number): Promise<string>;
+   * Lock timeout.
+   *
+   * @default 5 minutes
+   */
+  maxDuration?: DurationLike;
   /**
-  * Remove the specified keys.
-  *
-  * @param keys The keys to delete.
-  */
-  abstract del(...keys: string[]): Promise<void>;
+   * Additional lifetime of the lock after the handler has finished executing.
+   *
+   * This is useful to ensure that the lock is not released too early
+   *
+   * @default null
+   */
+  gracePeriod?: ((...args: Parameters<TFunc>) => DurationLike | undefined) | DurationLike;
 }
-//#endregion
-//#region src/providers/LockTopicProvider.d.ts
-declare class LockTopicProvider extends TopicProvider {}
-//#endregion
-//#region src/providers/LockDescriptorProvider.d.ts
-declare const envSchema: TObject<{
-  LOCK_PREFIX_KEY: TString;
+declare const envSchema: _alepha_core1.TObject<{
+  LOCK_PREFIX_KEY: _alepha_core1.TString;
 }>;
 declare module "alepha" {
   interface Env extends Partial<Static<typeof envSchema>> {}
 }
-declare class LockDescriptorProvider {
-  protected readonly alepha: Alepha;
+declare class LockDescriptor<TFunc extends AsyncFn> extends Descriptor<LockDescriptorOptions<TFunc>> {
+  protected readonly log: _alepha_core1.Logger;
+  protected readonly provider: LockProvider;
+  protected readonly env: {
+    LOCK_PREFIX_KEY: string;
+  };
   protected readonly dateTimeProvider: DateTimeProvider;
-  protected readonly lockProvider: LockProvider;
-  protected readonly lockTopicProvider: LockTopicProvider;
-  protected readonly log: Logger;
-  protected readonly env: Static<typeof envSchema>;
-  protected readonly id: string;
-  protected readonly locks: Map<string, LockDescriptorValue>;
-  protected readonly configure: HookDescriptor<"configure">;
-  protected readonly topicLockEnd: TopicDescriptor<{
-    payload: TObject<{
-      name: TString;
+  protected readonly id: `${string}-${string}-${string}-${string}-${string}`;
+  readonly maxDuration: dayjs_plugin_duration0.Duration;
+  protected readonly topicLockEnd: _alepha_topic0.TopicDescriptor<{
+    payload: _alepha_core1.TObject<{
+      name: _alepha_core1.TString;
     }>;
   }>;
-  protected prefixKey(key: string): string;
+  run(...args: Parameters<TFunc>): Promise<void>;
   /**
-  * Run the lock handler.
-  *
-  * @param value
-  * @param args
-  */
-  protected run(value: LockDescriptorValue, ...args: any[]): Promise<void>;
+   * Set the lock for the given key.
+   */
+  protected lock(key: string): Promise<LockResult>;
+  protected setGracePeriod(key: string, lock: LockResult, ...args: Parameters<TFunc>): Promise<void>;
   protected wait(key: string, maxDuration: DurationLike): Promise<void>;
-  /**
-  * Lock the key.
-  *
-  * @param key - The key to lock.
-  * @param item - The lock descriptor value.
-  */
-  protected lock(key: string, item: LockDescriptorValue): Promise<LockObject>;
-  protected parse(value: string): LockObject;
-}
-interface LockDescriptorValue {
-  options: LockDescriptorOptions<AsyncFn>;
-  key: (...args: any[]) => string;
-  maxDuration: DurationLike;
+  protected key(...args: Parameters<TFunc>): string;
+  protected parse(value: string): LockResult;
 }
-interface LockObject {
+interface LockResult {
   id: string;
   createdAt: DateTime;
   endedAt?: DateTime;
   response?: string;
 }
+//#endregion
+//#region src/providers/LockTopicProvider.d.ts
+declare abstract class LockTopicProvider extends TopicProvider {}
+//# sourceMappingURL=LockTopicProvider.d.ts.map
+
 //#endregion
 //#region src/providers/MemoryLockProvider.d.ts
 /**
-* A simple in-memory store provider.
-*/
+ * A simple in-memory store provider.
+ */
 declare class MemoryLockProvider implements LockProvider {
   protected readonly dateTimeProvider: DateTimeProvider;
-  protected readonly log: Logger;
+  protected readonly log: _alepha_core0$1.Logger;
   /**
-  * The in-memory store.
-  */
+   * The in-memory store.
+   */
   protected store: Record<string, string>;
   /**
-  * Timeouts used to expire keys.
-  */
+   * Timeouts used to expire keys.
+   */
   protected storeTimeout: Record<string, Timeout>;
   set(key: string, value: string, nx?: boolean, px?: number): Promise<string>;
   del(...keys: string[]): Promise<void>;
   private ttl;
 }
+//# sourceMappingURL=MemoryLockProvider.d.ts.map
 //#endregion
 //#region src/index.d.ts
-// ---------------------------------------------------------------------------------------------------------------------
 /**
-* Lock a resource for a certain period of time.
-*
-* This module provides a memory implementation of the lock provider.
-* You probably want to use an implementation like RedisLockProvider for distributed systems.
-*
-* @see {@link $lock}
-* @module alepha.lock
-*/
-declare class AlephaLock {
-  readonly name = "alepha.lock";
-  readonly $services: (alepha: Alepha) => Alepha;
-}
+ * Lock a resource for a certain period of time.
+ *
+ * This module provides a memory implementation of the lock provider.
+ * You probably want to use an implementation like RedisLockProvider for distributed systems.
+ *
+ * @see {@link $lock}
+ * @module alepha.lock
+ */
+declare const AlephaLock: _alepha_core0.ModuleDescriptor;
+//# sourceMappingURL=index.d.ts.map
+
 //#endregion
-export { $lock, AlephaLock, LockDescriptor, LockDescriptorOptions, LockDescriptorProvider, LockDescriptorValue, LockObject, LockProvider, LockTopicProvider, MemoryLockProvider };
+export { $lock, AlephaLock, LockDescriptor, LockDescriptorOptions, LockProvider, LockResult, LockTopicProvider, MemoryLockProvider };
 //# sourceMappingURL=index.d.ts.map