Merge pull request #7 from clear/feat/api-improvements

create `ofError` and `ofUnknown` methods for creating a stream

.changeset/silent-pandas-talk.md

@@ -0,0 +1,5 @@
+---
+"windpipe": minor
+---
+
+create new `ofError` and `ofUnknown` static methods for creating a stream

.changeset/three-forks-learn.md

@@ -0,0 +1,5 @@
+---
+"windpipe": minor
+---
+
+alter exported API

package.json

@@ -6,7 +6,7 @@
   "scripts": {
     "lint": "tsc && eslint .",
     "format": "eslint --fix .",
-    "build": "tsup ./src/index.ts --format esm,cjs --dts",
+    "build": "tsup ./src/index.ts --format esm,cjs --dts --splitting --cjsInterop",
     "doc": "typedoc ./src --media ./media --plugin typedoc-plugin-extras --favicon ./media/favicon.ico --footerLastModified true --plugin typedoc-material-theme --themeColor '#03284e'",
     "test": "vitest",
     "ci:release": "npm run build && changeset publish"

src/index.ts

@@ -1,42 +1,12 @@
 import { Stream } from "./stream";
-import type { StreamBase } from "./stream/base";
-import { ok, error, unknown, isOk, isError, isUnknown } from "./atom";
-export * from "./util";
 
-export { Stream, type StreamEnd } from "./stream";
+// Export all useful types for atoms
 export type { Atom, AtomOk, AtomError, AtomUnknown } from "./atom";
 
-// Attempt to emulate Highland API
-type HighlandConstructor = (typeof StreamBase)["from"] & {
-    of: (typeof StreamBase)["of"];
+// Re-export all utility types
+export type * from "./util";
 
-    /**
-     * Create a stream with a single `ok` atom on it.
-     */
-    ok: <T, E>(value: T) => Stream<T, E>;
+// Export the `StreamEnd` type
+export type { StreamEnd } from "./stream";
 
-    /**
-     * Create a stream with a single `error` atom on it.
-     */
-    error: <T, E>(value: E) => Stream<T, E>;
-
-    /**
-     * Create a stream with a single `unknown` atom on it.
-     */
-    unknown: <T, E>(value: unknown) => Stream<T, E>;
-};
-export const $: HighlandConstructor = Stream.from as HighlandConstructor;
-$.of = Stream.of;
-
-$.ok = (value) => Stream.of(ok(value));
-$.error = (value) => Stream.of(error(value));
-$.unknown = (value) => Stream.of(unknown(value, []));
-
-export const atom = {
-    ok,
-    error,
-    unknown,
-    isOk,
-    isError,
-    isUnknown,
-};
+export default Stream;

src/stream/base.ts

@@ -1,4 +1,4 @@
-import { normalise, type Atom, type MaybeAtom } from "../atom";
+import { normalise, type Atom, type MaybeAtom, error, unknown } from "../atom";
 import { Stream } from ".";
 import { Readable, Writable } from "stream";
 
@@ -184,6 +184,12 @@ export class StreamBase {
         );
     }
 
+    /**
+     * Create a new stream containing a single value. Unless an atom is provided, it will be
+     * converted to an `ok` atom.
+     *
+     * @group Creation
+     */
     static of<T, E>(value: MaybeAtom<T, E>): Stream<T, E> {
         let consumed = false;
         return Stream.fromNext(async () => {
@@ -196,6 +202,24 @@ export class StreamBase {
         });
     }
 
+    /**
+     * Create a new stream containing a single error atom.
+     *
+     * @group Creation
+     */
+    static ofError<T, E>(value: E): Stream<T, E> {
+        return this.of(error(value));
+    }
+
+    /**
+     * Create a new stream containing a single unknown atom.
+     *
+     * @group Creation
+     */
+    static ofUnknown<T, E>(value: unknown): Stream<T, E> {
+        return this.of(unknown(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/index.ts

@@ -1,5 +1,72 @@
+import {
+    ok,
+    error,
+    unknown,
+    isOk,
+    isError,
+    isUnknown,
+    type Atom,
+    type AtomOk,
+    type AtomError,
+    type AtomUnknown,
+} from "../atom";
 import { HigherOrderStream } from "./higher-order";
 
 export type { StreamEnd } from "./base";
 
-export class Stream<T, E> extends HigherOrderStream<T, E> {}
+export class Stream<T, E> extends HigherOrderStream<T, E> {
+    // Re-export atom utilities for convenience
+    /**
+     * Create an `ok` atom with the provided value.
+     *
+     * @group Atom
+     */
+    static ok<T, E>(value: T): Atom<T, E> {
+        return ok(value);
+    }
+
+    /**
+     * Create an `error` atom with the provided value.
+     *
+     * @group Atom
+     */
+    static error<T, E>(value: E): Atom<T, E> {
+        return error(value);
+    }
+
+    /**
+     * Create an `unknown` atom with the provided value.
+     *
+     * @group Atom
+     */
+    static unknown<T, E>(value: unknown, trace: string[]): Atom<T, E> {
+        return unknown(value, trace);
+    }
+
+    /**
+     * Verify if the provided atom is of the `ok` variant.
+     *
+     * @group Atom
+     */
+    static isOk<T, E>(atom: Atom<T, E>): atom is AtomOk<T> {
+        return isOk(atom);
+    }
+
+    /**
+     * Verify if the provided atom is of the `error` variant.
+     *
+     * @group Atom
+     */
+    static isError<T, E>(atom: Atom<T, E>): atom is AtomError<E> {
+        return isError(atom);
+    }
+
+    /**
+     * Verify if the provided atom is of the `unknown` variant.
+     *
+     * @group Atom
+     */
+    static isUnknown<T, E>(atom: Atom<T, E>): atom is AtomUnknown {
+        return isUnknown(atom);
+    }
+}

src/util.ts

@@ -1,4 +1,4 @@
-import type { Stream } from ".";
+import Stream from ".";
 
 /**
  * Maybe it's a promise. Maybe it's not. Who's to say.