fix(api): better typings and api, and added some documentation

Author: nutgaard

README.md

@@ -0,0 +1,71 @@
+# Data-pack
+
+Utility pack for working with random data
+
+## File utils
+
+Simple wrapper around `fs` and `fs/promises`.
+
+```typescript
+function read(path: string): Promise<string>;
+function readSync(path: string): string;
+function readJSON<T>(path: string): Promise<T>;
+function readJSONSync<T>(path: string): Promise<T>;
+
+function write(path: string, content: any): Promise<void>;
+function writeSync(path: string, content: any): void;
+function withWriteStream(path: string, block: (stream: WriteStream) => void): void;
+```
+
+## CSV
+
+Utilities for parsing and writing CSV files
+
+```typescript
+function* parseCSV(content: string, delimiter: string = ''): Generator<Array<string>, void>;
+function* parseCSVSync(content: string, delimiter: string = ''): Array<Array<string>>;
+function* parseCSVToFlow(content: string, delimiter: string = ''): GeneratorFlow<Array<string>>;
+```
+
+## JSON
+
+Utilities for parsing and writing JSON
+
+```typescript
+function serialize(content: any): string;
+function deserialize<T>(content: string): T;
+```
+
+## Generator flows
+
+Utilities for working with generators as if they are arrays
+
+```typescript
+// Creation
+const flow = GeneratorFlow.ofArray([1, 2, 3, 4]);
+const numFlow = GeneratorFlow.ofArray([5, 6]);
+const otherFlow = new GeneratorFlow(function* () {
+    yield 'a';
+    yield 'b';
+    yield 'c';
+    yield 'd';
+});
+
+// Stream functions
+flow.skipWhile((it) => it < 2); // Flow[3,4]
+flow.takeWhile((it) => it < 2); // Flow[1]
+flow.skip(2); // Flow[3,4]
+flow.tail(); // Flow[2,3,4]
+flow.take(2); // Flow[1,2]
+flow.map((it) => it * 2); // Flow[2,4,6,8]
+flow.flatMap((it) => [it * 2]); // Flow[2,4,6,8]
+flow.filter((it) => it % 2 == 0); // Flow[2,4]
+flow.zip(otherFlow); // Flow[[1, 'a'], [2, 'b'], [3, 'c'], [4, 'd']]
+flow.cartesianProduct(otherFlow); // Flow[[1, 'a'], [1, 'b'], [1, 'c'], [1, 'd'], [2, 'a'], ... [4, 'd']]
+flow.concat(otherFlow); // Flow[1, 2, 3, 4, 5, 6]
+flow.peek(console.log); // Flow[1, 2, 3, 4]
+flow.reduce(add, 0); // 10
+flow.size(); // 4
+flow.toArray(); // [1, 2, 3, 4]
+flow.toSet(); // Set<1, 2, 3, 4>
+```

src/file.ts

@@ -9,10 +9,11 @@ export async function read(path: string): Promise<string> {
 export function readSync(path: string): string {
     return fs.readFileSync(path, 'utf8');
 }
-export async function readJSON(path: string): Promise<string> {
-    return fsP.readFile(path, 'utf8').then(deserialize);
+export async function readJSON<T>(path: string): Promise<T> {
+    const content = await read(path);
+    return deserialize<T>(content);
 }
-export function readJSONSync(path: string): string {
+export function readJSONSync<T>(path: string): T {
     return deserialize(fs.readFileSync(path, 'utf8'));
 }
 

src/generator-flow.ts

@@ -144,10 +144,11 @@ export class GeneratorFlow<T = unknown> {
         return count;
     }
 
-    peek() {
+    peek(block: (t: T) => void) {
         const thisGenerator = this.generator();
         return new GeneratorFlow(function* () {
             for (const val of thisGenerator) {
+                block(val);
                 yield val;
             }
         });

src/json.ts

@@ -1,11 +1,7 @@
-export function serialize(content: any) {
+export function serialize(content: any): string {
     return typeof content === 'string' ? content : JSON.stringify(content, null, 2);
 }
 
-export function deserialize(content: string) {
-    try {
-        return JSON.parse(content);
-    } catch (e: unknown) {
-        return content;
-    }
+export function deserialize<T>(content: string): T {
+    return JSON.parse(content);
 }

test/json.test.ts

@@ -11,7 +11,6 @@ test('should serialize objects and arrays', () => {
 });
 
 test('should deserialize json', () => {
-    assertThat('content', deserialize('content'), 'array is deserialized');
     assertThat(['content'], deserialize('[\n  "content"\n]'), 'array is deserialized');
     assertThat({ content: 'hei' }, deserialize('{\n  "content": "hei"\n}'), 'object is deserialized');
 });