@everyonesoftware/common 1.0.0

package/sources/asyncResult.ts

@@ -0,0 +1,95 @@
+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;
+}

package/sources/basicDisposable.ts

@@ -0,0 +1,57 @@
+import { Disposable } from "./disposable";
+import { PreCondition } from "./preCondition";
+import { SyncResult } from "./syncResult";
+
+/**
+ * A {@link Disposable} type that can be configured with a function that will be invoked when the
+ * object is disposed.
+ */
+export class SyncDisposable implements Disposable
+{
+    private readonly disposedFunction: () => void;
+    private disposed: boolean;
+
+    protected constructor(disposedFunction: () => void)
+    {
+        PreCondition.assertNotUndefinedAndNotNull(disposedFunction, "disposedFunction");
+
+        this.disposedFunction = disposedFunction;
+        this.disposed = false;
+    }
+
+    /**
+     * Create a new {@link Disposable} that will invoke the provided {@link Function} when it is
+     * disposed.
+     * @param disposedFunction The function to invoke when the returned {@link Disposable} is
+     * disposed.
+     */
+    public static create(disposedFunction: () => void): SyncDisposable
+    {
+        return new SyncDisposable(disposedFunction);
+    }
+
+    public dispose(): SyncResult<boolean>
+    {
+        return SyncResult.create(() =>
+        {
+            const result: boolean = !this.disposed;
+            if (result)
+            {
+                try
+                {
+                    this.disposedFunction();
+                }
+                finally
+                {
+                    this.disposed = true;
+                }
+            }
+            return result;
+        });
+    }
+
+    public isDisposed(): boolean
+    {
+        return this.disposed;
+    }
+}

package/sources/byteList.ts

@@ -0,0 +1,202 @@
+import { EqualFunctions } from "./equalFunctions";
+import { Iterable } from "./iterable";
+import { Iterator } from "./iterator";
+import { JavascriptIterable, JavascriptIterator } from "./javascript";
+import { List } from "./list";
+import { PreCondition } from "./preCondition";
+import { SyncResult } from "./syncResult";
+import { ToStringFunctions } from "./toStringFunctions";
+import { Type } from "./types";
+
+/**
+ * A {@link List} of bytes.
+ */
+export class ByteList implements List<number>
+{
+    private bytes: Uint8Array;
+    private count: number;
+
+    private constructor()
+    {
+        this.bytes = new Uint8Array(0);
+        this.count = 0;
+    }
+
+    public static create(initialValues?: JavascriptIterable<number>): ByteList
+    {
+        const result: ByteList = new ByteList();
+        if (initialValues)
+        {
+            result.addAll(initialValues);
+        }
+        return result;
+    }
+
+    public add(value: number): this
+    {
+        return List.add(this, value);
+    }
+
+    public addAll(values: JavascriptIterable<number>): this
+    {
+        return List.addAll(this, values);
+    }
+
+    public insert(index: number, value: number): this
+    {
+        PreCondition.assertInsertIndex(index, this.getCount().await(), "index");
+        PreCondition.assertByte(value, "value");
+
+        if (this.count < this.bytes.length)
+        {
+            if (index < this.count)
+            {
+                this.bytes.copyWithin(index + 1, index, this.count);
+            }
+            this.bytes[index] = value;
+        }
+        else
+        {
+            const newCapacity: number = (this.bytes.length * 2) + 1;
+            const newBytes: Uint8Array = new Uint8Array(newCapacity);
+            if (index > 0)
+            {
+                newBytes.set(this.bytes.subarray(0, index));
+            }
+            newBytes[index] = value;
+            if (index < this.count)
+            {
+                newBytes.set(this.bytes.subarray(index), index + 1);
+            }
+            this.bytes = newBytes;
+        }
+        this.count++;
+
+        return this;
+    }
+
+    public insertAll(index: number, values: JavascriptIterable<number>): this
+    {
+        return List.insertAll(this, index, values);
+    }
+
+    public remove(value: number, equalFunctions?: EqualFunctions): SyncResult<number>
+    {
+        PreCondition.assertByte(value, "value");
+
+        return List.remove(this, value, equalFunctions);
+    }
+
+    public removeAt(index: number): SyncResult<number>
+    {
+        PreCondition.assertAccessIndex(index, this.count, "index");
+
+        const result: number = this.bytes[index];
+        this.bytes.copyWithin(index, index + 1, this.count);
+        this.count--;
+
+        return SyncResult.value(result);
+    }
+
+    public removeFirst(): SyncResult<number>
+    {
+        return List.removeFirst(this);
+    }
+
+    public removeLast(): SyncResult<number>
+    {
+        return List.removeLast(this);
+    }
+
+    public set(index: number, value: number): this
+    {
+        PreCondition.assertAccessIndex(index, this.getCount().await(), "index");
+        PreCondition.assertByte(value, "value");
+
+        this.bytes[index] = value;
+
+        return this;
+    }
+
+    public iterate(): Iterator<number>
+    {
+        return Iterator.create(this.bytes[Symbol.iterator]().take(this.count));
+    }
+
+    public get(index: number): SyncResult<number>
+    {
+        PreCondition.assertAccessIndex(index, this.getCount().await(), "index");
+
+        return SyncResult.value(this.bytes.at(index)!);
+    }
+
+    public toArray(): SyncResult<number[]>
+    {
+        return List.toArray(this);
+    }
+
+    public any(): SyncResult<boolean>
+    {
+        return this.getCount().then(count => count > 0);
+    }
+
+    public getCount(): SyncResult<number>
+    {
+        return SyncResult.value(this.count);
+    }
+
+    public equals(right: JavascriptIterable<number>, equalFunctions?: EqualFunctions): SyncResult<boolean>
+    {
+        return List.equals(this, right, equalFunctions);
+    }
+
+    public toString(toStringFunctions?: ToStringFunctions): string
+    {
+        return List.toString(this, toStringFunctions);
+    }
+
+    public concatenate(...toConcatenate: JavascriptIterable<number>[]): Iterable<number>
+    {
+        return List.concatenate(this, ...toConcatenate);
+    }
+
+    public map<TOutput>(mapping: (value: number) => TOutput | SyncResult<TOutput>): Iterable<TOutput>
+    {
+        return List.map(this, mapping);
+    }
+
+    public flatMap<TOutput>(mapping: (value: number) => JavascriptIterable<TOutput>): Iterable<TOutput>
+    {
+        return List.flatMap(this, mapping);
+    }
+
+    public where(condition: (value: number) => (boolean | SyncResult<boolean>)): Iterable<number>
+    {
+        return List.where(this, condition);
+    }
+
+    public instanceOf<TOutput extends number>(typeOrTypeCheck: Type<TOutput> | ((value: number) => value is TOutput)): Iterable<TOutput>
+    {
+        return List.instanceOf(this, typeOrTypeCheck);
+    }
+
+    public first(condition?: ((value: number) => (boolean | SyncResult<boolean>)) | undefined): SyncResult<number>
+    {
+        return List.first(this, condition);
+    }
+
+    public last(condition?: ((value: number) => (boolean | SyncResult<boolean>)) | undefined): SyncResult<number>
+    {
+        return List.last(this, condition);
+    }
+
+    public contains(value: number, equalFunctions?: EqualFunctions): SyncResult<boolean>
+    {
+        return List.contains(this, value, equalFunctions);
+    }
+
+    public [Symbol.iterator](): JavascriptIterator<number>
+    {
+        return List[Symbol.iterator](this);
+    }
+}

package/sources/byteListStream.ts

@@ -0,0 +1,121 @@
+import { ByteList } from "./byteList";
+import { ByteReadStream } from "./byteReadStream";
+import { ByteWriteStream } from "./byteWriteStream";
+import { EmptyError } from "./emptyError";
+import { PreCondition } from "./preCondition";
+import { SyncResult } from "./syncResult";
+import { isArray, isNumber, isUndefinedOrNull } from "./types";
+
+/**
+ * A {@link ByteReadStream} and {@link ByteWriteStream} implementation that is implemented using a
+ * {@link ByteList}.
+ */
+export class ByteListStream implements ByteReadStream, ByteWriteStream
+{
+    private readonly list: ByteList;
+
+    private constructor()
+    {
+        this.list = ByteList.create();
+    }
+
+    public static create(initialValues?: Uint8Array | number[]): ByteListStream
+    {
+        const result: ByteListStream = new ByteListStream();
+        if (initialValues)
+        {
+            result.writeBytes(initialValues).await();
+        }
+        return result;
+    }
+
+    /**
+     * Get the number of bytes that are available to be read.
+     */
+    public getAvailableByteCount(): number
+    {
+        return this.list.getCount().await();
+    }
+
+    public writeBytes(bytes: Uint8Array | number[], startIndex?: number, length?: number): SyncResult<number>
+    {
+        PreCondition.assertNotUndefinedAndNotNull(bytes, "bytes");
+
+        if (isArray(bytes))
+        {
+            bytes = new Uint8Array(bytes);
+        }
+        if (isUndefinedOrNull(startIndex))
+        {
+            startIndex = 0;
+        }
+        if (isUndefinedOrNull(length))
+        {
+            length = bytes.length - startIndex;
+        }
+
+        PreCondition.assertInsertIndex(startIndex, bytes.length, "startIndex");
+        PreCondition.assertBetween(0, length, bytes.length - startIndex, "length");
+
+        this.list.addAll(bytes.subarray(startIndex, length + startIndex));
+
+        return SyncResult.value(length);
+    }
+
+    public readBytes(count: number): SyncResult<Uint8Array>;
+    public readBytes(output: Uint8Array, startIndex?: number, count?: number): SyncResult<number>;
+    readBytes(countOrOutput: number | Uint8Array, startIndex?: number, count?: number): SyncResult<number> | SyncResult<Uint8Array>
+    {
+        let result: SyncResult<number> | SyncResult<Uint8Array>;
+        if (isNumber(countOrOutput))
+        {
+            PreCondition.assertGreaterThanOrEqualTo(countOrOutput, 0, "count");
+
+            if (!this.list.any().await())
+            {
+                result = SyncResult.error<Uint8Array>(new EmptyError());
+            }
+            else
+            {
+                const bytesReadCount: number = Math.min(countOrOutput, this.list.getCount().await());
+                const output: Uint8Array = new Uint8Array(bytesReadCount);
+                for (let i = 0; i < bytesReadCount; i++)
+                {
+                    output[i] = this.list.removeFirst().await();
+                }
+                result = SyncResult.value(output);
+            }
+        }
+        else
+        {
+            PreCondition.assertNotUndefinedAndNotNull(countOrOutput, "output");
+
+            if (isUndefinedOrNull(startIndex))
+            {
+                startIndex = 0;
+            }
+            if (isUndefinedOrNull(count))
+            {
+                count = countOrOutput.length - startIndex;
+            }
+
+            PreCondition.assertInsertIndex(startIndex, countOrOutput.length, "startIndex");
+            PreCondition.assertBetween(0, count, countOrOutput.length - startIndex, "count");
+
+            if (!this.list.any().await())
+            {
+                result = SyncResult.error<number>(new EmptyError());
+            }
+            else
+            {
+                const bytesReadCount: number = Math.min(count, this.list.getCount().await());
+                for (let i = 0; i < bytesReadCount; i++)
+                {
+                    countOrOutput[startIndex + i] = this.list.removeFirst().await();
+                }
+                result = SyncResult.value(bytesReadCount);
+            }
+        }
+        return result;
+    }
+}

package/sources/byteReadStream.ts

@@ -0,0 +1,24 @@
+import { AsyncResult } from "./asyncResult";
+
+/**
+ * A stream that reads bytes.
+ */
+export abstract class ByteReadStream
+{
+    /**
+     * Attempt to read the provided {@link count} number of bytes. Returns the bytes that were read.
+     * The number of bytes returned may be less than the number requested.
+     * @param count The number of bytes to attempt to read.
+     */
+    public abstract readBytes(count: number): AsyncResult<Uint8Array>;
+    /**
+     * Attempt to read bytes into the provided output array. Returns the number of bytes that were
+     * read.
+     * @param output The array that the read bytes will be written to.
+     * @param startIndex The index in the {@link output} array to start writting the read bytes to.
+     * Defaults to 0.
+     * @param count The maximum number of bytes to read. Defaults to the length of the output array
+     * minus the startIndex.
+     */
+    public abstract readBytes(output: Uint8Array, startIndex?: number, count?: number): AsyncResult<number>;
+}

package/sources/byteWriteStream.ts

@@ -0,0 +1,16 @@
+import { AsyncResult } from "./asyncResult";
+
+/**
+ * A stream that writes bytes.
+ */
+export abstract class ByteWriteStream
+{
+    /**
+     * Write the provided bytes to this {@link ByteWriteStream}.
+     * @param bytes The bytes to write.
+     * @param startIndex The index to start writing from.
+     * @param length The number of bytes to write.
+     * @returns The number of bytes that were written.
+     */
+    public abstract writeBytes(bytes: Uint8Array | number[], startIndex?: number, length?: number): AsyncResult<number>
+}

package/sources/bytes.ts

@@ -0,0 +1,25 @@
+/**
+ * A collection of values and functions for interacting with bytes.
+ */
+export abstract class Bytes
+{
+    /**
+     * The minimum value that a byte can have.
+     */
+    public static readonly minimumValue: number = 0;
+
+    /**
+     * The maximum value (inclusive) that a byte can have.
+     */
+    public static readonly maximumValue: number = 255;
+
+    /**
+     * Get whether the provided value is within the range of a valid byte (between 0 and
+     * 255).
+     * @param value The value to check.
+     */
+    public static isByte(value: number): boolean
+    {
+        return Bytes.minimumValue <= value && value <= Bytes.maximumValue;
+    }
+}