nucleus-mold 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Иван Семёнов
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,92 @@
+# nucleus-mold
+
+## A lightweight and efficient utility for serialization and polymorphic deserialization of complex objects in TypeScript 5.0+
+
+## 💻 Usage Example
+### 1. Define Your Models
+```typescript
+import { Nucleus } from './json-mold';
+@Nucleus({ as: 'System.Wallet' })
+export class Wallet {
+    public balance: number = 0;
+
+    // Private constructor is supported!
+    private constructor(balance: number) {
+        this.balance = balance;
+    }
+
+    public static create(balance: number) {
+        return new Wallet(balance);
+    }
+
+    public deposit(amount: number) {
+        this.balance += amount;
+    }
+}
+
+@Nucleus({ as: 'System.User' })
+export class User {
+    constructor(
+        public id: string,
+        public name: string,
+        public wallet: Wallet // Nested @Nucleus object
+    ) {}
+
+    public greet() {
+        return `Hello, I'm ${this.name}. Balance: ${this.wallet.balance}$`;
+    }
+}
+```
+
+### 2. Serialize and Deserialize
+```typescript
+import { JsonMold, isSerializable } from './json-mold';
+import { User, Wallet } from './models';
+
+const wallet = Wallet.create(250);
+const user = new User("usr_100", "Alex", wallet);
+
+console.log(isSerializable(user)); // true
+
+// --- CONCEAL (Serialize) ---
+const jsonStr = JsonMold.conceal(user);
+console.log(jsonStr);
+/*
+Output:
+{
+  "__type": "System.User",
+  "id": "usr_100",
+  "name": "Alex",
+  "wallet": {
+    "__type": "System.Wallet",
+    "balance": 250
+  }
+}
+*/
+
+// --- REVEAL (Deserialize) ---
+const restoredUser = JsonMold.reveal<User>(jsonStr);
+
+// It recovers the exact prototype chains without invoking constructors
+console.log(restoredUser instanceof User);        // true
+console.log(restoredUser.wallet instanceof Wallet); // true
+
+// Methods and 'this' context are fully functional
+restoredUser.wallet.deposit(50);
+console.log(restoredUser.greet()); // "Hello, I'm Alex. Balance: 300$"
+```
+
+## 🛠️ API Reference
+
+### `@Nucleus(options?: { as?: string })`
+A class decorator that registers the target class in the registry and injects the `toJSON` method.
+* `options.as` *(optional)*: A unique string identifier to prevent name collisions across different modules.
+
+### `JsonMold.conceal(obj: any, space?: number): string`
+Converts a domain object into a JSON string. Automatically attaches the `__type` meta key to any nested `@Nucleus` instances.
+
+### `JsonMold.reveal<T = any>(json: string): T`
+Parses a JSON string and recursively rebuilds instances of registered classes by their `__type` token using `Object.create`.
+
+### `isSerializable(obj: any): boolean`
+A helper function that returns `true` if the passed object comes from a class decorated with `@Nucleus`.

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "nucleus-mold",
+  "version": "1.0.0",
+  "description": "",
+  "main": "index.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/M2K-5F/nucleus-mold.git"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "bugs": {
+    "url": "https://github.com/M2K-5F/nucleus-mold/issues"
+  },
+  "homepage": "https://github.com/M2K-5F/nucleus-mold#readme"
+}

package/src/index.ts

@@ -0,0 +1,65 @@
+const SERIALIZABLE_MARKER = Symbol('serializable')
+const TYPE_KEY = '__type'
+
+const registry = new Map<string, Function>()
+
+export function Nucleus(options?: { as?: string }) {
+    return function<T extends Function>(
+        target: T,
+        context: ClassDecoratorContext<any>
+    ): void {
+        const className = options?.as || context?.name || target.name
+        registry.set(className, target)
+
+        const proto = (target as any).prototype
+
+        Object.defineProperty(proto, SERIALIZABLE_MARKER, {
+            value: true,
+            writable: false,
+            enumerable: false,
+            configurable: true
+        })
+
+        proto.toJSON = function () {
+            return {
+                [TYPE_KEY]: className,
+                ...Object.fromEntries(
+                    Object.getOwnPropertyNames(this).map(key => [key, (this as any)[key]])
+                )
+            }
+        }
+    }
+}
+
+
+export const JsonMold = {
+    conceal: (obj: any, space?: number) => {
+        return JSON.stringify(obj, null, space)
+    },
+
+    reveal: <T = any>(json: string): T => {
+        return JSON.parse(json, (key, value) => {
+            if (value && typeof value === 'object' && value[TYPE_KEY]) {
+                const TargetClass = registry.get(value[TYPE_KEY])
+                
+                if (TargetClass) {
+                    const instance = Object.create(TargetClass.prototype)
+                    
+                    for (const [k, v] of Object.entries(value)) {
+                        if (k !== TYPE_KEY) {
+                            (instance as any)[k] = v
+                        }
+                    }
+                    
+                    return instance
+                }
+            }
+            
+            return value
+        })
+    }
+}
+
+export function isSerializable(obj: any): boolean {
+    return obj && obj[SERIALIZABLE_MARKER] === true
+}