@everyonesoftware/common 2.0.0 → 4.0.0

package/package.json

@@ -1,11 +1,19 @@
 {
   "name": "@everyonesoftware/common",
-  "version": "2.0.0",
+  "version": "4.0.0",
   "description": "A package containing common code for everyonesoftware projects.",
+  "repository": {
+    "url": "https://github.com/everyonesoftware/common-typescript"
+  },
   "type": "module",
   "publishConfig": {
     "access": "public"
   },
+  "files": [
+    "outputs/",
+    "README.md",
+    "package.json"
+  ],
   "exports": {
     ".": {
       "types": "./outputs/sources.d.ts",
@@ -21,7 +29,8 @@
   "scripts": {
     "build": "barrelsby --directory sources --delete && tsup",
     "clean": "rimraf coverage outputs",
-    "test": "npm run build && c8 node -r source-map-support/register outputs/tests.js"
+    "test-only": "c8 node -r source-map-support/register outputs/tests.js",
+    "test": "npm run build && npm run test-only"
   },
   "dependencies": {
     "luxon": "3.7.2"

package/.c8rc.json

@@ -1,12 +0,0 @@
-{
-    "all": true,
-    "src": [
-        "sources"
-    ],
-    "temp-directory": "coverage/temp",
-    "report-dir": "coverage",
-    "reporter": [
-        "lcov",
-        "html"
-    ]
-}

package/.github/workflows/publish.yml

@@ -1,36 +0,0 @@
-name: Build, Test, and Publish
-
-on:
-  push:
-    branches:
-      - main
-
-jobs:
-  build-test-publish:
-    runs-on: ubuntu-latest
-
-    permissions:
-      contents: read
-
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@v5
-
-      - name: Setup Node.js
-        uses: actions/setup-node@v5
-        with:
-          node-version: 22
-          registry-url: 'https://registry.npmjs.org'
-          cache: 'npm'
-
-      - name: Install dependencies
-        run: npm ci
-
-      - name: Build
-        run: npm run build
-
-      - name: Run tests
-        run: npm test
-
-      - name: Publish to NPM
-        run: npm publish

package/.mocharc.json

@@ -1,9 +0,0 @@
-{
-    "color": true,
-    "ui": "tdd",
-    "extension": [
-        "ts"
-    ],
-    "spec": "tests/**/*.ts",
-    "require": "ts-node/register"
-}

package/sources/assertMessageParameters.ts

@@ -1,22 +0,0 @@
-/**
- * A collection of parameters that can be passed to an assert error message function.
- */
-export interface AssertMessageParameters
-{
-    /**
-     * The expected state.
-     */
-    expected: string,
-    /**
-     * The actual state.
-     */
-    actual: string,
-    /**
-     * A string representation of the expression that produced the actual state.
-     */
-    expression?: string,
-    /**
-     * A message that describes the failure.
-     */
-    message?: string,
-}

package/sources/asyncIterator.ts

@@ -1,437 +0,0 @@
-import { AsyncIteratorToJavascriptAsyncIteratorAdapter } from "./asyncIteratorToJavascriptAsyncIteratorAdapter";
-import { PromiseAsyncResult } from "./promiseAsyncResult";
-import { Comparable } from "./comparable";
-import { EmptyError } from "./emptyError";
-import { JavascriptAsyncIterator } from "./javascript";
-import { JavascriptAsyncIteratorToAsyncIteratorAdapter } from "./javascriptAsyncIteratorToAsyncIteratorAdapter";
-import { MapAsyncIterator } from "./mapAsyncIterator";
-import { NotFoundError } from "./notFoundError";
-import { PreCondition } from "./preCondition";
-import { SkipAsyncIterator } from "./skipAsyncIterator";
-import { TakeAsyncIterator } from "./takeAsyncIterator";
-import { instanceOfType, isJavascriptAsyncIterator, isUndefinedOrNull, Type } from "./types";
-import { WhereAsyncIterator } from "./whereAsyncIterator";
-
-/**
- * A type that can be used to asynchronously iterate over a collection.
- */
-export abstract class AsyncIterator<T>
-{
-    public static create<T>(iterator: JavascriptAsyncIterator<T>): AsyncIterator<T>
-    {
-        return JavascriptAsyncIteratorToAsyncIteratorAdapter.create(iterator);
-    }
-
-    /**
-     * Move to the next value in the collection. Return whether this {@link AsyncIterator} points to
-     * a value after the move.
-     */
-    public abstract next(): PromiseAsyncResult<boolean>;
-
-    /**
-     * Get whether this {@link AsyncIterator} has started iterating over the values in the collection.
-     */
-    public abstract hasStarted(): boolean;
-
-    /**
-     * Get whether this {@link AsyncIterator} currently points at a value in the collection.
-     */
-    public abstract hasCurrent(): boolean;
-
-    /**
-     * Get the value that this {@link AsyncIterator} points to.
-     */
-    public abstract getCurrent(): T;
-
-    /**
-     * Move to the first value if this {@link AsyncIterator} hasn't started yet.
-     * @returns This object for method chaining.
-     */
-    public start(): PromiseAsyncResult<this>
-    {
-        return AsyncIterator.start(this);
-    }
-
-    /**
-     * Move the provided {@link AsyncIterator} to its first value if it hasn't started yet.
-     */
-    public static start<T, TIterator extends AsyncIterator<T>>(iterator: TIterator): PromiseAsyncResult<TIterator>
-    {
-        PreCondition.assertNotUndefinedAndNotNull(iterator, "iterator");
-
-        return PromiseAsyncResult.create(async () =>
-        {
-            if (!iterator.hasStarted())
-            {
-                await iterator.next();
-            }
-            return iterator;
-        });
-    }
-
-    /**
-     * Get the current value from this {@link AsyncIterator} and advance this {@link AsyncIterator} to the
-     * next value.
-     */
-    public takeCurrent(): PromiseAsyncResult<T>
-    {
-        return AsyncIterator.takeCurrent(this);
-    }
-
-    public static takeCurrent<T>(iterator: AsyncIterator<T>): PromiseAsyncResult<T>
-    {
-        PreCondition.assertNotUndefinedAndNotNull(iterator, "iterator");
-        PreCondition.assertTrue(iterator.hasCurrent(), "iterator.hasCurrent()");
-
-        return PromiseAsyncResult.create(async () =>
-        {
-            const result: T = iterator.getCurrent();
-            await iterator.next();
-            return result;
-        });
-    }
-
-    public [Symbol.asyncIterator](): JavascriptAsyncIterator<T>
-    {
-        return AsyncIterator[Symbol.asyncIterator](this);
-    }
-
-    /**
-     * Convert the provided {@link AsyncIterator} to a {@link IteratorToJavascriptIteratorAdapter}.
-     * @param iterator The {@link AsyncIterator} to convert.
-     */
-    public static [Symbol.asyncIterator]<T>(iterator: AsyncIterator<T>): JavascriptAsyncIterator<T>
-    {
-        PreCondition.assertNotUndefinedAndNotNull(iterator, "iterator");
-
-        return AsyncIteratorToJavascriptAsyncIteratorAdapter.create(iterator);
-    }
-
-    /**
-     * Get whether this {@link AsyncIterator} contains any values.
-     * Note: This may advance the {@link AsyncIterator} to the first value if it hasn't been
-     * started yet.
-     */
-    public any(): PromiseAsyncResult<boolean>
-    {
-        return AsyncIterator.any(this);
-    }
-
-    /**
-     * Get whether this {@link AsyncIterator} contains any values.
-     * Note: This may advance the {@link AsyncIterator} to the first value if it hasn't been
-     * started yet.
-     */
-    public static any<T>(iterator: AsyncIterator<T>): PromiseAsyncResult<boolean>
-    {
-        PreCondition.assertNotUndefinedAndNotNull(iterator, "iterator");
-
-        return PromiseAsyncResult.create(async () =>
-        {
-            await iterator.start();
-            return iterator.hasCurrent();
-        });
-
-    }
-
-    /**
-     * Get the number of values in this {@link AsyncIterator}.
-     * Note: This will consume all of the values in this {@link AsyncIterator}.
-     */
-    public getCount(): PromiseAsyncResult<number>
-    {
-        return AsyncIterator.getCount(this);
-    }
-
-    /**
-     * Get the number of values in the provided {@link AsyncIterator}.
-     * Note: This will consume all of the values in the provided {@link AsyncIterator}.
-     */
-    public static getCount<T>(iterator: AsyncIterator<T>): PromiseAsyncResult<number>
-    {
-        PreCondition.assertNotUndefinedAndNotNull(iterator, "iterator");
-
-        return PromiseAsyncResult.create(async () =>
-        {
-            let result: number = 0;
-            if (iterator.hasCurrent())
-            {
-                result++;
-            }
-            while (await iterator.next())
-            {
-                result++;
-            }
-            return result;
-        });
-    }
-
-    /**
-     * Get all of the remaining values in this {@link AsyncIterator} in a {@link T} {@link Array}.
-     */
-    public toArray(): PromiseAsyncResult<T[]>
-    {
-        return AsyncIterator.toArray(this);
-    }
-
-    /**
-     * Get all of the remaining values in the provided {@link AsyncIterator} in a {@link T}
-     * {@link Array}.
-     */
-    public static toArray<T>(iterator: AsyncIterator<T>): PromiseAsyncResult<T[]>
-    {
-        PreCondition.assertNotUndefinedAndNotNull(iterator, "iterator");
-
-        return PromiseAsyncResult.create(async () =>
-        {
-            const result: T[] = [];
-
-            if (iterator.hasCurrent())
-            {
-                result.push(iterator.getCurrent());
-            }
-            while (await iterator.next())
-            {
-                result.push(iterator.getCurrent());
-            }
-
-            return result;
-        });
-    }
-
-    /**
-     * Get an {@link AsyncIterator} that will only return values that match the provided condition.
-     * @param condition The condition to run against each of the values in this {@link AsyncIterator}.
-     */
-    public where(condition: (value: T) => (boolean | PromiseLike<boolean>)): AsyncIterator<T>
-    {
-        return AsyncIterator.where(this, condition);
-    }
-
-    public static where<T>(iterator: AsyncIterator<T>, condition: (value: T) => (boolean | PromiseLike<boolean>)): AsyncIterator<T>
-    {
-        PreCondition.assertNotUndefinedAndNotNull(iterator, "iterator");
-        PreCondition.assertNotUndefinedAndNotNull(condition, "condition");
-
-        return WhereAsyncIterator.create(iterator, condition);
-    }
-
-    /**
-     * Get a {@link MapIterator} that will map all {@link T} values from this {@link AsyncIterator} to
-     * {@link TOutput} values.
-     * @param mapping The mapping that maps {@link T} values to {@link TOutput} values.
-     */
-    public map<TOutput>(mapping: (value: T) => (TOutput | PromiseLike<TOutput>)): AsyncIterator<TOutput>
-    {
-        return AsyncIterator.map(this, mapping);
-    }
-
-    public static map<T, TOutput>(iterator: AsyncIterator<T>, mapping: (value: T) => (TOutput | PromiseLike<TOutput>)): AsyncIterator<TOutput>
-    {
-        PreCondition.assertNotUndefinedAndNotNull(iterator, "iterator");
-        PreCondition.assertNotUndefinedAndNotNull(mapping, "mapping");
-
-        return MapAsyncIterator.create(iterator, mapping);
-    }
-
-    /**
-     * Get an {@link AsyncIterator} that will filter this {@link AsyncIterator} to only the values that are
-     * instances of {@link U} based on the provided type check {@link Function}.
-     * @param typeCheck The {@link Function} that will be used to determine if values are of type
-     * {@link U}.
-     */
-    public whereInstanceOf<U extends T>(typeCheck: (value: T) => value is U): AsyncIterator<U>
-    {
-        return AsyncIterator.whereInstanceOf(this, typeCheck);
-    }
-
-    public static whereInstanceOf<T, U extends T>(iterator: AsyncIterator<T>, typeCheck: (value: T) => value is U): AsyncIterator<U>
-    {
-        PreCondition.assertNotUndefinedAndNotNull(typeCheck, "typeCheck");
-
-        return iterator.where(typeCheck)
-            .map((value: T) => value as U);
-    }
-
-    /**
-     * Get an {@link AsyncIterator} that will filter this {@link AsyncIterator} to only the values that are
-     * instances of the provided {@link Type}.
-     * @param type The type of values to return from the new {@link AsyncIterator}.
-     */
-    public whereInstanceOfType<U extends T>(type: Type<U>): AsyncIterator<U>
-    {
-        return AsyncIterator.whereInstanceOfType(this, type);
-    }
-
-    public static whereInstanceOfType<T, U extends T>(iterator: AsyncIterator<T>, type: Type<U>): AsyncIterator<U>
-    {
-        PreCondition.assertNotUndefinedAndNotNull(type, "type");
-
-        return iterator.whereInstanceOf((value: T) => instanceOfType(value, type));
-    }
-
-    /**
-     * If the condition function is undefined, then this function will return the first value in
-     * this {@link AsyncIterator}. If this condition function is provided, then this function will return
-     * the first value that matches the provided condition.
-     * @param condition The condition that the returned value must satisfy.
-     */
-    public first(condition?: (value: T) => boolean): PromiseAsyncResult<T>
-    {
-        return AsyncIterator.first(this, condition);
-    }
-
-    /**
-     * If the condition function is undefined, then this function will return the first value in
-     * the {@link AsyncIterator}. If this condition function is provided, then this function will return
-     * the first value that matches the provided condition.
-     * @param iterator The {@link AsyncIterator} to get the first value from.
-     */
-    public static first<T>(iterator: AsyncIterator<T>, condition?: (value: T) => (boolean | PromiseLike<boolean>)): PromiseAsyncResult<T>
-    {
-        PreCondition.assertNotUndefinedAndNotNull(iterator, "iterator");
-
-        return PromiseAsyncResult.create(async () =>
-        {
-            await iterator.start();
-            if (isUndefinedOrNull(condition))
-            {
-                if (!iterator.hasCurrent())
-                {
-                    throw new EmptyError();
-                }
-            }
-            else
-            {
-                while (iterator.hasCurrent() && !await condition(iterator.getCurrent()))
-                {
-                    await iterator.next();
-                }
-
-                if (!iterator.hasCurrent())
-                {
-                    throw new NotFoundError("No value was found in the AsyncIterator that matched the provided condition.");
-                }
-            }
-            return iterator.getCurrent();
-        });
-    }
-
-    /**
-     * If the condition function is undefined, then this function will return the last value in this
-     * {@link AsyncIterator}. If this condition function is provided, then this function will return the
-     * last value that matches the provided condition.
-     * @param condition The condition that the returned value must satisfy.
-     */
-    public last(condition?: (value: T) => (boolean | PromiseLike<boolean>)): PromiseAsyncResult<T>
-    {
-        return AsyncIterator.last(this, condition);
-    }
-
-    /**
-     * If the condition function is undefined, then this function will return the last value in the
-     * {@link AsyncIterator}. If this condition function is provided, then this function will return the
-     * last value that matches the provided condition.
-     * @param iterator The {@link AsyncIterator} to get the last value from.
-     */
-    public static last<T>(iterator: AsyncIterator<T>, condition?: (value: T) => (boolean | PromiseLike<boolean>)): PromiseAsyncResult<T>
-    {
-        PreCondition.assertNotUndefinedAndNotNull(iterator, "iterator");
-
-        return PromiseAsyncResult.create(async () =>
-        {
-            await iterator.start();
-
-            if (!iterator.hasCurrent())
-            {
-                throw new EmptyError();
-            }
-
-            let result: T;
-            let found: boolean = false;
-            do
-            {
-                if (!condition || await condition(iterator.getCurrent()))
-                {
-                    result = iterator.getCurrent();
-                    found = true;
-                }
-            }
-            while (await iterator.next());
-
-            if (!found)
-            {
-                if (!condition)
-                {
-                    throw new EmptyError();
-                }
-                else
-                {
-                    throw new NotFoundError("No value was found in the AsyncIterator that matched the provided condition.");
-                }
-            }
-
-            return result!;
-        });
-    }
-
-    /**
-     * Find the maximum value in the provided {@link AsyncIterator}.
-     * @param iterator The values to find the maximum of.
-     */
-    public static findMaximum<T extends Comparable<T>>(iterator: JavascriptAsyncIterator<T> | AsyncIterator<T>): PromiseAsyncResult<T>
-    {
-        PreCondition.assertNotUndefinedAndNotNull(iterator, "iterable");
-
-        return PromiseAsyncResult.create(async () =>
-        {
-            if (isJavascriptAsyncIterator(iterator))
-            {
-                iterator = AsyncIterator.create(iterator as JavascriptAsyncIterator<T>);
-            }
-
-            let result: T = await iterator.first()
-                .convertError(EmptyError, () => new EmptyError("Can't find the maximum of an empty Iterator."));
-            while (await iterator.next())
-            {
-                const currentValue: T = iterator.getCurrent();
-                if (result.lessThan(currentValue))
-                {
-                    result = currentValue;
-                }
-            }
-
-            return result;
-        });
-    }
-
-    /**
-     * Get a new {@link AsyncIterator} that wraps around this {@link AsyncIterator} and only
-     * returns a maximum number of values from this {@link AsyncIterator}.
-     * @param maximumToTake The maximum number of values to take from this {@link AsyncIterator}.
-     */
-    public take(maximumToTake: number): AsyncIterator<T>
-    {
-        return AsyncIterator.take(this, maximumToTake);
-    }
-
-    public static take<T>(iterator: AsyncIterator<T>, maximumToTake: number): AsyncIterator<T>
-    {
-        return TakeAsyncIterator.create(iterator, maximumToTake);
-    }
-
-    /**
-     * Get a new {@link AsyncIterator} that wraps around this {@link AsyncIterator} and will skip the initial
-     * provided number of values before beginning to return values.
-     * @param maximumToSkip The maximum number of values to skip from this {@link AsyncIterator}.
-     */
-    public skip(maximumToSkip: number): AsyncIterator<T>
-    {
-        return AsyncIterator.skip(this, maximumToSkip);
-    }
-
-    public static skip<T>(iterator: AsyncIterator<T>, maximumToSkip: number): AsyncIterator<T>
-    {
-        return SkipAsyncIterator.create(iterator, maximumToSkip);
-    }
-}

package/sources/asyncIteratorToJavascriptAsyncIteratorAdapter.ts

@@ -1,48 +0,0 @@
-import { AsyncIterator } from "./asyncIterator";
-import { JavascriptAsyncIterator, JavascriptIteratorResult } from "./javascript";
-import { PreCondition } from "./preCondition";
-
-/**
- * A type that adapts an {@link AsyncIterator} to match a {@link JavascriptAsyncIterator}.
- */
-export class AsyncIteratorToJavascriptAsyncIteratorAdapter<T> implements JavascriptAsyncIterator<T>
-{
-    private readonly iterator: AsyncIterator<T>;
-    private hasStarted: boolean;
-
-    private constructor(iterator: AsyncIterator<T>)
-    {
-        PreCondition.assertNotUndefinedAndNotNull(iterator, "iterator");
-
-        this.iterator = iterator;
-        this.hasStarted = false;
-    }
-
-    public static create<T>(iterator: AsyncIterator<T>): AsyncIteratorToJavascriptAsyncIteratorAdapter<T>
-    {
-        return new AsyncIteratorToJavascriptAsyncIteratorAdapter<T>(iterator);
-    }
-    
-    public async next(): Promise<JavascriptIteratorResult<T>>
-    {
-        if (!this.hasStarted)
-        {
-            this.hasStarted = true;
-            await this.iterator.start();
-        }
-        else
-        {
-            await this.iterator.next();
-        }
-
-        const result: JavascriptIteratorResult<T> = {
-            done: !this.iterator.hasCurrent(),
-            value: undefined!,
-        };
-        if (!result.done)
-        {
-            result.value = this.iterator.getCurrent();
-        }
-        return result;
-    }
-}

package/sources/asyncResult.ts

@@ -1,95 +0,0 @@
-import { PromiseAsyncResult } from "./promiseAsyncResult";
-import { isPromise, Type } from "./types";
-
-/**
- * A result object that adds extra behavior beyond the standard {@link Promise}.
- */
-export abstract class AsyncResult<T> implements Promise<T>
-{
-    public static create<T>(action: () => (T | Promise<T>)): AsyncResult<T>;
-    public static create<T>(promise: Promise<T>): AsyncResult<T>;
-    static create<T>(actionOrPromise: (() => (T | Promise<T>)) | Promise<T>): AsyncResult<T>
-    {
-        return PromiseAsyncResult.create<T>(isPromise<T>(actionOrPromise) ? actionOrPromise : new Promise<T>(actionOrPromise));
-    }
-
-    /**
-     * Create a new {@link AsyncResult} that contains the provided value.
-     * @param value The value to wrap in a {@link AsyncResult}.
-     */
-    public static value<T>(value: T): AsyncResult<T>
-    {
-        return PromiseAsyncResult.value(value);
-    }
-
-    /**
-     * Create a new {@link AsyncResult} that contains the provided error.
-     * @param error The error to wrap in a {@link AsyncResult}.
-     */
-    public static error<T>(error: Error): AsyncResult<T>
-    {
-        return PromiseAsyncResult.error<T>(error);
-    }
-
-    public static yield(): AsyncResult<void>
-    {
-        return PromiseAsyncResult.yield();
-    }
-
-    /**
-     * Get a {@link AsyncResult} that runs the provided function if this {@link AsyncResult} is successful.
-     * @param thenFunction The function to run if this {@link AsyncResult} is successful.
-     */
-    public abstract then<TResult1 = T, TResult2 = never>(onfulfilled?: ((value: T) => TResult1 | PromiseLike<TResult1>) | null | undefined, onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null | undefined): AsyncResult<TResult1 | TResult2>
-
-    /**
-     * Run the provided onValueFunction if this {@link AsyncResult} is successful. The value or error
-     * contained by this {@link AsyncResult} will be contained by the returned {@link AsyncResult}.
-     * @param onValueFunction The function to run if this {@link AsyncResult} is successful.
-     */
-    public abstract onValue(onValueFunction: (value: T) => (void | Promise<void>)): AsyncResult<T>
-
-    /**
-     * Run the provided catchFunction if this {@link AsyncResult} contains an error.
-     * @param catchFunction The function to run if an error is caught.
-     */
-    public abstract catch<TResult = never>(onrejected?: ((reason: unknown) => TResult | PromiseLike<TResult>) | null): AsyncResult<T | TResult>
-    /**
-     * Run the provided catchFunction if this {@link AsyncResult} contains an error of the provided type.
-     * @param errorType The type of error to catch.
-     * @param catchFunction The function to run if the error is caught.
-     */
-    public abstract catch<TError,TResult = never>(errorType: Type<TError>, onrejected: (reason: TError) => (TResult | PromiseLike<TResult>)): AsyncResult<T | TResult>
-
-    /**
-     * Run the provided onErrorFunction if this {@link AsyncResult} contains an error.
-     * @param onErrorFunction The function to run if an error is found.
-     */
-    public abstract onError(onErrorFunction: (reason: unknown) => (void | PromiseLike<void>)): AsyncResult<T>;
-    /**
-     * Run the provided onErrorFunction if this {@link AsyncResult} contains an error of the provided
-     * type.
-     * @param errorType The type of error to respond to.
-     * @param onErrorFunction The function to run if the error is found.
-     */
-    public abstract onError<TError>(errorType: Type<TError>, onErrorFunction: (reason: TError) => (void | PromiseLike<void>)): AsyncResult<T>;
-
-    /**
-     * Run the provided convertErrorFunction if this {@link AsyncResult} contains an error. The value
-     * returned from the convertErrorFunction will be the error for the returned {@link AsyncResult}.
-     * @param convertErrorFunction The function that will return the new error. 
-     */
-    public abstract convertError(convertErrorFunction: (reason: unknown) => (unknown | PromiseLike<unknown>)): AsyncResult<T>;
-    /**
-     * Run the provided convertErrorFunction if this {@link AsyncResult} contains an error of the
-     * provided type. The value returned from the convertErrorFunction will be the error for the
-     * returned {@link AsyncResult}.
-     * @param errorType The type of error to respond to.
-     * @param convertErrorFunction The function that will return the new error. 
-     */
-    public abstract convertError<TError>(errorType: Type<TError>, convertErrorFunction: (reason: TError) => (unknown | PromiseLike<unknown>)): AsyncResult<T>;
-
-    public abstract finally(onfinally?: (() => (void | Promise<void>)) | null): AsyncResult<T>;
-
-    readonly abstract [Symbol.toStringTag]: string;
-}