From a1d0d4809d2381276604f18e109dec6ad259560d Mon Sep 17 00:00:00 2001 From: Tom Anderson Date: Mon, 15 Jul 2024 12:40:35 +1000 Subject: [PATCH] migrate and deprecate `unknown` methods to `exception` --- src/handler.ts | 4 ++-- src/index.ts | 6 ++++-- src/stream/base.ts | 14 +++++++++++--- src/stream/higher-order.ts | 20 +++++++++++++++----- src/stream/index.ts | 24 ++++++++++++++++++++---- src/stream/transforms.ts | 14 +++++++++++--- test/consumption.test.ts | 8 ++++---- test/creation.test.ts | 11 ++++++++--- test/errors.test.ts | 8 ++++---- test/higher-order.test.ts | 10 +++++----- test/transforms.test.ts | 10 ++++++---- 11 files changed, 90 insertions(+), 39 deletions(-) diff --git a/src/handler.ts b/src/handler.ts index 9c2d0d2..08f62cf 100644 --- a/src/handler.ts +++ b/src/handler.ts @@ -25,7 +25,7 @@ async function normalisePromise(value: MaybePromise): Promise { /** * Run the given handler, then the returned value will be normalised as an atom and returned. If an - * unhandled error is thrown during the handler, then it will be caught and returned as an `unknown` + * unhandled error is thrown during the handler, then it will be caught and returned as an `exception` * atom. */ export async function handler( @@ -43,7 +43,7 @@ export async function handler( /** * Run some callback. If it completes successfully, the value will be returned as `AtomOk`. If an - * error is thrown, it will be caught and returned as an `AtomUnknown`. `AtomError` will never be + * error is thrown, it will be caught and returned as an `AtomException`. `AtomError` will never be * produced from this helper. */ export async function run( diff --git a/src/index.ts b/src/index.ts index 747be32..a8b083a 100644 --- a/src/index.ts +++ b/src/index.ts @@ -5,10 +5,12 @@ export type { Atom, AtomOk, AtomError, - AtomException as AtomUnknown, + AtomException, + AtomUnknown, VALUE, ERROR, - EXCEPTION as UNKNOWN, + EXCEPTION, + UNKNOWN, MaybeAtom, } from "./atom"; diff --git a/src/stream/base.ts b/src/stream/base.ts index 8b933ec..4de64fc 100644 --- a/src/stream/base.ts +++ b/src/stream/base.ts @@ -214,7 +214,7 @@ export class StreamBase { this.push(normalise(value)); } } catch (e) { - // Promise was rejected, add as an unknown error + // Promise was rejected, add as an exception this.push(exception(e, [])); } }, @@ -250,14 +250,22 @@ export class StreamBase { } /** - * Create a new stream containing a single unknown atom. + * Create a new stream containing a single exception atom. * * @group Creation */ - static ofUnknown(value: unknown): Stream { + static ofException(value: unknown): Stream { return this.of(exception(value, [])); } + /** + * @group Creation + * @deprecated use `ofException` instead + */ + static ofUnknown(value: unknown): Stream { + return this.ofException(value); + } + /** * Create a stream and corresponding writable Node stream, where any writes to the writable * Node stream will be emitted on the returned stream. diff --git a/src/stream/higher-order.ts b/src/stream/higher-order.ts index f80ddd0..a2ff452 100644 --- a/src/stream/higher-order.ts +++ b/src/stream/higher-order.ts @@ -107,15 +107,15 @@ export class HigherOrderStream extends StreamTransforms { } /** - * Maps over each unknown error in the stream, producing a new stream from it, and flatten all + * Maps over each exception in the stream, producing a new stream from it, and flatten all * the value streams together. * * @group Higher Order */ - flatMapUnknown( + flatMapException( cb: (value: unknown, trace: string[]) => MaybePromise>, ): Stream { - const trace = this.trace("flatMapUnknown"); + const trace = this.trace("flatMapException"); return this.flatMapAtom( (atom) => (isException(atom) ? accept(atom) : reject(atom)), @@ -125,6 +125,16 @@ export class HigherOrderStream extends StreamTransforms { ); } + /** + * @group Higher Order + * @deprecated use `flatMapException` instead + */ + flatMapUnknown( + cb: (value: unknown, trace: string[]) => MaybePromise>, + ): Stream { + return this.flatMapException(cb); + } + /** * Map over each value in the stream, produce a stream from it, cache the resultant stream * and flatten all the value streams together @@ -235,7 +245,7 @@ export class HigherOrderStream extends StreamTransforms { /** * Emit items from provided stream if this stream is completely empty. * - * @note If there are any errors (known or unknown) on the stream, then the new stream won't be + * @note If there are any errors or exceptions on the stream, then the new stream won't be * consumed. * * @group Higher Order @@ -262,7 +272,7 @@ export class HigherOrderStream extends StreamTransforms { /** * Consume the entire stream, and completely replace it with a new stream. This will remove - * any errors currently on the stream (both known and unknown). + * any errors and exceptions currently on the stream. * * Equivalent to: * diff --git a/src/stream/index.ts b/src/stream/index.ts index e10897f..68e7f1f 100644 --- a/src/stream/index.ts +++ b/src/stream/index.ts @@ -39,14 +39,22 @@ export class Stream extends HigherOrderStream { } /** - * Create an `unknown` atom with the provided value. + * Create an `exception` atom with the provided value. * * @group Atom */ - static unknown(value: unknown, trace: string[]): Atom { + static exception(value: unknown, trace: string[]): Atom { return exception(value, trace); } + /** + * @group Atom + * @deprecated use `exception` instead + */ + static unknown(value: unknown, trace: string[]): Atom { + return this.exception(value, trace); + } + /** * Verify if the provided atom is of the `ok` variant. * @@ -66,11 +74,19 @@ export class Stream extends HigherOrderStream { } /** - * Verify if the provided atom is of the `unknown` variant. + * Verify if the provided atom is of the `exception` variant. * * @group Atom */ - static isUnknown(atom: Atom): atom is AtomException { + static isException(atom: Atom): atom is AtomException { return isException(atom); } + + /** + * @group Atom + * @deprecated use `isException` instead + */ + static isUnknown(atom: Atom): atom is AtomException { + return this.isException(atom); + } } diff --git a/src/stream/transforms.ts b/src/stream/transforms.ts index 1116dea..25b069f 100644 --- a/src/stream/transforms.ts +++ b/src/stream/transforms.ts @@ -85,12 +85,12 @@ export class StreamTransforms extends StreamConsumption { } /** - * Map over each unknown in the stream. + * Map over each exception in the stream. * * @group Transform */ - mapUnknown(cb: (error: unknown) => MaybePromise>): Stream { - const trace = this.trace("mapUnknown"); + mapException(cb: (error: unknown) => MaybePromise>): Stream { + const trace = this.trace("mapException"); return this.consume(async function* (it) { for await (const atom of it) { @@ -103,6 +103,14 @@ export class StreamTransforms extends StreamConsumption { }); } + /** + * @group Transform + * @deprecated use `mapException` instead + */ + mapUnknown(cb: (error: unknown) => MaybePromise>): Stream { + return this.mapException(cb); + } + /** * Run a callback for each value in the stream, ideal for side effects on stream items. * diff --git a/test/consumption.test.ts b/test/consumption.test.ts index 8062918..6569f6e 100644 --- a/test/consumption.test.ts +++ b/test/consumption.test.ts @@ -20,7 +20,7 @@ describe.concurrent("stream consumption", () => { $.error("known"), 2, 3, - $.unknown("$.error", []), + $.exception("$.error", []), ]).toArray(); expect(array).toEqual([1, 2, 3]); @@ -50,7 +50,7 @@ describe.concurrent("stream consumption", () => { $.error("known"), 2, 3, - $.unknown("$.error", []), + $.exception("$.error", []), ]).toArray({ atoms: true, }); @@ -60,7 +60,7 @@ describe.concurrent("stream consumption", () => { $.error("known"), $.ok(2), $.ok(3), - $.unknown("$.error", []), + $.exception("$.error", []), ]); }); @@ -184,7 +184,7 @@ describe.concurrent("stream consumption", () => { $.ok("a"), $.error("an error"), $.ok("b"), - $.unknown("unknown error", []), + $.exception("unknown error", []), $.ok("c"), ]).toReadable("object"); diff --git a/test/creation.test.ts b/test/creation.test.ts index 9a94c15..6d5a702 100644 --- a/test/creation.test.ts +++ b/test/creation.test.ts @@ -151,7 +151,12 @@ describe.concurrent("stream creation", () => { test("next atoms produces atoms", async ({ expect }) => { expect.assertions(1); - const atoms = [$.ok(0), $.error("some error"), $.ok(1), $.unknown("unknown error", [])]; + const atoms = [ + $.ok(0), + $.error("some error"), + $.ok(1), + $.exception("unknown error", []), + ]; const s = $.fromNext(async () => { if (atoms.length > 0) { return atoms.shift(); @@ -164,7 +169,7 @@ describe.concurrent("stream creation", () => { $.ok(0), $.error("some error"), $.ok(1), - $.unknown("unknown error", []), + $.exception("unknown error", []), ]); }); @@ -187,7 +192,7 @@ describe.concurrent("stream creation", () => { }); expect(await s.toArray({ atoms: true })).toEqual([ - $.unknown("some error", []), + $.exception("some error", []), $.ok(2), ]); }); diff --git a/test/errors.test.ts b/test/errors.test.ts index 1078639..e1448b3 100644 --- a/test/errors.test.ts +++ b/test/errors.test.ts @@ -16,7 +16,7 @@ describe.concurrent("error handling", () => { expect(await s.toArray({ atoms: true })).toEqual([ $.ok(1), - $.unknown(new Error("bad number"), ["map"]), + $.exception(new Error("bad number"), ["map"]), $.ok(3), ]); }); @@ -36,7 +36,7 @@ describe.concurrent("error handling", () => { expect(await s.toArray({ atoms: true })).toEqual([ $.ok(1), - $.unknown(new Error("bad number"), ["map"]), + $.exception(new Error("bad number"), ["map"]), $.ok(3), ]); }); @@ -56,7 +56,7 @@ describe.concurrent("error handling", () => { .filter((n) => n % 2 === 0); expect(await s.toArray({ atoms: true })).toEqual([ - $.unknown(new Error("bad number"), ["map"]), + $.exception(new Error("bad number"), ["map"]), $.ok(4), ]); }); @@ -84,7 +84,7 @@ describe.concurrent("error handling", () => { .filter((n) => n % 2 === 0); expect(await s.toArray({ atoms: true })).toEqual([ - $.unknown(new Error("bad number"), ["filter", "map", "map"]), + $.exception(new Error("bad number"), ["filter", "map", "map"]), $.ok(30), $.ok(4), $.ok(50), diff --git a/test/higher-order.test.ts b/test/higher-order.test.ts index 3d6701a..d0e83e9 100644 --- a/test/higher-order.test.ts +++ b/test/higher-order.test.ts @@ -25,7 +25,7 @@ describe.concurrent("higher order streams", () => { $.ok(1), $.error("known error"), $.ok(2), - $.unknown("bad error", []), + $.exception("bad error", []), $.ok(3), ]).flatMap((n) => $.from(new Array(n).fill(n))); @@ -34,7 +34,7 @@ describe.concurrent("higher order streams", () => { $.error("known error"), $.ok(2), $.ok(2), - $.unknown("bad error", []), + $.exception("bad error", []), $.ok(3), $.ok(3), $.ok(3), @@ -121,9 +121,9 @@ describe.concurrent("higher order streams", () => { test("stream with unknown error", async ({ expect }) => { expect.assertions(1); - const s = $.from([$.unknown("some error", [])]).otherwise($.from([1])); + const s = $.from([$.exception("some error", [])]).otherwise($.from([1])); - expect(await s.toArray({ atoms: true })).toEqual([$.unknown("some error", [])]); + expect(await s.toArray({ atoms: true })).toEqual([$.exception("some error", [])]); }); }); @@ -198,7 +198,7 @@ describe.concurrent("higher order streams", () => { expect(await s.toArray({ atoms: true })).toEqual([ $.ok(20), - $.unknown("Cannot divide by zero!", ["cachedFlatMap"]), + $.exception("Cannot divide by zero!", ["cachedFlatMap"]), $.ok(2), $.ok(20), $.ok(20), diff --git a/test/transforms.test.ts b/test/transforms.test.ts index 49ce338..b8f227c 100644 --- a/test/transforms.test.ts +++ b/test/transforms.test.ts @@ -84,9 +84,9 @@ describe("stream transforms", () => { test("single unknown", async ({ expect }) => { expect.assertions(1); - const s = $.from([$.unknown(1, []), $.ok(2), $.ok(3)]).collect(); + const s = $.from([$.exception(1, []), $.ok(2), $.ok(3)]).collect(); - expect(await s.toArray({ atoms: true })).toEqual([$.unknown(1, []), $.ok([2, 3])]); + expect(await s.toArray({ atoms: true })).toEqual([$.exception(1, []), $.ok([2, 3])]); }); }); @@ -116,7 +116,9 @@ describe("stream transforms", () => { test("single unknown", async ({ expect }) => { expect.assertions(1); - const s = $.from([$.unknown(1, []), $.ok(2), $.ok(3)]).mapUnknown((e) => $.error(e)); + const s = $.from([$.exception(1, []), $.ok(2), $.ok(3)]).mapException((e) => + $.error(e), + ); expect(await s.toArray({ atoms: true })).toEqual([$.error(1), $.ok(2), $.ok(3)]); }); @@ -124,7 +126,7 @@ describe("stream transforms", () => { test("multiple unknown", async ({ expect }) => { expect.assertions(1); - const s = $.from([$.unknown(1, []), $.ok(2), $.unknown(3, [])]).mapUnknown((e) => + const s = $.from([$.exception(1, []), $.ok(2), $.exception(3, [])]).mapException((e) => $.error(e), );