@sergdudko/objectstream 3.2.25 → 4.0.0

package/README.md

@@ -1,6 +1,6 @@
 # @sergdudko/objectstream
 
-Revolutionize Your JSON Handling with Streamlined Efficiency: Seamlessly Convert JSON from String or Transform JSON to Drain with this Powerful Stream Creation Tool. Harness the Power of Object Streams for Swift and Seamless Data Processing!
+A powerful and efficient Node.js library for streaming JSON processing. Transform JSON strings to objects and objects to JSON strings with support for custom separators, multiple encodings, and high-performance streaming operations.
 
 [![npm](https://img.shields.io/npm/v/@sergdudko/objectstream.svg)](https://www.npmjs.com/package/@sergdudko/objectstream)
 [![npm](https://img.shields.io/npm/dy/@sergdudko/objectstream.svg)](https://www.npmjs.com/package/@sergdudko/objectstream)
@@ -8,101 +8,358 @@ Revolutionize Your JSON Handling with Streamlined Efficiency: Seamlessly Convert
 ![GitHub last commit](https://img.shields.io/github/last-commit/siarheidudko/objectstream.svg)
 ![GitHub release](https://img.shields.io/github/release/siarheidudko/objectstream.svg)
 
-- Based on native methods of NodeJS
+## ✨ Features
 
-## INSTALL
+- **Dual Package**: Full ES Modules (ESM) and CommonJS (CJS) support
+- **TypeScript**: Complete type definitions included
+- **High Performance**: Based on native Node.js stream methods
+- **Multiple Encodings**: Support for utf8, base64, latin1, binary, and hex
+- **Custom Separators**: Configure start, middle, and end separators
+- **Memory Efficient**: Streaming approach for large JSON datasets
+- **Zero Dependencies**: No external dependencies
+
+## 📦 Installation
 
 ```bash
- npm i @sergdudko/objectstream --save
+npm install @sergdudko/objectstream
 ```
 
-## DOCS
+## 🚀 Quick Start
+
+### ESM (ES Modules)
 
-[See docs](https://siarheidudko.github.io/objectstream/index.html)
+```javascript
+import { Parser, Stringifer } from '@sergdudko/objectstream';
 
-## SUPPORTED ENCODING
+// String to Object conversion
+const parser = new Parser();
+parser.on('data', (obj) => {
+  console.log('Parsed object:', obj);
+});
+parser.write('{"name":"John","age":30}');
+parser.end();
 
-| Stream     | incoming stream                   | outgoing stream                   |
-| ---------- | --------------------------------- | --------------------------------- |
-| Stringifer | utf8 (object mode)                | utf8, base64, latin1, binary, hex |
-| Parser     | utf8, base64, latin1, binary, hex | utf8 (object mode)                |
+// Object to String conversion
+const stringifer = new Stringifer();
+stringifer.on('data', (jsonString) => {
+  console.log('JSON string:', jsonString.toString());
+});
+stringifer.write({ name: 'John', age: 30 });
+stringifer.end();
+```
 
-## USE
+### CommonJS
 
-```js
-// REQUIRE OR IMPORT CLASS
+```javascript
+const { Parser, Stringifer } = require('@sergdudko/objectstream');
 
-const Stringifer = require("@sergdudko/objectstream").Stringifer;
-const Parser = require("@sergdudko/objectstream").Parser;
-// or use import
-import { Stringifer, Parser } from "@sergdudko/objectstream";
+// Or using default export
+const objectstream = require('@sergdudko/objectstream');
+const { Parser, Stringifer } = objectstream.default;
+```
 
-// CREATE STREAM
+### TypeScript
 
-const firstSeparator = "[";
-const middleSeparator = ",";
-const endSeparator = "]";
-const stringToObject = new Parser(
-  firstSeparator,
-  middleSeparator,
-  endSeparator
-);
-const objectToString = new Stringifer(
-  firstSeparator,
-  middleSeparator,
-  endSeparator
-);
+```typescript
+import { Parser, Stringifer } from '@sergdudko/objectstream';
 
-// EVENTS
+interface User {
+  name: string;
+  age: number;
+}
 
-stringToObject.on("data", (e) => {
-  // e - is Object
+const parser = new Parser();
+parser.on('data', (user: User) => {
+  console.log(`User: ${user.name}, Age: ${user.age}`);
 });
-stringToObject.on("error", (d) => {
-  // e - Array of Error
+```
+
+## 📚 API Reference
+
+### Parser Class
+
+Transform stream that converts JSON strings to JavaScript objects.
+
+#### Constructor
+
+```typescript
+new Parser(start?: string, middle?: string, end?: string)
+```
+
+#### Parameters
+
+- `start` (optional): First separator character (default: none)
+- `middle` (optional): Middle separator character (default: none)  
+- `end` (optional): End separator character (default: none)
+
+#### Methods
+
+- `setEncoding(encoding)`: Set input encoding (`utf8`, `utf-8`, `base64`, `latin1`, `binary`, `hex`)
+
+#### Events
+
+- `data`: Emitted when an object is parsed
+- `error`: Emitted when parsing fails
+- `end`: Emitted when stream ends
+- `finish`: Emitted when stream finishes
+
+### Stringifer Class
+
+Transform stream that converts JavaScript objects to JSON strings.
+
+#### Constructor
+
+```typescript
+new Stringifer(start?: string, middle?: string, end?: string)
+```
+
+#### Parameters
+
+- `start` (optional): First separator character (default: none)
+- `middle` (optional): Middle separator character (default: none)
+- `end` (optional): End separator character (default: none)
+
+#### Methods
+
+- `setEncoding(encoding)`: Set output encoding (`utf8`, `utf-8`, `base64`, `latin1`, `binary`, `hex`)
+
+#### Events
+
+- `data`: Emitted when JSON string is generated
+- `error`: Emitted when stringification fails
+- `end`: Emitted when stream ends
+- `finish`: Emitted when stream finishes
+
+## 💡 Usage Examples
+
+### Basic JSON Processing
+
+```javascript
+import { Parser, Stringifer } from '@sergdudko/objectstream';
+
+const parser = new Parser();
+const stringifer = new Stringifer();
+
+// Parse JSON string
+parser.on('data', (obj) => {
+  console.log('Parsed:', obj);
 });
-stringToObject.on("end", () => {
-  // end event
+
+parser.write('{"message":"Hello World"}');
+parser.end();
+
+// Stringify object
+stringifer.on('data', (data) => {
+  console.log('Stringified:', data.toString());
 });
-stringToObject.on("finish", () => {
-  // finish event
+
+stringifer.write({ message: 'Hello World' });
+stringifer.end();
+```
+
+### Custom Separators for JSON Arrays
+
+```javascript
+import { Parser, Stringifer } from '@sergdudko/objectstream';
+
+// Process JSON array with custom separators
+const parser = new Parser('[', ',', ']');
+const stringifer = new Stringifer('[', ',', ']');
+
+stringifer.on('data', (data) => {
+  console.log('JSON Array chunk:', data.toString());
+});
+
+// Write multiple objects
+stringifer.write({ id: 1, name: 'Alice' });
+stringifer.write({ id: 2, name: 'Bob' });
+stringifer.write({ id: 3, name: 'Charlie' });
+stringifer.end(); // Output: [{"id":1,"name":"Alice"},{"id":2,"name":"Bob"},{"id":3,"name":"Charlie"}]
+```
+
+### Different Encodings
+
+```javascript
+import { Parser, Stringifer } from '@sergdudko/objectstream';
+
+// Base64 encoding
+const stringifer = new Stringifer();
+stringifer.setEncoding('base64');
+
+stringifer.on('data', (data) => {
+  console.log('Base64 JSON:', data); // Base64 encoded JSON string
 });
-objectToString.on("data", (e) => {
-  // e - is Buffer (deault, if you need a string use setEncoding)
+
+stringifer.write({ encoded: true });
+stringifer.end();
+
+// Parse Base64 encoded JSON
+const parser = new Parser();
+parser.setEncoding('base64');
+
+parser.on('data', (obj) => {
+  console.log('Decoded object:', obj);
 });
-objectToString.on("error", (d) => {
-  // e - Array of Error
+
+// Write base64 encoded JSON
+parser.write(Buffer.from('{"decoded":true}').toString('base64'));
+parser.end();
+```
+
+### Stream Piping
+
+```javascript
+import { Parser, Stringifer } from '@sergdudko/objectstream';
+import { Transform } from 'stream';
+
+// Create a processing pipeline
+const parser = new Parser();
+const processor = new Transform({
+  objectMode: true,
+  transform(obj, encoding, callback) {
+    // Process each object
+    obj.processed = true;
+    obj.timestamp = Date.now();
+    callback(null, obj);
+  }
 });
-objectToString.on("end", () => {
-  // end event
+const stringifer = new Stringifer();
+
+// Pipe the streams together
+parser
+  .pipe(processor)
+  .pipe(stringifer)
+  .on('data', (data) => {
+    console.log('Processed JSON:', data.toString());
+  });
+
+// Input data
+parser.write('{"name":"test"}');
+parser.end();
+```
+
+### Error Handling
+
+```javascript
+import { Parser, Stringifer } from '@sergdudko/objectstream';
+
+const parser = new Parser();
+
+parser.on('data', (obj) => {
+  console.log('Valid object:', obj);
 });
-objectToString.on("finish", () => {
-  // finish event
+
+parser.on('error', (errors) => {
+  console.error('Parsing errors:', errors);
 });
 
-// CHANGE ENCODING
+// Valid JSON
+parser.write('{"valid":true}');
+
+// Invalid JSON
+parser.write('{"invalid":}');
+
+parser.end();
+```
+
+## 🎯 Supported Encodings
+
+| Encoding | Input | Output | Description |
+|----------|-------|--------|-------------|
+| `utf8` (default) | ✅ | ✅ | Standard UTF-8 text |
+| `utf-8` | ✅ | ✅ | Alias for utf8 |
+| `base64` | ✅ | ✅ | Base64 encoded data |
+| `latin1` | ✅ | ✅ | Latin-1 encoding |
+| `binary` | ✅ | ✅ | Binary data encoding |
+| `hex` | ✅ | ✅ | Hexadecimal encoding |
 
-stringToObject.setEncoding("latin1");
-objectToString.setEncoding("latin1");
+## ⚡ Performance
 
-// WRITE DATA (example for utf8)
+ObjectStream is optimized for high-performance streaming operations:
 
-stringToObject.write('{"boolean":true}');
-objectToString.write({ boolean: true });
+- **Memory Efficient**: Processes data in chunks, suitable for large JSON files
+- **Zero-Copy Operations**: Minimizes memory copying where possible
+- **Stream-Based**: Non-blocking operations using Node.js streams
+- **Optimized Parsing**: Efficient JSON parsing with error recovery
 
-// PIPE
+## 🧪 Testing
 
-stringToObject.pipe(objectToString);
+The library includes comprehensive TypeScript tests:
+
+```bash
+npm test
+```
+
+Test coverage includes:
+
+- ✅ Parser functionality with various data types
+- ✅ Stringifer functionality with validation
+- ✅ Custom separators and encodings
+- ✅ Stream piping and event handling
+- ✅ Error handling and edge cases
+- ✅ Performance benchmarks
+- ✅ ESM/CJS compatibility
+
+## 🏗️ Development
+
+```bash
+# Install dependencies
+npm install
+
+# Run tests
+npm test
+
+# Build dual package (ESM + CJS)
+npm run build
+
+# Lint code
+npm run lint
 ```
 
-## EXAMPLE
+## 📄 Package Structure
+
+```
+dist/
+├── esm/          # ES Modules build
+├── cjs/          # CommonJS build
+└── types/        # Shared TypeScript definitions
+```
+
+## 🤝 Contributing
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add some amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+## 🎯 Version History
+
+- **v3.x**: TypeScript rewrite, dual package support, modern Node.js features
+- **v2.x**: Enhanced performance and encoding support
+- **v1.x**: Initial release with basic streaming functionality
+
+## 📄 License
+
+MIT License - see [LICENSE](./LICENSE) file for details.
+
+## 🆘 Support
+
+- 📝 **Issues**: [GitHub Issues](https://github.com/siarheidudko/objectstream/issues)
+- 💬 **Discussions**: [GitHub Discussions](https://github.com/siarheidudko/objectstream/discussions)
+- 📧 **Email**: [siarhei@dudko.dev](mailto:siarhei@dudko.dev)
+
+## 💝 Support This Project
 
-[see test directory](https://github.com/siarheidudko/objectstream/tree/master/test)
+If Redux Cluster helps you build amazing applications, consider supporting its development:
 
-## OLDER VERSIONS
+- ☕ **[Buy me a coffee](https://www.buymeacoffee.com/dudko.dev)**
+- 💳 **[PayPal](https://paypal.me/dudkodev)**
+- 🎯 **[Patreon](https://patreon.com/dudko_dev)**
+- 🌐 **[More options](http://dudko.dev/donate)**
 
-- [v2.0.5](https://www.npmjs.com/package/@sergdudko/objectstream/v/2.0.5) - supported Node 8
+Your support helps maintain and improve Redux Cluster for the entire community!
 
-## LICENSE
+---
 
-MIT
+**Made with ❤️ by [Siarhei Dudko](https://github.com/siarheidudko)**

package/dist/cjs/index.js

@@ -0,0 +1,29 @@
+"use strict";
+/**
+ * Module for stream conversion Json to String and String to Json
+ * @module sergdudko/objectstream
+ * @author Siarhei Dudko <slavianich@gmail.com>
+ * @copyright 2020
+ * @license MIT
+ * @version 2.0.0
+ * @requires stream
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Stringifer = exports.Parser = void 0;
+const Parser_1 = require("./classes/Parser");
+Object.defineProperty(exports, "Parser", { enumerable: true, get: function () { return Parser_1.Parser; } });
+const Stringifer_1 = require("./classes/Stringifer");
+Object.defineProperty(exports, "Stringifer", { enumerable: true, get: function () { return Stringifer_1.Stringifer; } });
+// Default export for CommonJS compatibility
+const objectstream = {
+    /**
+     * Object to String stream
+     */
+    Stringifer: Stringifer_1.Stringifer,
+    /**
+     * String to Object stream
+     */
+    Parser: Parser_1.Parser,
+};
+exports.default = objectstream;
+//# sourceMappingURL=index.js.map

package/dist/esm/classes/Parser.js

@@ -0,0 +1,231 @@
+import { Transform } from "stream";
+import { validator } from "../utils/global";
+/**
+ * @class Parser
+ *
+ * Сreates an instance of Parser (String to Json conversion stream)
+ */
+export class Parser extends Transform {
+    /**
+     *
+     * @param start - first separator
+     * @param middle - middle separator
+     * @param end - end separator
+     */
+    constructor(start, middle, end) {
+        super({ highWaterMark: 64 * 1024, objectMode: true });
+        if (typeof start !== "undefined" &&
+            (typeof start !== "string" ||
+                Buffer.byteLength(start) > 1 ||
+                start.match(/["{}]/)))
+            throw new Error("Argument start require one byte String!");
+        if (typeof middle !== "undefined" &&
+            (typeof middle !== "string" ||
+                Buffer.byteLength(middle) > 1 ||
+                middle.match(/["{}]/)))
+            throw new Error("Argument separator require one byte String!");
+        if (typeof end !== "undefined" &&
+            (typeof end !== "string" ||
+                Buffer.byteLength(end) > 1 ||
+                end.match(/["{}]/)))
+            throw new Error("Argument end require one byte String!");
+        this.__separators = {
+            start: Buffer.from(start ? start : "", "utf8")[0],
+            middle: Buffer.from(middle ? middle : "", "utf8")[0],
+            end: Buffer.from(end ? end : "", "utf8")[0],
+        };
+        this.__clear();
+        this.__bytesRead = 0;
+        this.__encoding = "utf8";
+        this.setDefaultEncoding(this.__encoding);
+        this.__buffers = [];
+        this.__leftBrace = 0;
+        this.__rightBrace = 0;
+        this.__openQuotes = false;
+    }
+    /**
+     * clear buffer and reset counters
+     *
+     * @private
+     */
+    __clear() {
+        this.__buffers = [];
+        this.__leftBrace = 0;
+        this.__rightBrace = 0;
+        this.__openQuotes = false;
+    }
+    /**
+     * basic stream handler
+     */
+    __handler(buffer, s, errors) {
+        if (this.__buffers.length > 65536) {
+            const _nbuffer = Buffer.concat(this.__buffers);
+            this.__buffers = [];
+            this.__buffers.push(_nbuffer);
+        }
+        if (this.__leftBrace !== 0) {
+            this.__buffers.push(buffer.slice(s, s + 1));
+        }
+        else if (this.__separators.start !== buffer[s] &&
+            this.__separators.end !== buffer[s] &&
+            this.__separators.middle !== buffer[s] &&
+            0x20 !== buffer[s] &&
+            0x0d !== buffer[s] &&
+            0x0a !== buffer[s] &&
+            0x09 !== buffer[s]) {
+            errors.push(new Error("Unexpected token " +
+                buffer.slice(s, s + 1).toString(this.__encoding) +
+                " in JSON at position " +
+                (this.__bytesRead + s)));
+        }
+    }
+    /**
+     * Data event handler
+     *
+     * @private
+     * @param string - string or buffer data
+     * @param encoding - stream encoding
+     * @param callback - callback function
+     */
+    _transform(string, 
+    // eslint-disable-next-line
+    encoding = this.__encoding, callback = () => {
+        return;
+    }) {
+        if (typeof string === "undefined") {
+            callback();
+            return;
+        }
+        if (string === null) {
+            this._final(() => {
+                callback();
+            });
+            return;
+        }
+        const _buffer = typeof string === "string" ? Buffer.from(string, encoding) : string;
+        if (!(_buffer instanceof Buffer)) {
+            callback([
+                new Error("Incoming data type is " +
+                    typeof _buffer +
+                    ", require data type is String!"),
+            ]);
+            return;
+        }
+        if (Parser.__empty.equals(_buffer)) {
+            callback();
+            return;
+        }
+        const errors = [];
+        for (let s = 0; s < _buffer.length; s++) {
+            switch (_buffer[s]) {
+                case 0x7b:
+                    this.__leftBrace += 1;
+                    this.__handler(_buffer, s, errors);
+                    break;
+                case 0x7d:
+                    this.__rightBrace += 1;
+                    this.__handler(_buffer, s, errors);
+                    break;
+                case 0x08:
+                case 0x09:
+                case 0x0a:
+                case 0x0c:
+                case 0x0d:
+                case 0x00:
+                case 0x0b:
+                    if (this.__openQuotes && this.__leftBrace !== 0)
+                        this.__buffers.push(Buffer.from("\\u" + ("0000" + _buffer[s].toString(16)).slice(-4), "utf8"));
+                    break;
+                case 0x22:
+                    if (_buffer[s - 1] !== 0x5c)
+                        if (this.__openQuotes)
+                            this.__openQuotes = false;
+                        else if (this.__leftBrace !== 0)
+                            this.__openQuotes = true;
+                    this.__handler(_buffer, s, errors);
+                    break;
+                default:
+                    this.__handler(_buffer, s, errors);
+                    break;
+            }
+            if (this.__leftBrace !== 0 && this.__leftBrace === this.__rightBrace) {
+                try {
+                    const _buf = Buffer.concat(this.__buffers);
+                    const _str = _buf.toString("utf8");
+                    const _object = JSON.parse(_str);
+                    if (validator(_object, false)) {
+                        this.__clear();
+                        this.push(_object);
+                    }
+                    else {
+                        this.__clear();
+                        errors.push(new Error("Validation failed, incoming data type is not pure Object!"));
+                    }
+                }
+                catch (err) {
+                    this.__clear();
+                    errors.push(err);
+                }
+            }
+            else if (this.__leftBrace < this.__rightBrace) {
+                this.__clear();
+                errors.push(new Error("Parsing error, clear buffer!"));
+            }
+        }
+        if (errors.length > 0)
+            callback(errors);
+        else
+            callback();
+        this.__bytesRead += _buffer.byteLength;
+    }
+    /**
+     * Flush event handler
+     *
+     * @private
+     * @param callback - callback function
+     */
+    _flush(callback = () => {
+        return;
+    }) {
+        this.__clear();
+        callback();
+    }
+    /**
+     * End event handler
+     *
+     * @private
+     * @param callback - callback function
+     */
+    _final(callback = () => {
+        return;
+    }) {
+        if (this.__buffers.length === 0) {
+            callback();
+            return;
+        }
+        try {
+            const _buf = Buffer.concat(this.__buffers);
+            const _str = _buf.toString("utf8");
+            JSON.parse(_str);
+            callback([new Error("Raw object detected!")]);
+        }
+        catch (err) {
+            callback([err]);
+        }
+    }
+    /**
+     * set stream encoding
+     */
+    setEncoding(encoding) {
+        this.__encoding = encoding;
+        this.setDefaultEncoding(this.__encoding);
+        return this;
+    }
+}
+/**
+ * empty buffer
+ *
+ * @private
+ */
+Parser.__empty = Buffer.from("");
+//# sourceMappingURL=Parser.js.map