@xylabs/promise 4.13.21 → 4.13.22

package/README.md

@@ -15,7 +15,7 @@
 
 Base functionality used throughout XY Labs TypeScript/JavaScript libraries
 
-## API Documentation
+## Reference
 
 **@xylabs/promise**
 

package/dist/neutral/index.d.ts

@@ -1,8 +1,66 @@
-export { fulfilled } from './fulfilled.ts';
-export { fulfilledValues } from './fulfilledValues.ts';
-export * from './isPromise.ts';
-export * from './PromiseEx.ts';
-export { rejected } from './rejected.ts';
-export * from './toPromise.ts';
-export * from './types.ts';
-//# sourceMappingURL=index.d.ts.map
+import { TypedValue } from '@xylabs/typeof';
+
+/**
+ * For use with Promise.allSettled to filter only successful results
+ * @param val
+ * @returns
+ */
+declare const fulfilled: <T>(val: PromiseSettledResult<T>) => val is PromiseFulfilledResult<T>;
+
+/**
+ * For use with Promise.allSettled to reduce to only successful result values
+ * @example <caption>Casting the initialValue provided to reduce</caption>
+ * const resolved = Promise.resolve('resolved')
+ * const rejected = Promise.reject('rejected')
+ * const settled = await Promise.allSettled([resolved, rejected])
+ * const results = settled.reduce(fulfilledValues, [] as string[])
+ * // results === [ 'resolved' ]
+ * @example <caption>Providing type parameter to reduce and initialValue type can be inferred</caption>
+ * const resolved = Promise.resolve('resolved')
+ * const rejected = Promise.reject('rejected')
+ * const settled = await Promise.allSettled([resolved, rejected])
+ * const results = settled.reduce<string[]>(fulfilledValues, [])
+ * // results === [ 'resolved' ]
+ * @param previousValue
+ * @param currentValue
+ * @returns
+ */
+declare const fulfilledValues: <T>(previousValue: T[], currentValue: PromiseSettledResult<T>) => T[];
+
+interface PromiseType {
+    then: () => unknown;
+}
+type AnyNonPromise = Exclude<TypedValue, PromiseType>;
+declare const isPromise: (value: unknown) => value is Promise<unknown>;
+
+type PromiseExSubFunc<T, TResult = T> = (value: T) => TResult;
+type PromiseExFunc<T> = (resolve?: PromiseExSubFunc<T, void>, reject?: PromiseExSubFunc<T, void>) => void;
+type PromiseExValueFunc<V> = (value?: V) => boolean;
+declare class PromiseEx<T, V = void> extends Promise<T> {
+    cancelled?: boolean;
+    private _value?;
+    constructor(func: PromiseExFunc<T>, value?: V);
+    then<TResult1 = T, TResult2 = never>(onfulfilled?: ((value: T) => TResult1 | PromiseLike<TResult1>) | null | undefined, onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null | undefined, onvalue?: (value?: V) => boolean): Promise<TResult1 | TResult2>;
+    value(onvalue?: (value?: V) => boolean): this;
+}
+
+/**
+ * For use with Promise.allSettled to filter only rejected results
+ * @param val
+ * @returns
+ */
+declare const rejected: <T>(val: PromiseSettledResult<T>) => val is PromiseRejectedResult;
+
+type Promisable<T, V = never> = PromiseEx<T, V> | Promise<T> | T;
+type PromisableArray<T, V = never> = Promisable<T[], V>;
+type OptionalPromisable<T, V = never> = Promisable<T | undefined, V>;
+type OptionalPromisableArray<T, V = never> = PromisableArray<T | undefined, V>;
+type NullablePromisable<T, V = never> = Promisable<T | null, V>;
+type NullablePromisableArray<T, V = never> = PromisableArray<T | null, V>;
+/** @description Used to document promises that are being used as Mutexes */
+type AsyncMutex<T> = Promise<T>;
+
+declare function toPromise<T>(value: Promisable<T>): Promise<T>;
+
+export { PromiseEx, fulfilled, fulfilledValues, isPromise, rejected, toPromise };
+export type { AnyNonPromise, AsyncMutex, NullablePromisable, NullablePromisableArray, OptionalPromisable, OptionalPromisableArray, Promisable, PromisableArray, PromiseExFunc, PromiseExSubFunc, PromiseExValueFunc, PromiseType };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xylabs/promise",
-  "version": "4.13.21",
+  "version": "4.13.22",
   "description": "Base functionality used throughout XY Labs TypeScript/JavaScript libraries",
   "keywords": [
     "promise",
@@ -41,11 +41,13 @@
     "dist",
     "src"
   ],
+  "dependencies": {
+    "@xylabs/typeof": "^4.13.22"
+  },
   "devDependencies": {
     "@xylabs/ts-scripts-yarn3": "^7.0.0",
     "@xylabs/tsconfig": "^7.0.0",
-    "@xylabs/typeof": "^4.13.21",
-    "@xylabs/vitest-extended": "^4.13.21",
+    "@xylabs/vitest-extended": "^4.13.22",
     "typescript": "^5.8.3",
     "vitest": "^3.2.4"
   },