@kogs/utils - npm Package Compare versions

Comparing version 1.0.7 to 1.1.7

index.d.ts

+/// <reference types="node" />
+/// <reference types="node" />
+import stream from 'node:stream';
+type ReadableChunk = string | Buffer | Uint8Array | null;
+type StreamFilter = (chunk: ReadableChunk) => Promise<boolean>;
+/**
+ * Creates a readable stream and pushes the given array of chunks to it.
+ * @param input - Array of chunks to be pushed to the stream.
+ * @param objectMode - If true, the stream will be in object mode. If false, the stream will be in buffer mode. If undefined, the stream will be in object mode if the first element of the array is an object, and in buffer mode otherwise.
+ * @returns A readable stream that will emit the given array of chunks.
+ */
+export declare function arrayToStream(input: Array<ReadableChunk>, objectMode?: boolean): stream.Readable;
+/**
+ * Consumes a readable stream and returns an array of chunks emitted by the stream.
+ * @param input - Readable stream to be converted to an array.
+ * @returns An array of chunks emitted by the stream.
+ */
+export declare function streamToArray(input: stream.Readable): Promise<Array<ReadableChunk>>;
+/**
+ * Consumes a readable stream and returns a buffer containing the data emitted by the stream.
+ * @param input - Readable stream to be converted to a buffer.
+ * @returns A buffer containing the data emitted by the stream.
+ */
+export declare function streamToBuffer(input: stream.Readable): Promise<Buffer>;
+/**
+ * Creates a transform stream that filters chunks based on the given function.
+ * @param fn - Function that returns true if the chunk should be passed through the stream, and false otherwise.
+ * @param objectMode - If true, the stream will be in object mode. If false, the stream will be in buffer mode.
+ * @returns A transform stream that filters chunks based on the given function.
+ */
+export declare function filterStream(fn: StreamFilter, objectMode?: boolean): stream.Transform;
+/**
+ * Merges the given streams into a single stream.
+ * @param streams - Streams to be merged.
+ * @returns A stream containing the data emitted by the given streams.
+ */
+export declare function mergeStreams(...streams: Array<stream.Readable>): Promise<stream.PassThrough>;
+declare const _default: {
+    arrayToStream: typeof arrayToStream;
+    streamToArray: typeof streamToArray;
+    streamToBuffer: typeof streamToBuffer;
+    filterStream: typeof filterStream;
+    mergeStreams: typeof mergeStreams;
+};
+export default _default;

package.json

 {
 	"name": "@kogs/utils",
-	"version": "1.0.7",
+	"version": "1.1.7",
 	"type": "module",
@@ -25,3 +25,2 @@ "description": "A collection of standalone utility functions.",
 	"devDependencies": {
-		"@kogs/test": "^2.1.2",
 		"@types/node": "^18.11.18",
@@ -28,0 +27,0 @@ "@typescript-eslint/eslint-plugin": "^5.48.0",

README.md

@@ -25,6 +25,101 @@ # @kogs/utils
 
-## Documentation
+## API
 
-> TODO: Add documentation.
+- [`arrayToStream`](#arraytostream) - Convert an array of values to a readable stream.
+- [`streamToArray`](#streamtoarray) - Convert a readable stream to an array of values.
+- [`streamToBuffer`](#streamtobuffer) - Convert a readable stream to a `Buffer`.
+- [`filterStream`](#filterstream) - Create a transform stream that filters stream data.
+- [`mergeStreams`](#mergestreams) - Merge multiple readable streams into a single stream.
 
+### arrayToStream
+`arrayToStream(input: Array<ReadableChunk>, objectMode: boolean = true): stream.Readable`
+
+```js
+// Relevant types:
+type ReadableChunk = string | Buffer | Uint8Array | null;
+```
+
+This method accepts an array of values and returns a readable stream that emits each value in the array.
+
+If `objectMode` is not defined, it will default to `true` if the first element in the `input` array is a non-null object, otherwise it will default to `false`. See the [Node.js documentation](https://nodejs.org/api/stream.html#object-mode) for more information on object mode.
+
+```js
+// Example usage.
+import { arrayToStream } from '@kogs/utils';
+
+const stream = arrayToStream(['foo', 'bar', 'baz']);
+// stream.read() ==== 'foo'
+```
+
+### streamToArray
+`streamToArray(input: stream.Readable): Promise<Array<ReadableChunk>>`
+
+```js
+// Relevant types:
+type ReadableChunk = string | Buffer | Uint8Array | null;
+```
+
+This method accepts a readable stream and returns a promise that resolves with an array of values emitted by the stream.
+
+```js
+// Example usage.
+import { streamToArray } from '@kogs/utils';
+
+const stream = ...; // Readable stream containing 'foo', 'bar', 'baz'.
+const result = await streamToArray(stream);
+// result === ['foo', 'bar', 'baz']
+```
+
+### streamToBuffer
+`streamToBuffer(input: stream.Readable): Promise<Buffer>`
+
+This method accepts a readable stream and returns a promise that resolves with a `Buffer` containing the data emitted by the stream.
+
+```js
+// Example usage.
+import { streamToBuffer } from '@kogs/utils';
+
+const stream = ...; // Readable stream containing 'foo', 'bar', 'baz'.
+const result = await streamToBuffer(stream);
+// `result` is a Buffer[9] containing 'foobarbaz'.
+```
+
+### filterStream
+`filterStream(fn: StreamFilter, objectMode: boolean = true): stream.Transform`
+
+```js
+// Relevant types:
+type StreamFilter = (chunk: ReadableChunk) => Promise<boolean>;
+```
+
+This method accepts a filter function and returns a transform stream that filters the data emitted by a stream.
+
+```js
+// Example usage.
+import { filterStream } from '@kogs/utils';
+
+const stream = ...; // Readable stream containing 'foo', 'bar', 'baz'.
+const filtered = stream.pipe(filterStream(chunk => chunk !== 'bar'));
+
+// `filtered` will emit 'foo' and 'baz'.
+```
+
+### mergeStreams
+`mergeStreams(...streams: Array<stream.Readable>): Promise<stream.PassThrough>`
+
+This method accepts a variable number of readable streams and returns a promise that resolves with a `PassThrough` stream that merges the data emitted by the input streams.
+
+See the [Node.js documentation](https://nodejs.org/api/stream.html#class-streampassthrough) for more information on `PassThrough` streams.
+
+```js
+// Example usage.
+import { mergeStreams } from '@kogs/utils';
+
+const stream1 = ...; // Readable stream containing 'foo', 'bar', 'baz'.
+const stream2 = ...; // Readable stream containing 'qux', 'quux', 'corge'.
+
+const merged = await mergeStreams(stream1, stream2);
+// `merged` will emit 'foo', 'bar', 'baz', 'qux', 'quux', 'corge'.
+```
+
 ## What is `@kogs`?
@@ -31,0 +126,0 @@ `@kogs` is a collection of packages that I've written to consolidate the code I often reuse across my projects with the following goals in mind:

.eslintrc.cjs

-module.exports = {
-	'env': {
-		'node': true,
-		'es2021': true,
-		'jest/globals': true
-	},
-	'extends': [
-		'eslint:recommended',
-		'plugin:@typescript-eslint/recommended'
-	],
-	'ignorePatterns': ['*.js', '*.d.ts'],
-	'overrides': [
-	],
-	'parser': '@typescript-eslint/parser',
-	'parserOptions': {
-		'ecmaVersion': 'latest',
-		'sourceType': 'module'
-	},
-	'plugins': [
-		'@typescript-eslint',
-		'jest'
-	],
-	'rules': {
-		'@typescript-eslint/no-explicit-any': 'error',
-		'@typescript-eslint/no-inferrable-types': 'off',
-		'indent': [
-			'error',
-			'tab'
-		],
-		'linebreak-style': [
-			'error',
-			process.platform === 'win32' ? 'windows' : 'unix'
-		],
-		'quotes': [
-			'error',
-			'single'
-		],
-		'semi': [
-			'error',
-			'always'
-		]
-	}
-};

No alert changes

Improved metrics

Total package byte prevSize

12170

71.65%

Dev dependency count

6

-14.29%

Lines of code

133

2.31%

Number of lines in readme file

139

215.91%

No dependency changes