drimion 0.1.0

package/dist/kernel/libs/iterator.ts

@@ -0,0 +1,298 @@
+import type { IIterator, IIteratorConfig } from "../types/iterator.types";
+
+/**
+ * @description
+ * The `Iterator` class provides a way to traverse through a collection of items sequentially,
+ * without exposing the underlying data structure. It supports both forward and backward traversal,
+ * optional looping behavior, and methods to manipulate the underlying collection.
+ */
+export class Iterator<T> implements IIterator<T> {
+	private readonly items: Array<T>;
+	private readonly restartOnFinish: boolean;
+	private readonly returnCurrentOnReversion: boolean;
+	private currentIndex: number;
+	private lastCommand: "next" | "prev" | "none";
+
+	private constructor(config?: IIteratorConfig<T>) {
+		this.items = config?.initialData ?? [];
+		this.restartOnFinish = !!config?.restartOnFinish;
+		this.returnCurrentOnReversion = !!config?.returnCurrentOnReversion;
+		this.currentIndex = -1;
+		this.lastCommand = "none";
+	}
+
+	/**
+	 * @description
+	 * Creates a new `Iterator` instance from the provided configuration.
+	 *
+	 * @param config Optional configuration object.
+	 * @param config.initialData An initial array of items to iterate over.
+	 * @param config.returnCurrentOnReversion If `true`, the current item will be returned again before moving on when switching iteration direction.
+	 * @param config.restartOnFinish If `true`, when reaching the end of the items, iteration continues from the opposite end, looping the iteration indefinitely.
+	 *
+	 * @returns A new `Iterator` instance.
+	 */
+	public static create<U>(config?: IIteratorConfig<U>): Iterator<U> {
+		return new Iterator<U>(config);
+	}
+
+	/**
+	 * @description
+	 * Alias for `addToEnd` - adds a new item to the end of the collection.
+	 *
+	 * @param data The item to add.
+	 * @returns The current `Iterator` instance.
+	 */
+	public add(data: T): Iterator<T> {
+		return this.addToEnd(data);
+	}
+
+	/**
+	 * @description
+	 * Adds a new item to the end of the collection.
+	 *
+	 * @param data The item to add.
+	 * @returns The current `Iterator` instance.
+	 */
+	public addToEnd(data: T): Iterator<T> {
+		this.items.push(data);
+		return this;
+	}
+
+	/**
+	 * @description
+	 * Adds a new item to the start of the collection and resets the cursor to before the first element.
+	 *
+	 * @param data The item to add.
+	 * @returns The current `Iterator` instance.
+	 */
+	public addToStart(data: T): Iterator<T> {
+		this.currentIndex = -1;
+		this.items.unshift(data);
+		return this;
+	}
+
+	/**
+	 * @description
+	 * Removes all items from the collection.
+	 *
+	 * @returns The current `Iterator` instance.
+	 */
+	public clear(): Iterator<T> {
+		this.items.splice(0, this.total());
+		this.currentIndex = -1;
+		return this;
+	}
+
+	/**
+	 * @description
+	 * Creates a new Iterator instance with the same configuration and current state as the existing one.
+	 *
+	 * @returns A cloned Iterator instance.
+	 */
+	public clone(): IIterator<T> {
+		return Iterator.create({
+			initialData: this.toArray(),
+			restartOnFinish: this.restartOnFinish,
+			returnCurrentOnReversion: this.returnCurrentOnReversion,
+		});
+	}
+
+	/**
+	 * @description
+	 * Returns the first item in the collection without changing the current index.
+	 *
+	 * @returns The first item, or `undefined` if empty.
+	 */
+	public first(): T {
+		return this.items.at(0) as T;
+	}
+
+	/**
+	 * @description
+	 * Checks if there is another item after the current position.
+	 *
+	 * @returns `true` if another item is available after the current index, otherwise `false`.
+	 */
+	public hasNext(): boolean {
+		if (this.isEmpty()) return false;
+		return this.currentIndex + 1 < this.items.length;
+	}
+
+	/**
+	 * @description
+	 * Checks if there is another item before the current position.
+	 *
+	 * @returns `true` if another item is available before the current index, otherwise `false`.
+	 */
+	public hasPrev(): boolean {
+		if (this.isEmpty()) return false;
+		return this.currentIndex - 1 >= 0;
+	}
+
+	/**
+	 * @description
+	 * Checks if the iterator has no items.
+	 *
+	 * @returns `true` if there are no items, otherwise `false`.
+	 */
+	public isEmpty(): boolean {
+		return this.total() === 0;
+	}
+
+	/**
+	 * @description
+	 * Returns the last item in the collection without changing the current index.
+	 *
+	 * @returns The last item, or `undefined` if empty.
+	 */
+	public last(): T {
+		return this.items.at(-1) as T;
+	}
+
+	/**
+	 * @description
+	 * Moves the iterator forward and returns the next item.
+	 *
+	 * If `restartOnFinish` is `true` and the end is reached, iteration restarts from the beginning.
+	 * If `restartOnFinish` is `false` and the end is reached, returns `null`.
+	 *
+	 * @returns The next item, or `null` if no next item exists and looping is disabled.
+	 */
+	public next(): T {
+		if (this.hasNext()) {
+			if (this.lastCommand === "prev" && this.currentIndex === 0) {
+				this.lastCommand = "next";
+				return this.items[this.currentIndex] as T;
+			}
+			const nextIndex = this.currentIndex + 1;
+			this.currentIndex = nextIndex;
+			this.lastCommand = this.returnCurrentOnReversion ? "next" : "none";
+			return this.items[nextIndex] as T;
+		}
+		if (!this.restartOnFinish) return null as unknown as T;
+		this.toFirst();
+		return this.first();
+	}
+
+	/**
+	 * @description
+	 * Moves the iterator backward and returns the previous item.
+	 *
+	 * If `restartOnFinish` is `true` and the beginning is reached, iteration continues from the end.
+	 * If `restartOnFinish` is `false` and the beginning is reached, returns `null`.
+	 *
+	 * @returns The previous item, or `null` if no previous item exists and looping is disabled.
+	 */
+	public prev(): T {
+		if (this.hasPrev()) {
+			if (
+				this.lastCommand === "next" &&
+				this.currentIndex === this.total() - 1
+			) {
+				this.lastCommand = "prev";
+				return this.items[this.currentIndex] as T;
+			}
+			const prevIndex = this.currentIndex - 1;
+			this.currentIndex = prevIndex;
+			this.lastCommand = this.returnCurrentOnReversion ? "prev" : "none";
+			return this.items[prevIndex] as T;
+		}
+		if (!this.restartOnFinish) return null as unknown as T;
+		this.toLast();
+		return this.last();
+	}
+
+	/**
+	 * @description
+	 * Removes the first item from the collection.
+	 *
+	 * @returns The current `Iterator` instance.
+	 */
+	public removeFirst(): Iterator<T> {
+		if (this.currentIndex > 0) this.currentIndex -= 1;
+		this.items.shift();
+		return this;
+	}
+
+	/**
+	 * @description
+	 * Removes a specific item from the iterator's collection.
+	 *
+	 * If the item is found and removed, the current index is adjusted accordingly.
+	 *
+	 * @param item The item to be removed.
+	 */
+	public removeItem(item: T): void {
+		const index = this.items.findIndex(
+			(value) => JSON.stringify(item) === JSON.stringify(value),
+		);
+
+		if (index !== -1) {
+			this.items.splice(index, 1);
+			if (index >= this.currentIndex) this.prev();
+		}
+	}
+
+	/**
+	 * @description
+	 * Removes the last item from the collection.
+	 *
+	 * @returns The current `Iterator` instance.
+	 */
+	public removeLast(): Iterator<T> {
+		if (this.currentIndex >= this.total()) this.currentIndex -= 1;
+		this.items.pop();
+		return this;
+	}
+
+	/**
+	 * @description
+	 * Returns all items in the iterator as an array.
+	 *
+	 * @returns A copy of the internal array of items.
+	 */
+	public toArray(): Array<T> {
+		return [...this.items];
+	}
+
+	/**
+	 * @description
+	 * Moves the internal cursor to the start of the collection.
+	 *
+	 * @returns The current `Iterator` instance.
+	 */
+	public toFirst(): Iterator<T> {
+		if (this.currentIndex === 0 || this.currentIndex === -1) {
+			this.currentIndex = -1;
+			return this;
+		}
+		this.currentIndex = 0;
+		return this;
+	}
+
+	/**
+	 * @description
+	 * Moves the internal cursor to the end of the collection.
+	 *
+	 * @returns The current `Iterator` instance.
+	 */
+	public toLast(): Iterator<T> {
+		if (this.currentIndex === this.total() - 1 || this.currentIndex === -1) {
+			this.currentIndex = this.total();
+			return this;
+		}
+		this.currentIndex = this.total() - 1;
+		return this;
+	}
+
+	/**
+	 * @description
+	 * Returns the total number of items in the iterator.
+	 *
+	 * @returns The count of items in the underlying collection.
+	 */
+	public total(): number {
+		return this.items.length;
+	}
+}

package/dist/kernel/libs/result.ts

@@ -0,0 +1,252 @@
+import type { ICommand } from "../types/command.types";
+import type { IIterator } from "../types/iterator.types";
+import type {
+	IResult,
+	IResultExecuteFn,
+	IResultHook,
+	IResultObject,
+	IResultOption,
+} from "../types/result.types";
+import type { AnyObject } from "../types/utils.types";
+import { Iterator } from "./iterator";
+
+/**
+ * @description
+ * The `Result` class represents the outcome of an operation, encapsulating both the success or failure state.
+ *
+ * A `Result` instance can contain a payload (`data`), an error, and optional metadata for additional context.
+ * This pattern encourages explicit handling of operation success or failure, making your code more robust and expressive.
+ *
+ * @typeParam `T` - The type of the payload when the result is successful.
+ * @typeParam `D` - The type of the error when the result is a failure. Defaults to `string`.
+ * @typeParam `M` - The type of the metadata object. Defaults to an empty object `{}`.
+ *
+ */
+export class Result<T = void, D = string, M = AnyObject>
+	implements IResult<T, D, M>
+{
+	readonly #data: Readonly<T | null>;
+	readonly #error: Readonly<D | null>;
+	readonly #isError: Readonly<boolean>;
+	readonly #isSuccess: Readonly<boolean>;
+	readonly #metaData: Readonly<M>;
+
+	private constructor(isSuccess: boolean, data?: T, error?: D, metaData?: M) {
+		this.#data = data ?? null;
+		this.#error = error ?? null;
+		this.#isError = !isSuccess;
+		this.#isSuccess = isSuccess;
+		this.#metaData = metaData ?? ({} as M);
+	}
+
+	/**
+	 * @description
+	 * Creates a failure `Result` instance, optionally containing an error and metadata.
+	 *
+	 * @returns A `Result` instance representing failure.
+	 */
+	public static error<D = string, M = AnyObject, P = void>(
+		error?: D,
+		metaData?: M,
+	): IResult<P, D, M>;
+	public static error<D = string, M = AnyObject, T = void>(
+		error: D,
+		metaData?: M,
+	): IResult<T, D, M> {
+		const errorMessage =
+			typeof error !== "undefined" && error !== null
+				? error
+				: "void error. no message!";
+
+		const fail = new Result(
+			false,
+			null,
+			errorMessage,
+			metaData,
+		) as unknown as IResult<T, D, M>;
+
+		return Object.freeze(fail) as IResult<T, D, M>;
+	}
+
+	/**
+	 * @description
+	 * Combines multiple `Result` instances into a single `Result`.
+	 *
+	 * If any of the provided results is a failure, the combined `Result` is a failure.
+	 * If all results are successful, the combined `Result` is considered a success.
+	 *
+	 * @param results An array of `Result` instances to combine.
+	 * @returns A `Result` instance representing the combined outcome.
+	 */
+	public static combine<A = unknown, B = unknown, M = unknown>(
+		results: Array<IResult<unknown, unknown, unknown>>,
+	): IResult<A, B, M> {
+		const iterator = Result.iterate(results);
+		if (iterator.isEmpty()) {
+			return Result.error(
+				"No results provided on combine param" as B,
+			) as unknown as IResult<A, B, M>;
+		}
+
+		while (iterator.hasNext()) {
+			const currentResult = iterator.next();
+			if (currentResult.isError()) return currentResult as IResult<A, B, M>;
+		}
+
+		return iterator.first() as IResult<A, B, M>;
+	}
+
+	/**
+	 * @description
+	 * Retrieves the error of the `Result`. If the `Result` is a success, `error()` returns `null`.
+	 *
+	 * @returns The error `D` or `null` if the result is a success.
+	 */
+	public error(): D {
+		return this.#error as D;
+	}
+
+	/**
+	 * @description
+	 * Executes a command based on the result state. You can specify whether the command executes on success, failure, or both.
+	 * Optionally, you can provide data to the command if required.
+	 *
+	 * @param command An object implementing `ICommand` interface.
+	 * @returns An object with methods to configure command execution based on the `Result` state.
+	 */
+	public execute<X, Y>(command: ICommand<X, Y>): IResultExecuteFn<X, Y> {
+		return {
+			on: (
+				option: IResultOption,
+			): Promise<IResult<Y, string, AnyObject>> | undefined => {
+				if (option === "success" && this.isSuccess())
+					return command.execute(undefined as unknown as X);
+				if (option === "error" && this.isError())
+					return command.execute(undefined as unknown as X);
+			},
+			withData: (data: X): IResultHook<Y> => {
+				return {
+					on: (
+						option: IResultOption,
+					): Promise<IResult<Y, string, AnyObject>> | undefined => {
+						if (option === "success" && this.isSuccess())
+							return command.execute(data);
+						if (option === "error" && this.isError())
+							return command.execute(data);
+					},
+				};
+			},
+		};
+	}
+
+	/**
+	 * @description
+	 * Determines if the `Result` represents a failure state.
+	 *
+	 * @returns `true` if the result is a failure, `false` if it is a success.
+	 */
+	public isError(): boolean {
+		return this.#isError;
+	}
+
+	/**
+	 * @description
+	 * Checks if the `Result` payload is `null`.
+	 *
+	 * This can be useful for confirming the presence or absence of a value before proceeding.
+	 *
+	 * @returns `true` if the payload is `null`, `false` otherwise.
+	 */
+	public isNull(): boolean {
+		return this.#data === null || this.#isError;
+	}
+
+	/**
+	 * @description
+	 * Determines if the `Result` represents a success state.
+	 *
+	 * @returns `true` if the result is a success, `false` if it is a failure.
+	 */
+	public isSuccess(): boolean {
+		return this.#isSuccess;
+	}
+
+	/**
+	 * @description
+	 * Creates an iterator over a collection of `Result` instances. This allows sequential processing of multiple results.
+	 *
+	 * @param results An array of `Result` instances.
+	 * @returns An `Iterator` over the provided results.
+	 */
+	public static iterate<A, B, M>(
+		results?: Array<IResult<A, B, M>>,
+	): IIterator<IResult<A, B, M>> {
+		return Iterator.create<IResult<A, B, M>>({
+			initialData: results,
+			returnCurrentOnReversion: true,
+		});
+	}
+
+	/**
+	 * @description
+	 * Retrieves the metadata associated with the `Result`.
+	 *
+	 * @returns The metadata object `M`, or `{}` if no metadata was provided.
+	 */
+	public metaData(): M {
+		const metaData = this.#metaData;
+		return Object.freeze(metaData);
+	}
+
+	/**
+	 * @description
+	 * Creates a success `Result` instance, optionally containing data and metadata.
+	 *
+	 * @returns A `Result` instance representing success.
+	 */
+	public static success(): IResult<void>;
+	public static success<T, M = AnyObject, D = string>(
+		data: T,
+		metaData?: M,
+	): IResult<T, D, M>;
+	public static success<T, M = AnyObject, D = string>(
+		data?: T,
+		metaData?: M,
+	): IResult<T, D, M> {
+		const _data = typeof data === "undefined" ? null : data;
+		const ok = new Result(true, _data, null, metaData) as unknown as IResult<
+			T,
+			D,
+			M
+		>;
+		return Object.freeze(ok) as IResult<T, D, M>;
+	}
+
+	/**
+	 * @description
+	 * Converts the `Result` instance into a plain object for easier logging or serialization.
+	 *
+	 * @returns An object containing `isSuccess`, `isError`, `data`, `error`, and `metaData`.
+	 */
+	public toObject(): IResultObject<T, D, M> {
+		const metaData = {
+			isSuccess: this.#isSuccess,
+			isError: this.#isError,
+			data: this.#data as T | null,
+			error: this.#error as D | null,
+			metaData: this.#metaData as M,
+		};
+
+		return Object.freeze(metaData);
+	}
+
+	/**
+	 * @description
+	 * Retrieves the payload of the `Result`. If the `Result` is a failure, `value()` returns `null`.
+	 *
+	 * @returns The payload `T` or `null` if the result is a failure.
+	 */
+	public value(): T {
+		return this.#data as T;
+	}
+}