migrate and deprecate unknown methods to exception

src/handler.ts

@@ -25,7 +25,7 @@ async function normalisePromise<T>(value: MaybePromise<T>): Promise<T> {
 
 /**
  * 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<T, E>(
@@ -43,7 +43,7 @@ export async function handler<T, E>(
 
 /**
  * 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<T>(

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";
 

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<T, E>(value: unknown): Stream<T, E> {
+    static ofException<T, E>(value: unknown): Stream<T, E> {
         return this.of(exception(value, []));
     }
 
+    /**
+     * @group Creation
+     * @deprecated use `ofException` instead
+     */
+    static ofUnknown<T, E>(value: unknown): Stream<T, E> {
+        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.

src/stream/higher-order.ts

@@ -107,15 +107,15 @@ export class HigherOrderStream<T, E> extends StreamTransforms<T, E> {
     }
 
     /**
-     * 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<T, E>>,
     ): Stream<T, E> {
-        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<T, E> extends StreamTransforms<T, E> {
         );
     }
 
+    /**
+     * @group Higher Order
+     * @deprecated use `flatMapException` instead
+     */
+    flatMapUnknown(
+        cb: (value: unknown, trace: string[]) => MaybePromise<Stream<T, E>>,
+    ): Stream<T, E> {
+        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<T, E> extends StreamTransforms<T, E> {
     /**
      * 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<T, E> extends StreamTransforms<T, E> {
 
     /**
      * 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:
      *

src/stream/index.ts

@@ -39,14 +39,22 @@ export class Stream<T, E> extends HigherOrderStream<T, E> {
     }
 
     /**
-     * Create an `unknown` atom with the provided value.
+     * Create an `exception` atom with the provided value.
      *
      * @group Atom
      */
-    static unknown<T, E>(value: unknown, trace: string[]): Atom<T, E> {
+    static exception<T, E>(value: unknown, trace: string[]): Atom<T, E> {
         return exception(value, trace);
     }
 
+    /**
+     * @group Atom
+     * @deprecated use `exception` instead
+     */
+    static unknown<T, E>(value: unknown, trace: string[]): Atom<T, E> {
+        return this.exception(value, trace);
+    }
+
     /**
      * Verify if the provided atom is of the `ok` variant.
      *
@@ -66,11 +74,19 @@ export class Stream<T, E> extends HigherOrderStream<T, E> {
     }
 
     /**
-     * Verify if the provided atom is of the `unknown` variant.
+     * Verify if the provided atom is of the `exception` variant.
      *
      * @group Atom
      */
-    static isUnknown<T, E>(atom: Atom<T, E>): atom is AtomException {
+    static isException<T, E>(atom: Atom<T, E>): atom is AtomException {
         return isException(atom);
     }
+
+    /**
+     * @group Atom
+     * @deprecated use `isException` instead
+     */
+    static isUnknown<T, E>(atom: Atom<T, E>): atom is AtomException {
+        return this.isException(atom);
+    }
 }

src/stream/transforms.ts

@@ -85,12 +85,12 @@ export class StreamTransforms<T, E> extends StreamConsumption<T, E> {
     }
 
     /**
-     * Map over each unknown in the stream.
+     * Map over each exception in the stream.
      *
      * @group Transform
      */
-    mapUnknown(cb: (error: unknown) => MaybePromise<MaybeAtom<T, E>>): Stream<T, E> {
-        const trace = this.trace("mapUnknown");
+    mapException(cb: (error: unknown) => MaybePromise<MaybeAtom<T, E>>): Stream<T, E> {
+        const trace = this.trace("mapException");
 
         return this.consume(async function* (it) {
             for await (const atom of it) {
@@ -103,6 +103,14 @@ export class StreamTransforms<T, E> extends StreamConsumption<T, E> {
         });
     }
 
+    /**
+     * @group Transform
+     * @deprecated use `mapException` instead
+     */
+    mapUnknown(cb: (error: unknown) => MaybePromise<MaybeAtom<T, E>>): Stream<T, E> {
+        return this.mapException(cb);
+    }
+
     /**
      * Run a callback for each value in the stream, ideal for side effects on stream items.
      *

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");
 

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),
             ]);
         });

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),

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),

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,15 +116,17 @@ 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)]);
         });
 
         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),
             );