@oscarpalmer/atoms 0.158.0 → 0.160.0

package/types/array/position.d.ts

@@ -0,0 +1,117 @@
+import type { PlainObject } from '../models';
+export type ArrayPosition = 'end' | 'inside' | 'invalid' | 'outside' | 'same' | 'start';
+/**
+ * Does the needle array end the haystack array?
+ * @param haystack Haystack array
+ * @param needle Needle array
+ * @param key Key to get an item's value for matching
+ * @return `true` if the haystack ends with the needle, otherwise `false`
+ */
+export declare function endsWithArray<Item extends PlainObject>(haystack: Item[], needle: Item[], key: keyof Item): boolean;
+/**
+ * Does the needle array end the haystack array?
+ * @param haystack Haystack array
+ * @param needle Needle array
+ * @param callback Callback to get an item's value for matching
+ * @return `true` if the haystack ends with the needle, otherwise `false`
+ */
+export declare function endsWithArray<Item>(haystack: Item[], needle: Item[], callback: (item: Item, index: number, array: Item[]) => unknown): boolean;
+/**
+ * Does the needle array end the haystack array?
+ * @param haystack Haystack array
+ * @param needle Needle array
+ * @return `true` if the haystack ends with the needle, otherwise `false`
+ */
+export declare function endsWithArray<Item>(haystack: Item[], needle: Item[]): boolean;
+/**
+ * Get the position of an array within another array
+ * @param haystack Haystack array
+ * @param needle Needle array
+ * @param key Key to get an item's value for matching
+ * @returns Position of the needle within the haystack
+ */
+export declare function getArrayPosition<Item extends PlainObject>(haystack: Item[], needle: Item[], key: keyof Item): ArrayPosition;
+/**
+ * Get the position of an array within another array
+ * @param haystack Haystack array
+ * @param needle Needle array
+ * @param callback Callback to get an item's value for matching
+ * @returns Position of the needle within the haystack
+ */
+export declare function getArrayPosition<Item>(haystack: Item[], needle: Item[], callback: (item: Item, index: number, array: Item[]) => unknown): ArrayPosition;
+/**
+ * Get the position of an array within another array
+ * @param haystack Haystack array
+ * @param needle Needle array
+ * @returns Position of the needle within the haystack
+ */
+export declare function getArrayPosition<Item>(haystack: Item[], needle: Item[]): ArrayPosition;
+/**
+ * Does the needle array exist within the haystack array?
+ * @param haystack Haystack array
+ * @param needle Needle array
+ * @param key Key to get an item's value for matching
+ * @return `true` if the haystack includes the needle, otherwise `false`
+ */
+export declare function includesArray<Item extends PlainObject>(haystack: Item[], needle: Item[], key: keyof Item): boolean;
+/**
+ * Does the needle array exist within the haystack array?
+ * @param haystack Haystack array
+ * @param needle Needle array
+ * @param callback Callback to get an item's value for matching
+ * @return `true` if the haystack includes the needle, otherwise `false`
+ */
+export declare function includesArray<Item>(haystack: Item[], needle: Item[], callback: (item: Item, index: number, array: Item[]) => unknown): boolean;
+/**
+ * Does the needle array exist within the haystack array?
+ * @param haystack Haystack array
+ * @param needle Needle array
+ * @return `true` if the haystack includes the needle, otherwise `false`
+ */
+export declare function includesArray<Item>(haystack: Item[], needle: Item[]): boolean;
+/**
+ * Get the index of an array within another array
+ * @param haystack Haystack array
+ * @param needle Needle array
+ * @param key Key to get an item's value for matching
+ * @return Index of the needle's start within the haystack, or `-1` if it is not found
+ */
+export declare function indexOfArray<Item extends PlainObject>(haystack: Item[], needle: Item[], key: keyof Item): number;
+/**
+ * Get the index of an array within another array
+ * @param haystack Haystack array
+ * @param needle Needle array
+ * @param callback Callback to get an item's value for matching
+ * @return Index of the needle's start within the haystack, or `-1` if it is not found
+ */
+export declare function indexOfArray<Item>(haystack: Item[], needle: Item[], callback: (item: Item, index: number, array: Item[]) => unknown): number;
+/**
+ * Get the index of an array within another array
+ * @param haystack Haystack array
+ * @param needle Needle array
+ * @return Index of the needle's start within the haystack, or `-1` if it is not found
+ */
+export declare function indexOfArray<Item>(haystack: Item[], needle: Item[]): number;
+/**
+ * Does the needle array start the haystack array?
+ * @param haystack Haystack array
+ * @param needle Needle array
+ * @param key Key to get an item's value for matching
+ * @return `true` if the haystack starts with the needle, otherwise `false`
+ */
+export declare function startsWithArray<Item extends PlainObject>(haystack: Item[], needle: Item[], key: keyof Item): boolean;
+/**
+ * Does the needle array start the haystack array?
+ * @param haystack Haystack array
+ * @param needle Needle array
+ * @param callback Callback to get an item's value for matching
+ * @return `true` if the haystack starts with the needle, otherwise `false`
+ */
+export declare function startsWithArray<Item>(haystack: Item[], needle: Item[], callback: (item: Item, index: number, array: Item[]) => unknown): boolean;
+/**
+ * Does the needle array start the haystack array?
+ * @param haystack Haystack array
+ * @param needle Needle array
+ * @return `true` if the haystack starts with the needle, otherwise `false`
+ */
+export declare function startsWithArray<Item>(haystack: Item[], needle: Item[]): boolean;

package/types/promise/helpers.d.ts

@@ -1,7 +1,9 @@
 import type { RequiredKeys } from '../models';
-import { type FulfilledPromise, type PromiseOptions, type PromisesOptions, type PromiseStrategy, type RejectedPromise } from './models';
+import type { Result } from '../result/models';
+import { type FulfilledPromise, type PromiseOptions, type PromisesOptions, type PromiseStrategy, type PromisesValue, type RejectedPromise } from './models';
 export declare function getPromiseOptions(input: unknown): RequiredKeys<PromiseOptions, 'time'>;
 export declare function getPromisesOptions(input: unknown): RequiredKeys<PromisesOptions, 'strategy'>;
+export declare function getResultsFromPromises<Value>(promised: PromisesValue<Value>[]): Result<Value>[];
 export declare function getStrategyOrDefault(value: unknown): PromiseStrategy;
 /**
  * Is the value a fulfilled promise result?

package/types/promise/index.d.ts

@@ -1,4 +1,5 @@
-import { type PromiseOptions, type Promises, type PromisesOptions, type PromisesResult } from './models';
+import type { Result } from '../result/models';
+import { type PromiseOptions, type PromisesItems, type PromisesOptions, type PromisesResult, type PromisesValue, type PromisesValues } from './models';
 /**
  * Wrap a promise with safety handlers, with optional abort capabilities and timeout
  * @param promise Promise to wrap
@@ -28,7 +29,25 @@ export declare function attemptPromise<Value>(callback: () => Value, options?: P
  * @param options Options for handling the promises
  * @returns List of results
  */
-export declare function promises<Items extends unknown[], Options extends PromisesOptions>(items: Promises<Items>, options?: Options): Promise<Options['strategy'] extends 'first' ? Items : PromisesResult<Items>>;
+export declare function promises<Items extends unknown[], Options extends PromisesOptions>(items: [...Items], options?: Options): Promise<Options['strategy'] extends 'first' ? Items : PromisesValues<PromisesItems<Items>>>;
+/**
+ * Handle a list of promises, returning their results in an ordered array.
+ *
+ * Depending on the strategy, the function will either reject on the first error encountered or return an array of rejected and resolved results
+ * @param items List of promises
+ * @param options Options for handling the promises
+ * @returns List of results
+ */
+export declare function promises<Value, Options extends PromisesOptions>(items: Promise<Value>[], options?: Options): Promise<Options['strategy'] extends 'first' ? Value[] : PromisesValue<Value>[]>;
+/**
+ * Handle a list of promises, returning their results in an ordered array.
+ *
+ * If any promise in the list is rejected, the whole function will reject
+ * @param items List of promises
+ * @param strategy Strategy for handling the promises; rejects on the first error encountered
+ * @returns List of results
+ */
+export declare function promises<Items extends unknown[]>(items: [...Items], strategy: 'first'): Promise<PromisesItems<Items>>;
 /**
  * Handle a list of promises, returning their results in an ordered array.
  *
@@ -37,17 +56,45 @@ export declare function promises<Items extends unknown[], Options extends Promis
  * @param strategy Strategy for handling the promises; rejects on the first error encountered
  * @returns List of results
  */
-export declare function promises<Items extends unknown[]>(items: Promises<Items>, strategy: 'first'): Promise<Items>;
+export declare function promises<Value>(items: Promise<Value>[], strategy: 'first'): Promise<Value[]>;
+/**
+ * Handle a list of promises, returning their results in an ordered array of rejected and resolved results
+ * @param items List of promises
+ * @param signal AbortSignal for aborting the operation _(when aborted, the promise will reject with the reason of the signal)_
+ * @returns List of results
+ */
+export declare function promises<Items extends unknown[]>(items: [...Items], signal?: AbortSignal): Promise<PromisesValues<PromisesItems<Items>>>;
 /**
  * Handle a list of promises, returning their results in an ordered array of rejected and resolved results
  * @param items List of promises
  * @param signal AbortSignal for aborting the operation _(when aborted, the promise will reject with the reason of the signal)_
  * @returns List of results
  */
-export declare function promises<Items extends unknown[]>(items: Promises<Items>, signal?: AbortSignal): Promise<PromisesResult<Items>>;
+export declare function promises<Value>(items: Promise<Value>[], signal?: AbortSignal): Promise<PromisesValue<Value>[]>;
+export declare namespace promises {
+    var result: typeof resultPromises;
+}
+/**
+ * Handle a list of promises, returning their results in an ordered array of results _({@link Result})_.
+ *
+ * Depending on the strategy, the function will either reject on the first error encountered or return an array of rejected and resolved results
+ * @param items List of promises
+ * @param signal AbortSignal for aborting the operation _(when aborted, the promise will reject with the reason of the signal)_
+ * @returns List of results
+ */
+declare function resultPromises<Items extends unknown[]>(items: [...Items], signal?: AbortSignal): Promise<PromisesResult<PromisesItems<Items>>>;
+/**
+ * Handle a list of promises, returning their results in an ordered array of results _({@link Result})_.
+ *
+ * Depending on the strategy, the function will either reject on the first error encountered or return an array of rejected and resolved results
+ * @param items List of promises
+ * @param signal AbortSignal for aborting the operation _(when aborted, the promise will reject with the reason of the signal)_
+ * @returns List of results
+ */
+declare function resultPromises<Value>(items: Promise<Value>[], signal?: AbortSignal): Promise<Result<Awaited<Value>>[]>;
 export { toPromise as fromResult } from '../result/misc';
 export { delay } from './delay';
 export { isFulfilled, isRejected } from './helpers';
 export { cancelable, toResult } from './misc';
-export { CancelablePromise, PromiseTimeoutError, type FulfilledPromise, type RejectedPromise, type PromiseOptions, type PromiseStrategy, type PromisesOptions, type PromisesResult, type PromisesResultItem, } from './models';
+export { CancelablePromise, PromiseTimeoutError, type FulfilledPromise, type PromiseOptions, type PromisesOptions, type PromisesResult, type PromiseStrategy, type PromisesValues as PromisesValue, type PromisesValue as PromisesValueItem, type RejectedPromise, } from './models';
 export { timed } from './timed';

package/types/promise/misc.d.ts

@@ -6,7 +6,7 @@ import { CancelablePromise, type PromiseParameters } from './models';
  * @returns Cancelable promise
  */
 export declare function cancelable<Value>(executor: (resolve: (value: Value) => void, reject: (reason: unknown) => void) => void): CancelablePromise<Value>;
-export declare function handleResult<Items extends unknown[]>(status: string, parameters: PromiseParameters<Items>): void;
+export declare function handleResult(status: string, parameters: PromiseParameters): void;
 export declare function settlePromise(aborter: () => void, settler: (value: any) => void, value: unknown, signal?: AbortSignal): void;
 /**
  * Converts a promise to a promised result

package/types/promise/models.d.ts

@@ -1,3 +1,4 @@
+import type { Result } from '../result/models';
 export declare class CancelablePromise<Value = void> extends Promise<Value> {
     #private;
     constructor(executor: (resolve: (value: Value) => void, reject: (reason: unknown) => void) => void);
@@ -9,14 +10,14 @@ export declare class CancelablePromise<Value = void> extends Promise<Value> {
 }
 export type FulfilledPromise<Value> = {
     status: typeof PROMISE_TYPE_FULFILLED;
-    value: Value;
+    value: Awaited<Value>;
 };
-export type PromiseData<Items extends unknown[]> = {
+export type PromiseData = {
     last: number;
-    result: Items | PromisesResult<Items>;
+    result: unknown[];
 };
-export type PromiseHandlers<Items extends unknown[]> = {
-    resolve: (value: Items | PromisesResult<Items>) => void;
+export type PromiseHandlers = {
+    resolve: (value: unknown[]) => void;
     reject: (reason: unknown) => void;
 };
 export type PromiseOptions = {
@@ -29,11 +30,11 @@ export type PromiseOptions = {
      */
     time?: number;
 };
-export type PromiseParameters<Items extends unknown[]> = {
+export type PromiseParameters = {
     abort: () => void;
     complete: boolean;
-    data: PromiseData<Items>;
-    handlers: PromiseHandlers<Items>;
+    data: PromiseData;
+    handlers: PromiseHandlers;
     index: number;
     signal?: AbortSignal;
     value?: unknown;
@@ -50,7 +51,7 @@ export type PromiseStrategy = 'complete' | 'first';
 export declare class PromiseTimeoutError extends Error {
     constructor();
 }
-export type Promises<Items extends unknown[]> = {
+export type PromisesItems<Items extends unknown[]> = {
     [K in keyof Items]: Promise<Items[K]>;
 };
 export type PromisesOptions = {
@@ -58,9 +59,12 @@ export type PromisesOptions = {
     strategy?: PromiseStrategy;
 };
 export type PromisesResult<Items extends unknown[]> = {
-    [K in keyof Items]: Items[K] extends Promise<infer Value> ? PromisesResultItem<Value> : never;
+    [K in keyof Items]: Items[K] extends Promise<infer Value> ? Result<Awaited<Value>> : never;
+};
+export type PromisesValue<Value> = FulfilledPromise<Value> | RejectedPromise;
+export type PromisesValues<Items extends unknown[]> = {
+    [K in keyof Items]: Items[K] extends Promise<infer Value> ? PromisesValue<Awaited<Value>> : never;
 };
-export type PromisesResultItem<Value> = FulfilledPromise<Value> | RejectedPromise;
 export type RejectedPromise = {
     status: typeof PROMISE_TYPE_REJECTED;
     reason: unknown;