protoobject 1.1.30 → 2.0.0

package/README.md

@@ -20,6 +20,107 @@ Inspired by gRPC and Firebase.
  npm i protoobject --save
 ```
 
+## MODULE FORMATS
+
+This library supports both **CommonJS** and **ESM** (ES Modules) formats:
+
+### CommonJS
+
+```javascript
+const { ProtoObject, StaticImplements, protoObjectFactory } = require('protoobject');
+```
+
+### ES Modules (ESM)
+
+```javascript
+import { ProtoObject, StaticImplements, protoObjectFactory } from 'protoobject';
+```
+
+The library automatically provides the correct format based on your project configuration. No additional setup required!
+
+## 🌐 BROWSER COMPATIBILITY
+
+ProtoObject works in **both Node.js and Browser environments**:
+
+### Browser Usage
+
+For browser compatibility, use the browser-specific import:
+
+```javascript
+// Browser-compatible imports only (excludes Node.js-specific modules)
+import { 
+  ProtoObject, 
+  StaticImplements,
+  protoObjectFactory 
+} from 'protoobject/browser';
+```
+
+### Node.js Usage
+
+For Node.js, use the full import with all modules:
+
+```javascript
+// Full import with all modules including Node.js-specific
+import { 
+  ProtoObject,
+  ProtoObjectSQLite,
+  ProtoObjectTCP,
+  ProtoObjectCrypto,
+  ProtoObjectFS,
+  ProtoObjectStream
+} from 'protoobject';
+```
+
+### Browser Support
+
+- ✅ Chrome 80+
+- ✅ Firefox 75+
+- ✅ Safari 13+
+- ✅ Edge 80+
+- ✅ ES6+ and ES Modules support
+
+### What Works in Browser
+
+- ✅ Core ProtoObject functionality
+- ✅ JSON serialization/deserialization
+- ✅ localStorage/sessionStorage integration
+- ✅ Fetch API integration
+- ✅ IndexedDB integration
+- ✅ WebSocket integration
+
+### What's Node.js Only
+
+- ❌ ProtoObjectSQLite (use IndexedDB in browser)
+- ❌ ProtoObjectTCP (use WebSockets/Fetch in browser)
+- ❌ ProtoObjectCrypto (use Web Crypto API in browser)
+- ❌ ProtoObjectFS (use localStorage/IndexedDB/Fetch in browser)
+- ❌ ProtoObjectStream (use browser streams or fetch in browser)
+
+## 📚 EXAMPLES
+
+See the [`examples/`](./examples/) directory for comprehensive usage examples:
+
+- **[Browser Examples](./examples/browser/)** - Browser compatibility with interactive demo
+- **[JavaScript Examples](./examples/javascript/)** - Plain JavaScript usage with CommonJS
+- **[TypeScript Examples](./examples/typescript/)** - Type-safe usage with decorators and interfaces  
+- **[SQL Database Examples](./examples/sql-database/)** - Database integration patterns
+
+## 🧪 TESTING
+
+Run all tests:
+
+```bash
+npm test
+```
+
+Run specific test suites:
+
+```bash
+npm run test:ts    # TypeScript tests
+npm run test:js    # JavaScript tests  
+npm run test:sql   # SQL database tests
+```
+
 ## DOCS
 
 ### The main methods of the ProtoObject class
@@ -453,6 +554,45 @@ export class ApplicationRecord extends BaseRecord<ApplicationRecord> {
 }
 ```
 
-## LICENSE
+## 🤝 Contributing
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+### Development Setup
+
+```bash
+git clone https://github.com/siarheidudko/protoobject.git
+cd protoobject
+npm install
+npm run build
+npm test
+```
+
+## 📄 License
+
+MIT License - see [LICENSE](./LICENSE) file for details.
+
+## 🆘 Support
+
+- 📝 **Issues**: [GitHub Issues](https://github.com/siarheidudko/protoobject/issues)
+- 💬 **Discussions**: [GitHub Discussions](https://github.com/siarheidudko/protoobject/discussions)
+- 📧 **Email**: [siarhei@dudko.dev](mailto:siarhei@dudko.dev)
+
+## 💝 Support This Project
+
+If Redux Cluster helps you build amazing applications, consider supporting its development:
+
+- ☕ **[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)**
+
+Your support helps maintain and improve Redux Cluster for the entire community!
+
+---
 
-MIT
+**Made with ❤️ by [Siarhei Dudko](https://github.com/siarheidudko)**

package/lib/cjs/browser.js

@@ -0,0 +1,28 @@
+"use strict";
+/**
+ * Browser-compatible exports of protoobject
+ * @module protoobject/browser
+ * @author Siarhei Dudko <siarhei@dudko.dev>
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ProtoObjectBrowserStorage = exports.ProtoObjectLocalStorage = exports.protoObjectFactory = exports.StaticImplements = exports.ProtoObject = void 0;
+// Core classes (browser-compatible)
+var proto_object_js_1 = require("./classes/proto-object.js");
+Object.defineProperty(exports, "ProtoObject", { enumerable: true, get: function () { return proto_object_js_1.ProtoObject; } });
+// Decorators (browser-compatible)
+var static_implements_js_1 = require("./decorators/static-implements.js");
+Object.defineProperty(exports, "StaticImplements", { enumerable: true, get: function () { return static_implements_js_1.StaticImplements; } });
+// Utilities (browser-compatible)
+var protoobject_factory_js_1 = require("./utils/protoobject-factory.js");
+Object.defineProperty(exports, "protoObjectFactory", { enumerable: true, get: function () { return protoobject_factory_js_1.protoObjectFactory; } });
+var protoobject_localstorage_js_1 = require("./utils/protoobject-localstorage.js");
+Object.defineProperty(exports, "ProtoObjectLocalStorage", { enumerable: true, get: function () { return protoobject_localstorage_js_1.ProtoObjectLocalStorage; } });
+var protoobject_browser_storage_js_1 = require("./utils/protoobject-browser-storage.js");
+Object.defineProperty(exports, "ProtoObjectBrowserStorage", { enumerable: true, get: function () { return protoobject_browser_storage_js_1.ProtoObjectBrowserStorage; } });
+// Note: The following modules are Node.js-specific and not available in browser:
+// - ProtoObjectSQLite (requires node:sqlite and node:crypto)
+// - ProtoObjectTCP (requires node:net)
+// - ProtoObjectCrypto (requires node:crypto)
+// - ProtoObjectFS (requires node:fs, node:path, node:events)
+// - ProtoObjectStream (requires node:stream via @sergdudko/objectstream)
+//# sourceMappingURL=browser.js.map

package/lib/cjs/browser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser.js","sourceRoot":"","sources":["../../src/browser.ts"],"names":[],"mappings":";AAAA;;;;GAIG;;;AAEH,oCAAoC;AACpC,6DAAwD;AAA/C,8GAAA,WAAW,OAAA;AAEpB,kCAAkC;AAClC,0EAAqE;AAA5D,wHAAA,gBAAgB,OAAA;AAWzB,iCAAiC;AACjC,yEAAoE;AAA3D,4HAAA,kBAAkB,OAAA;AAC3B,mFAA8E;AAArE,sIAAA,uBAAuB,OAAA;AAChC,yFAIgD;AAH9C,2IAAA,yBAAyB,OAAA;AAK3B,iFAAiF;AACjF,6DAA6D;AAC7D,uCAAuC;AACvC,6CAA6C;AAC7C,6DAA6D;AAC7D,yEAAyE"}

package/lib/cjs/classes/proto-object-crypto.js

@@ -0,0 +1,133 @@
+"use strict";
+/**
+ * ProtoObjectCrypto - Cryptographic utilities for ProtoObject
+ * @description Provides encryption, hashing, and digital signature capabilities
+ * @author Siarhei Dudko <siarhei@dudko.dev>
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ProtoObjectCrypto = exports.HashAlgorithm = exports.EncryptionAlgorithm = void 0;
+const node_crypto_1 = require("node:crypto");
+const proto_object_js_1 = require("./proto-object.js");
+/* eslint-disable no-unused-vars */
+/**
+ * Encryption algorithms supported
+ */
+var EncryptionAlgorithm;
+(function (EncryptionAlgorithm) {
+    EncryptionAlgorithm["AES256"] = "aes-256-cbc";
+    EncryptionAlgorithm["AES192"] = "aes-192-cbc";
+    EncryptionAlgorithm["AES128"] = "aes-128-cbc";
+})(EncryptionAlgorithm || (exports.EncryptionAlgorithm = EncryptionAlgorithm = {}));
+/**
+ * Hash algorithms supported
+ */
+var HashAlgorithm;
+(function (HashAlgorithm) {
+    HashAlgorithm["SHA256"] = "sha256";
+    HashAlgorithm["SHA512"] = "sha512";
+    HashAlgorithm["MD5"] = "md5";
+})(HashAlgorithm || (exports.HashAlgorithm = HashAlgorithm = {}));
+/* eslint-enable no-unused-vars */
+/**
+ * Base class for Crypto-enabled ProtoObjects
+ */
+class ProtoObjectCrypto extends proto_object_js_1.ProtoObject {
+    constructor(data) {
+        super(data);
+    }
+    /**
+     * Generate hash of the object
+     * @param algorithm - Hash algorithm to use
+     * @returns Hash string
+     */
+    generateHash(algorithm = HashAlgorithm.SHA256) {
+        const data = JSON.stringify(this.toJSON());
+        const hash = (0, node_crypto_1.createHash)(algorithm).update(data).digest("hex");
+        this._hash = hash;
+        return hash;
+    }
+    /**
+     * Get stored hash
+     * @returns Hash string or undefined
+     */
+    getHash() {
+        return this._hash;
+    }
+    /**
+     * Encrypt object data
+     * @param password - Encryption password
+     * @param algorithm - Encryption algorithm
+     * @returns Encrypted data structure
+     */
+    encrypt(password, algorithm = EncryptionAlgorithm.AES256) {
+        const data = JSON.stringify(this.toJSON());
+        const salt = (0, node_crypto_1.randomBytes)(16);
+        const iv = (0, node_crypto_1.randomBytes)(16);
+        // Derive key from password and salt
+        const key = (0, node_crypto_1.createHash)("sha256")
+            .update(password + salt.toString("hex"))
+            .digest();
+        const cipher = (0, node_crypto_1.createCipheriv)(algorithm, key, iv);
+        let encrypted = cipher.update(data, "utf8", "hex");
+        encrypted += cipher.final("hex");
+        return {
+            algorithm,
+            data: encrypted,
+            iv: iv.toString("hex"),
+            salt: salt.toString("hex"),
+        };
+    }
+    /**
+     * Decrypt encrypted data
+     * @param encryptedData - Encrypted data structure
+     * @param password - Decryption password
+     * @returns Decrypted object data
+     */
+    static decrypt(encryptedData, password) {
+        const { algorithm, data, iv, salt } = encryptedData;
+        // Derive key from password and salt
+        const key = (0, node_crypto_1.createHash)("sha256")
+            .update(password + salt)
+            .digest();
+        const decipher = (0, node_crypto_1.createDecipheriv)(algorithm, key, Buffer.from(iv, "hex"));
+        let decrypted = decipher.update(data, "hex", "utf8");
+        decrypted += decipher.final("utf8");
+        return JSON.parse(decrypted);
+    }
+    /**
+     * Generate random salt for encryption
+     * @param length - Salt length in bytes
+     * @returns Hex string salt
+     */
+    static generateSalt(length = 16) {
+        return (0, node_crypto_1.randomBytes)(length).toString("hex");
+    }
+    /**
+     * Verify hash of the object
+     * @param expectedHash - Expected hash value
+     * @param algorithm - Hash algorithm used
+     * @returns True if hash matches
+     */
+    verifyHash(expectedHash, algorithm = HashAlgorithm.SHA256) {
+        const currentHash = this.generateHash(algorithm);
+        return currentHash === expectedHash;
+    }
+    /**
+     * Create encrypted backup of the object
+     * @param password - Encryption password
+     * @param algorithm - Encryption algorithm
+     * @returns Encrypted backup data
+     */
+    createEncryptedBackup(password, algorithm = EncryptionAlgorithm.AES256) {
+        const hash = this.generateHash();
+        const encrypted = this.encrypt(password, algorithm);
+        return {
+            hash,
+            encrypted,
+            timestamp: Date.now(),
+            algorithm,
+        };
+    }
+}
+exports.ProtoObjectCrypto = ProtoObjectCrypto;
+//# sourceMappingURL=proto-object-crypto.js.map

package/lib/cjs/classes/proto-object-crypto.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"proto-object-crypto.js","sourceRoot":"","sources":["../../../src/classes/proto-object-crypto.ts"],"names":[],"mappings":"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"}