mutts 1.0.7 → 1.0.9

package/docs/std-decorators.md

@@ -1,4 +1,4 @@
-TODO: redo the doc here
+
 # Standard decorators
 
 A TypeScript library that provides standard decorators that should stop being re-implemented for the 50th time
@@ -189,13 +189,13 @@ When the decorator is applied to a non-getter method:
 3. **Memory overhead**: Cached values are stored indefinitely
 4. **Getter-only**: Can only be applied to getter methods, not setters or regular methods
 
-## Describe
+## Descriptor
 
-The `describe` decorator provides a clean, reusable way to configure property descriptors (enumerable, configurable, writable) for class properties. This decorator uses a functional approach that makes it easy to create reusable descriptor configurations.
+The `descriptor` decorator provides a clean, reusable way to configure property descriptors (enumerable, configurable, writable) for class properties. This decorator uses a functional approach that makes it easy to create reusable descriptor configurations.
 
 ## API Reference
 
-### `describe(descriptor: PropertyDescriptor): <T>(...properties: (keyof T)[]) => GenericClassDecorator<T>`
+### `descriptor(descriptor: PropertyDescriptor): <T>(...properties: (keyof T)[]) => GenericClassDecorator<T>`
 
 A function that creates a decorator to configure property descriptors for specified properties.
 
@@ -207,29 +207,68 @@ A function that creates a decorator to configure property descriptors for specif
 
 **Returns:** A function that takes property names and returns a class decorator
 
+**Flavors:**
+The `descriptor` function is flavored with the following chainable properties:
+- `.enumerable` - Sets enumerable to true
+- `.hidden` - Sets enumerable to false
+- `.configurable` - Sets configurable to true
+- `.frozen` - Sets configurable to false
+- `.writable` - Sets writable to true
+- `.readonly` - Sets writable to false
+
 **Usage Pattern:**
 ```typescript
-const readonly = describe({ writable: false })
-const hidden = describe({ enumerable: false })
-const locked = describe({ configurable: false })
+// Using flavors for single properties
+@descriptor.readonly('id', 'createdAt')
+@descriptor.hidden('_private')
+class MyClass { }
 
-@readonly('id', 'createdAt')
-@hidden('_private')
-@locked('critical')
+// For multiple descriptor properties on the same property, use object syntax
+@descriptor({ writable: false, enumerable: false, configurable: false })('secret')
 class MyClass { }
+
+// Note: Stacking multiple flavored decorators on the same property is not recommended
+// as each decorator creates a new subclass and only the last applied takes effect
 ```
 
 ## Usage Examples
 
+### Using Flavors
+
+```typescript
+import { descriptor } from 'mutts/std-decorators'
+
+// Use flavors directly for cleaner syntax
+@descriptor.readonly('id', 'createdAt')
+@descriptor.hidden('_private', '_cache')
+@descriptor.frozen('critical')
+class User {
+  id: string = 'user-123'
+  name: string = 'John'
+  _private: string = 'secret'
+  _cache: Map<string, any> = new Map()
+  createdAt: Date = new Date()
+  critical: string = 'locked'
+  
+  constructor(name: string) {
+    this.name = name
+  }
+}
+
+const user = new User('Alice')
+console.log(Object.keys(user)) // ['name', 'createdAt'] - only enumerable properties
+// user.id = 'new-id' // TypeError: Cannot assign to read only property 'id'
+```
+
 ### Creating Reusable Decorators
 
 ```typescript
-import { describe } from 'mutts/std-decorators'
+import { descriptor } from 'mutts/std-decorators'
 
 // Create reusable descriptor configurations
-const readonly = describe({ writable: false })
-const hidden = describe({ enumerable: false })
-const locked = describe({ configurable: false })
+const readonly = descriptor.readonly
+const hidden = descriptor.hidden
+const locked = descriptor.frozen
 
 // Use them on classes
 @readonly('id', 'createdAt')
@@ -255,11 +294,10 @@ console.log(Object.keys(user)) // ['id', 'name', 'createdAt', 'critical'] - only
 ### Making Properties Non-Enumerable
 
 ```typescript
-import { describe } from 'mutts/std-decorators'
-
-const hidden = describe({ enumerable: false })
+import { descriptor } from 'mutts/std-decorators'
 
-@hidden('_internal', '_cache', 'debug')
+// Use the hidden flavor directly
+@descriptor.hidden('_internal', '_cache', 'debug')
 class CacheManager {
   public data: any[] = []
   _internal: Map<string, any> = new Map()
@@ -280,13 +318,10 @@ console.log(Object.getOwnPropertyNames(cache)) // ['data', '_internal', '_cache'
 ### Read-Only Properties
 
 ```typescript
-import { describe } from 'mutts/std-decorators'
+import { descriptor } from 'mutts/std-decorators'
 
-const readonly = describe({ writable: false })
-const readonlyLocked = describe({ writable: false, configurable: false })
-
-@readonly('createdAt', 'version')
-@readonlyLocked('id')
+// Use flavors for read-only properties
+@descriptor.readonly('createdAt', 'version')
 class Document {
   id: string
   title: string
@@ -306,25 +341,41 @@ class Document {
 }
 
 const doc = new Document('doc-1', 'My Document')
-// doc.id = 'new-id' // TypeError: Cannot assign to read only property 'id'
 // doc.createdAt = new Date() // TypeError: Cannot assign to read only property 'createdAt'
+// doc.version = 2 // TypeError: Cannot assign to read only property 'version'
 doc.updateTitle('Updated Title') // This works
 ```
 
-### Configuration Control
+### Combining Multiple Flavors
 
 ```typescript
-import { describe } from 'mutts/std-decorators'
+import { descriptor } from 'mutts/std-decorators'
 
-const locked = describe({ configurable: false })
-const frozen = describe({ configurable: false, writable: false })
+// Stack multiple flavored decorators
+@descriptor.readonly('secret')
+@descriptor.hidden('secret')
+@descriptor.frozen('secret')
+class SecureData {
+  public info: string = 'public'
+  secret: string = 'top secret'
+}
 
-@locked('_sealed')
-@frozen('_frozen')
+const data = new SecureData()
+// data.secret = 'leaked' // TypeError: Cannot assign to read only property 'secret'
+console.log(Object.keys(data)) // ['info'] - secret is not enumerable
+// Object.defineProperty(data, 'secret', { value: 'new' }) // TypeError: Cannot redefine property
+```
+
+### Configuration Control
+
+```typescript
+import { descriptor } from 'mutts/std-decorators'
+
+// Use flavors for configuration control
+@descriptor.frozen('_sealed')
 class SecureObject {
   public data: any
   _sealed: string = 'cannot be reconfigured'
-  _frozen: string = 'cannot be changed or reconfigured'
   
   constructor(data: any) {
     this.data = data
@@ -333,41 +384,41 @@ class SecureObject {
 
 const obj = new SecureObject({ key: 'value' })
 // Object.defineProperty(obj, '_sealed', { value: 'new' }) // TypeError: Cannot redefine property
-// Object.defineProperty(obj, '_frozen', { value: 'new' }) // TypeError: Cannot redefine property
 ```
 
 ## Implementation Details
 
 ### Functional Approach
 
-The `describe` decorator uses a functional approach that separates descriptor configuration from property selection:
+The `descriptor` function uses a flavored approach that provides direct access to common configurations:
 
 ```typescript
-// Create reusable configurations once
-const readonly = describe({ writable: false })
-const hidden = describe({ enumerable: false })
-
-// Apply to multiple classes with different properties
-@readonly('id', 'createdAt')
+// Use flavors directly for cleaner syntax
+@descriptor.readonly('id', 'createdAt')
+@descriptor.hidden('internal')
 class User { }
 
+// Or create reusable aliases
+const readonly = descriptor.readonly
+const hidden = descriptor.hidden
+
 @readonly('version', 'buildDate')  
 class Package { }
 ```
 
 ### Common Decorator Patterns
 
-The functional approach makes it easy to create common decorator patterns:
+The flavored approach makes it easy to create common decorator patterns:
 
 ```typescript
-import { describe } from './std-decorators'
+import { descriptor } from './std-decorators'
 
-// Common reusable decorators
-export const readonly = describe({ writable: false })
-export const hidden = describe({ enumerable: false })
-export const locked = describe({ configurable: false })
-export const frozen = describe({ writable: false, configurable: false })
-export const private = describe({ enumerable: false, configurable: false })
+// Common reusable decorators using flavors
+export const readonly = descriptor.readonly
+export const hidden = descriptor.hidden
+export const locked = descriptor.frozen
+export const frozen = (() => descriptor.readonly.frozen)()
+export const private = (() => descriptor.hidden.frozen)()
 
 // Usage examples
 @readonly('id', 'createdAt')
@@ -389,7 +440,7 @@ The decorator merges the provided descriptor configuration with the existing pro
 
 ```typescript
 // Original property might have { enumerable: true, writable: true, configurable: true }
-// After @readonly('prop') where readonly = describe({ writable: false })
+// After @descriptor.readonly('prop')
 // Final descriptor: { enumerable: true, writable: false, configurable: true }
 ```
 
@@ -399,9 +450,9 @@ The property descriptor configuration is applied in the constructor after callin
 
 ## Best Practices
 
-1. **Create reusable configurations**: Define descriptor configurations once and reuse them
-2. **Use descriptive names**: Name your descriptor configurations clearly (`readonly`, `hidden`, `locked`)
-3. **Combine multiple decorators**: Stack multiple `describe` decorators for complex configurations
+1. **Use flavors directly**: Prefer `descriptor.readonly` over creating aliases for simple cases
+2. **Create reusable aliases**: For complex or frequently used combinations, create aliases
+3. **Combine multiple decorators**: Stack multiple flavored decorators for complex configurations
 4. **Use for encapsulation**: Hide internal properties from enumeration
 5. **Control immutability**: Make critical properties read-only
 6. **Prevent reconfiguration**: Lock important properties from being modified
@@ -551,6 +602,74 @@ deprecated.warn = (target, propertyKey, message?) => {
 4. **Document migration paths**: Provide clear upgrade instructions
 5. **Monitor usage**: Track which deprecated features are still being used
 
+## Debounce
+
+The `debounce` decorator delays the execution of a method until a specified amount of time has passed since the last time it was called. This is useful for handling rapid events like keystrokes or window resizing.
+
+## API Reference
+
+### `@debounce(delay: number)`
+
+A decorator that debounces a method.
+
+**Parameters:**
+- `delay`: The delay in milliseconds to wait before executing the method.
+
+**Returns:** A method decorator.
+
+## Usage Example
+
+```typescript
+import { debounce } from 'mutts/std-decorators'
+
+class SearchComponent {
+  @debounce(300)
+  onSearch(query: string) {
+    // This will only run after 300ms of inactivity
+    console.log(`Searching for: ${query}`)
+    this.performApiCall(query)
+  }
+
+  performApiCall(query: string) {
+    // ...
+  }
+}
+```
+
+## Throttle
+
+The `throttle` decorator limits the execution of a method to at most once every specified amount of time. This is useful for rate-limiting expensive operations like scroll handlers or animations.
+
+## API Reference
+
+### `@throttle(delay: number)`
+
+A decorator that throttles a method.
+
+**Parameters:**
+- `delay`: The time interval in milliseconds.
+
+**Returns:** A method decorator.
+
+## Usage Example
+
+```typescript
+import { throttle } from 'mutts/std-decorators'
+
+class ScrollHandler {
+  @throttle(100)
+  onScroll(event: Event) {
+    // This will run at most once every 100ms
+    console.log('Scroll event processed')
+    this.updateUI()
+  }
+
+  updateUI() {
+    // ...
+  }
+}
+```
+
 ## Related
 
 - [JavaScript Decorators](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Decorators)

package/docs/zone.md

@@ -21,20 +21,17 @@ console.log(myZone.active); // undefined
 
 ## Async Propagation
 
-By default, zones are lost when an async operation yields control (e.g., after `await`). To fix this, `mutts` provides `configureAsyncZone()`.
+By default, zones are lost when an async operation yields control (e.g., after `await`). To fix this, register zones in `asyncZone` — the global `ZoneAggregator` — which automatically preserves context across async boundaries via `asyncHooks`.
 
 ```typescript
-import { configureAsyncZone, asyncZone, Zone } from 'mutts/zone';
+import { asyncZone, Zone } from 'mutts/zone';
 
 const requestId = new Zone<string>();
 
 // 1. Tell the global aggregator to track this zone
 asyncZone.add(requestId);
 
-// 2. Patch global async primitives (once per app)
-configureAsyncZone();
-
-// 3. Usage
+// 2. Usage
 requestId.with("req-123", async () => {
     await somePromise();
     // Context is automatically preserved across await!
@@ -42,6 +39,12 @@ requestId.with("req-123", async () => {
 });
 ```
 
+> [!WARNING]
+> **Browser Limitations**: In browser environments (where `AsyncLocalStorage` is unavailable), `mutts` relies on monkey-patching global async primitives (Promise, setTimeout, etc.) to propagate zones. This is generally less robust than Node.js's `async_hooks` and may fail to track context across:
+> *   Native `async/await` boundaries in some modern browsers if not transpiled.
+> *   Concurrent modifications to global prototypes by other libraries.
+
+
 ## Core API
 
 ### `AZone<T>` (Abstract)

package/package.json

@@ -1,50 +1,61 @@
 {
   "name": "mutts",
   "description": "Modern UTility TS: A collection of TypeScript utilities",
-  "version": "1.0.7",
-  "main": "dist/browser.js",
+  "version": "1.0.9",
+  "main": "dist/browser.cjs",
   "module": "dist/browser.esm.js",
   "types": "dist/browser.d.ts",
   "exports": {
     ".": {
+      "test-node": {
+        "import": "./src/entry-node.ts"
+      },
+      "test-browser": {
+        "import": "./src/entry-browser.ts"
+      },
       "node": {
         "types": "./dist/node.d.ts",
         "import": "./dist/node.esm.js",
-        "require": "./dist/node.js"
+        "require": "./dist/node.cjs"
       },
       "default": {
         "types": "./dist/browser.d.ts",
         "import": "./dist/browser.esm.js",
-        "require": "./dist/browser.js"
+        "require": "./dist/browser.cjs"
       }
     },
     "./browser": {
       "types": "./dist/browser.d.ts",
       "import": "./dist/browser.esm.js",
-      "require": "./dist/browser.js"
+      "require": "./dist/browser.cjs"
     },
     "./node": {
       "types": "./dist/node.d.ts",
       "import": "./dist/node.esm.js",
-      "require": "./dist/node.js"
+      "require": "./dist/node.cjs"
     },
     "./src": {
       "node": {
-        "types": "./src/async/node.ts",
-        "import": "./src/async/node.ts"
+        "types": "./src/entry-node.ts",
+        "import": "./src/entry-node.ts"
       },
       "default": {
-        "types": "./src/async/browser.ts",
-        "import": "./src/async/browser.ts"
+        "types": "./src/entry-browser.ts",
+        "import": "./src/entry-browser.ts"
       }
     },
     "./src/browser": {
-      "types": "./src/async/browser.ts",
-      "import": "./src/async/browser.ts"
+      "types": "./src/entry-browser.ts",
+      "import": "./src/entry-browser.ts"
     },
     "./src/node": {
-      "types": "./src/async/node.ts",
-      "import": "./src/async/node.ts"
+      "types": "./src/entry-node.ts",
+      "import": "./src/entry-node.ts"
+    },
+    "./debug": {
+      "types": "./dist/debug.d.ts",
+      "import": "./dist/debug.esm.js",
+      "require": "./dist/debug.cjs"
     }
   },
   "files": [
@@ -59,14 +70,20 @@
     "build": "npm run build:js && npm run build:devtools",
     "build:watch": "rollup -c --watch",
     "prepublishOnly": "npm run build",
-    "test": "NODE_OPTIONS=--expose-gc jest",
-    "test:coverage": "NODE_OPTIONS=--expose-gc jest --coverage",
-    "test:coverage:watch": "NODE_OPTIONS=--expose-gc jest --coverage --watch",
-    "test:legacy": "TSCONFIG=tsconfig.legacy.json jest --detectOpenHandles --testPathPatterns=decorator",
-    "test:modern": "TSCONFIG=tsconfig.modern.json jest --detectOpenHandles --testPathPatterns=decorator",
-    "test:profile": "RUN_PROFILING=1 NODE_OPTIONS=--expose-gc jest --testPathPatterns=profiling",
-    "test:profile:benchmark": "RUN_PROFILING=1 NODE_OPTIONS=--expose-gc jest --testPathPatterns=profiling --testNamePattern=benchmark",
-    "test:profile:detailed": "RUN_PROFILING=1 node --prof node_modules/jest/bin/jest.js --testPathPatterns=profiling --no-coverage",
+    "test": "npm run test:node && npm run test:browser",
+    "test:node": "TEST_ENV=node NODE_OPTIONS='--expose-gc' vitest run",
+    "test:browser": "TEST_ENV=browser vitest run --browser",
+    "test:zone:node": "TEST_ENV=node vitest run tests/zone.test.ts",
+    "test:zone:browser": "TEST_ENV=browser vitest run tests/zone.test.ts",
+    "test:async:node": "TEST_ENV=node vitest run tests/async-hook.test.ts",
+    "test:async:browser": "TEST_ENV=browser vitest run tests/async-hook.test.ts",
+    "test:coverage": "TEST_ENV=node vitest run --coverage",
+    "test:coverage:watch": "TEST_ENV=node vitest run --coverage --watch",
+    "test:legacy": "TEST_ENV=node TSCONFIG=tsconfig.legacy.json vitest run --detectOpenHandles",
+    "test:modern": "TEST_ENV=node TSCONFIG=tsconfig.modern.json vitest run --detectOpenHandles",
+    "test:profile": "RUN_PROFILING=1 NODE_OPTIONS=--expose-gc vitest run",
+    "test:profile:benchmark": "RUN_PROFILING=1 NODE_OPTIONS=--expose-gc vitest run -t benchmark",
+    "test:profile:detailed": "RUN_PROFILING=1 node --prof node_modules/vitest/vitest.mjs --no-coverage",
     "benchmark:save": "tsx tests/profiling/benchmark.ts save",
     "benchmark:compare": "tsx tests/profiling/benchmark.ts compare",
     "benchmark:list": "tsx tests/profiling/benchmark.ts list",
@@ -102,25 +119,25 @@
   },
   "devDependencies": {
     "@biomejs/biome": "^2.0.6",
-    "@jest/globals": "^30.2.0",
     "@rollup/plugin-commonjs": "^28.0.6",
     "@rollup/plugin-json": "^6.1.0",
     "@rollup/plugin-node-resolve": "^16.0.1",
     "@rollup/plugin-terser": "^0.4.4",
     "@rollup/plugin-typescript": "^12.1.4",
-    "@types/jest": "^30.0.0",
     "@types/node": "^22.10.10",
-    "jest": "^30.0.4",
+    "@vitest/browser": "^4.0.18",
+    "@vitest/browser-playwright": "^4.0.18",
+    "playwright": "^1.58.1",
     "rollup": "^4.52.2",
     "rollup-plugin-copy": "^3.5.0",
     "rollup-plugin-dts": "^6.2.3",
     "rollup-plugin-typescript2": "^0.36.0",
-    "ts-jest": "^29.4.0",
     "ts-node": "^10.9.2",
     "tslib": "^2.8.1",
     "tsx": "^4.20.4",
     "typescript": "^5.8.3",
-    "vis-network": "^9.1.9"
+    "vis-network": "^9.1.9",
+    "vitest": "^4.0.18"
   },
   "packageManager": "pnpm@10.7.1+sha512.2d92c86b7928dc8284f53494fb4201f983da65f0fb4f0d40baafa5cf628fa31dae3e5968f12466f17df7e97310e30f343a648baea1b9b350685dafafffdf5808"
 }