promise-logic 1.3.1 → 2.3.3

package/README.md

@@ -1,21 +1,48 @@
-# PromiseLogic
 
-> Compose promises with logic gate semantics - Forget APIs, remember logic.
+# Promise Logic - Advanced Promise Logic Gates for Async Programming
 
-PromiseLogic is a comprehensive utility library that provides intuitive logical gate semantics for Promise composition. It extends the standard Promise API with logical operations that mirror digital circuit design, making asynchronous programming more intuitive and expressive.
+Compose promises with logic gate semantics (AND, OR, NOT, XOR, NAND, NOR, XNOR, Majority). Forget APIs, remember logic.
 
-## Philosophy
+## Features
 
-**"Forget APIs, remember logic."** - Replace fragmented API knowledge with fundamental logic concepts that work consistently across all asynchronous operations.
+- **Logic Gate Semantics**: Extend Promise API with AND, OR, NOT, XOR, NAND, NOR, XNOR, Majority operations
+- **Dual Entry Points**: Choose between JavaScript or enhanced TypeScript experience
+- **Type Safety**: Complete TypeScript definitions with strict type checking
+- **Promise Utilities**: Additional utilities like Flip-Flop state management
+- **Zero Dependencies**: Pure JavaScript/TypeScript implementation
+- **Tree Shakeable**: Optimized for modern bundlers
 
-## Features
+## Recent Updates
+
+### Version 2.3.2 Highlights
+
+**🚀 NOT Gate Implementation**  
+Introduced the NOT logic gate for promise inversion, enabling flexible negation patterns in asynchronous workflows:
+
+```javascript
+// Success -> Failure transformation
+await PromiseLogic.not(Promise.resolve('success')); // Rejects with 'success'
 
-- **Complete Logic Gate Semantics**: AND, OR, XOR, NAND, NOR, XNOR, Majority
-- **Extended Promise Operations**: All fulfilled/rejected results, complete settlement analysis
-- **Dual API Pattern**: Static class methods + Configurable factory function
-- **Production Ready**: Zero dependencies, complete TypeScript support
-- **Test Driven**: 100% test coverage with comprehensive edge cases
-- **Tree Shaking**: Optimized bundle output for modern build systems
+// Failure -> Success transformation  
+const result = await PromiseLogic.not(Promise.reject('error')); // Resolves with 'error'
+```
+
+**📦 Enhanced TypeScript System**  
+Completely revamped TypeScript architecture with:
+- Full generic type propagation
+- Strict type checking with zero `any` types  
+- Advanced type inference for all operations
+- Seamless IDE integration with IntelliSense
+
+**⚡ Performance Optimizations**
+- Optimized internal logic for better efficiency
+- Reduced memory overhead in gate operations
+- Improved error handling and edge case management
+
+**📚 Documentation Enhancements**
+- Comprehensive API reference with TypeScript examples
+- Better usage guidelines and best practices
+- Clear entry point documentation for different environments
 
 ## Installation
 
@@ -25,324 +52,249 @@ npm install promise-logic
 
 ## Quick Start
 
-### Basic Logic Gates
+### JavaScript (Default)
 
 ```javascript
+// ES Modules
 import { PromiseLogic } from 'promise-logic';
 
-// AND logic - All promises must succeed (equivalent to Promise.all)
+// CommonJS
+const { PromiseLogic } = require('promise-logic');
+
+// Use logic gates
 const results = await PromiseLogic.and([
-  fetch('/api/users'),
-  fetch('/api/posts'),
-  fetch('/api/comments')
+  Promise.resolve('data1'),
+  Promise.resolve('data2')
 ]);
+// results = ['data1', 'data2']
+```
 
-// OR logic - Any promise succeeds (short-circuits on first success)
-const data = await PromiseLogic.or([
-  fetchPrimaryService(),
-  fetchBackupService()
-]);
+### TypeScript (Enhanced)
 
-// XOR logic - Exactly one promise must succeed
-const uniqueResult = await PromiseLogic.xor([
-  cacheLookup(),
-  databaseQuery()
-]);
+```typescript
+// TypeScript version with full type inference
+import { PromiseLogic } from 'promise-logic/typescript';
+
+// Type-safe operations with automatic inference
+const numbers = await PromiseLogic.and<number>([
+  Promise.resolve(1),
+  Promise.resolve(2)
+]); 
+
+const strings = await PromiseLogic.or<string>([
+  Promise.resolve('hello'),
+  Promise.resolve('world')
+]); 
 ```
 
-### Advanced Logic Operations
+## Core Logic Gates
+
+### `and(promises)`
+Resolves with all values when all promises fulfill. Equivalent to `Promise.all()`.
 
 ```javascript
-// NAND logic - Not all promises succeed (at least one failure)
-const hasFailures = await PromiseLogic.nand([
-  validateInput(),
-  checkPermissions(),
-  verifyResources()
+const results = await PromiseLogic.and([
+  Promise.resolve(1),
+  Promise.resolve(2),
+  Promise.resolve(3)
 ]);
+// results = [1, 2, 3]
+```
 
-// NOR logic - All promises must fail
-const allFailed = await PromiseLogic.nor([
-  experimentalFeature(),
-  deprecatedAPI()
-]);
+### `or(promises)`
+Resolves with the first fulfilled promise. Equivalent to `Promise.any()`.
 
-// Majority logic - More than half succeed
-const consensus = await PromiseLogic.majority([
-  server1.query(),
-  server2.query(),
-  server3.query()
+```javascript
+const result = await PromiseLogic.or([
+  Promise.reject('error'),
+  Promise.resolve('success')
 ]);
+// result = 'success'
 ```
 
-### Extended Result Analysis
+### `xor(promises)`
+Exclusive OR - resolves only when exactly one promise fulfills.
 
 ```javascript
-// Get only successful results
-const successes = await PromiseLogic.allFulfilled([
-  apiCall1(),
-  apiCall2(),
-  apiCall3()
-]);
+try {
+  const result = await PromiseLogic.xor([
+    Promise.reject('error1'),
+    Promise.resolve('success'),
+    Promise.reject('error2')
+  ]);
+  // result = 'success'
+} catch (error) {
+  // Throws if zero or multiple promises fulfill
+}
+```
 
-// Get only failure reasons
-const failures = await PromiseLogic.allRejected([
-  riskyOperation1(),
-  riskyOperation2()
-]);
+### `nand(promises)`
+Not AND - resolves when not all promises fulfill.
 
-// Get complete settlement information
-const allResults = await PromiseLogic.allResults([
-  operation1(),
-  operation2()
+```javascript
+const results = await PromiseLogic.nand([
+  Promise.resolve('success'),
+  Promise.reject('error')
 ]);
+// results = ['success']
+```
 
-// Strict all-success validation
-const allSuccessful = await PromiseLogic.allSuccessful([
-  validation1(),
-  validation2(),
-  validation3()
-]);
+### `nor(promises)`
+Not OR - resolves only when all promises reject.
 
-// Strict all-failure validation
-const allFailed = await PromiseLogic.allFailed([
-  deprecatedCall1(),
-  deprecatedCall2()
+```javascript
+const results = await PromiseLogic.nor([
+  Promise.reject('error1'),
+  Promise.reject('error2')
 ]);
+// results = []
 ```
 
-## API Reference
-
-### Core Logic Gates
-
-#### `PromiseLogic.and(iterable)`
-Equivalent to `Promise.all`. Resolves when all promises fulfill, rejects if any promise rejects.
-
-#### `PromiseLogic.or(iterable)`
-Resolves with the first successful promise. Rejects only if all promises reject.
-
-#### `PromiseLogic.xor(iterable)`
-Resolves when exactly one promise fulfills. Rejects if zero or multiple promises fulfill.
-
-#### `PromiseLogic.nand(iterable)`
-Resolves when not all promises fulfill (at least one rejection). Rejects if all promises fulfill.
-
-#### `PromiseLogic.nor(iterable)`
-Resolves when all promises reject. Rejects if any promise fulfills.
-
-#### `PromiseLogic.xnor(iterable)`
-Resolves when all promises fulfill or all reject. Rejects in mixed scenarios.
-
-#### `PromiseLogic.majority(iterable)`
-Resolves when more than half of promises fulfill. Rejects otherwise.
-
-### Extended Operations
-
-#### `PromiseLogic.allFulfilled(iterable)`
-Always resolves with an array of fulfilled values (empty if none).
-
-#### `PromiseLogic.allRejected(iterable)`
-Always resolves with an array of rejection reasons (empty if none).
+### `xnor(promises)`
+Exclusive NOR - resolves when all promises have the same outcome.
 
-#### `PromiseLogic.allResults(iterable)`
-Equivalent to `Promise.allSettled`. Returns complete settlement information.
-
-#### `PromiseLogic.allSuccessful(iterable)`
-Resolves with all values only if every promise fulfills. Rejects otherwise.
-
-#### `PromiseLogic.allFailed(iterable)`
-Resolves with all rejection reasons only if every promise rejects. Rejects otherwise.
-
-### Utility Methods
-
-#### `PromiseLogic.race(iterable)`
-Equivalent to `Promise.race`. Resolves or rejects with the first settled promise.
-
-#### `PromiseLogic.allSettled(iterable)`
-Equivalent to `Promise.allSettled`. Always resolves with settlement results.
-
-#### `PromiseLogic.createFlipFlop(initialState?)`
-Creates a stateful flip-flop utility for managing boolean state transitions.
-
-## Factory Function
+```javascript
+const results = await PromiseLogic.xnor([
+  Promise.resolve('a'),
+  Promise.resolve('b')
+]);
+// results = ['a', 'b']
+```
 
-Create customized instances with method name transformations:
+### `majority(promises)`
+Resolves when majority (>50%) of promises fulfill.
 
 ```javascript
-import { createPromiseLogic } from 'promise-logic';
-
-// Default naming
-const logic = createPromiseLogic();
-await logic.and([promise1, promise2]);
-
-// With prefix
-const asyncLogic = createPromiseLogic({ prefix: 'async' });
-await asyncLogic.asyncand([promise1, promise2]);
-
-// With suffix
-const logicUtils = createPromiseLogic({ suffix: 'Logic' });
-await logicUtils.andLogic([promise1, promise2]);
-
-// With custom renaming
-const customLogic = createPromiseLogic({
-  rename: {
-    and: 'conjunction',
-    or: 'disjunction',
-    xor: 'exclusiveOr'
-  }
-});
-await customLogic.conjunction([promise1, promise2]);
-
-// Combined transformations
-const advancedLogic = createPromiseLogic({
-  prefix: 'async',
-  suffix: 'Logic',
-  rename: { and: 'conjunction' }
-});
-await advancedLogic.asyncconjunctionLogic([promise1, promise2]);
+const results = await PromiseLogic.majority([
+  Promise.resolve('a'),
+  Promise.resolve('b'),
+  Promise.reject('error')
+]);
+// results = ['a', 'b']
 ```
 
-## Real-World Examples
+## NOT Gate - New in v2.3.2
 
-### Service Orchestration
+### `not(promise)`
+Inverts promise resolution - successful promises become rejections, and vice versa.
 
 ```javascript
-// Load balancing with fallback
-const userData = await PromiseLogic.or([
-  primaryUserService.getUser(id),
-  secondaryUserService.getUser(id),
-  cacheService.getUser(id)
-]);
-
-// Multi-step validation
-const isValid = await PromiseLogic.and([
-  validateEmail(email),
-  validatePassword(password),
-  checkRateLimit(ipAddress)
-]);
+// Success -> Failure
+try {
+  await PromiseLogic.not(Promise.resolve('success'));
+} catch (error) {
+  console.log(error); // 'success'
+}
 
-// Consensus-based decision making
-const configuration = await PromiseLogic.majority([
-  configServer1.getConfig(),
-  configServer2.getConfig(),
-  configServer3.getConfig()
-]);
+// Failure -> Success
+const result = await PromiseLogic.not(Promise.reject('error'));
+console.log(result); // 'error'
 ```
 
-### Error Recovery & Analysis
+**Use Cases:**
+- Transform error handling patterns
+- Create conditional promise flows
+- Implement retry logic with inverted conditions
+- Build fallback mechanisms
 
-```javascript
-// Graceful degradation
-const [successfulResults, failedOperations] = await Promise.all([
-  PromiseLogic.allFulfilled(operations),
-  PromiseLogic.allRejected(operations)
-]);
+## Advanced Utilities
 
-// Comprehensive error reporting
-const results = await PromiseLogic.allResults(operations);
-const successful = results.filter(r => r.status === 'fulfilled');
-const failed = results.filter(r => r.status === 'rejected');
+### `race(promises)`
+Equivalent to `Promise.race()`.
 
-console.log(`Operations: ${successful.length} successful, ${failed.length} failed`);
-```
+### `allSettled(promises)`
+Equivalent to `Promise.allSettled()`.
 
-### State Management
+### `allFulfilled(promises)`
+Resolves with all fulfilled values, ignoring rejections.
 
-```javascript
-// Flip-flop for toggle operations
-const toggle = PromiseLogic.createFlipFlop(false);
+### `allRejected(promises)`
+Resolves with all rejection reasons, ignoring fulfillments.
 
-// Toggle state and wait for change
-await toggle.toggle();
-console.log(toggle.getState()); // true
+### `createFlipFlop(initialState?)`
+Creates a stateful flip-flop for managing boolean state across async operations.
 
-// Set specific state
-await toggle.setState(false);
-```
+```javascript
+const flipFlop = PromiseLogic.createFlipFlop(false);
 
-## Error Handling
+// Get current state
+console.log(flipFlop.getState()); // false
 
-All logic gates throw `PromiseLogicError` with descriptive messages:
+// Toggle state
+await flipFlop.toggle();
+console.log(flipFlop.getState()); // true
 
-```javascript
-try {
-  await PromiseLogic.xor([apiCall1(), apiCall2()]);
-} catch (error) {
-  if (error.type === 'XOR_ERROR') {
-    console.log('Expected exactly one successful call');
-  }
-  console.log('Failed promises:', error.results);
-}
+// Wait for specific state
+await flipFlop.waitFor(true); // Resolves immediately if already true
+
+// Async state change
+setTimeout(() => flipFlop.set(false), 100);
+await flipFlop.waitForChange(); // Waits for state change
 ```
 
-## TypeScript Support
+## TypeScript Support - Enhanced in v2.3.2
+
+The TypeScript version (`promise-logic/typescript`) provides:
 
-Full TypeScript support with precise type inference:
+- **Full Type Inference**: Automatic type deduction for all operations
+- **Strict Type Checking**: Zero `any` types, complete type safety
+- **IDE Support**: Enhanced IntelliSense and code completion
+- **Generic Type Propagation**: Proper handling of complex generic scenarios
 
 ```typescript
-import { PromiseLogic } from 'promise-logic';
+import { PromiseLogic } from 'promise-logic/typescript';
 
-// Type inference for successful results
-const numbers: number[] = await PromiseLogic.and([
-  Promise.resolve(1),
-  Promise.resolve(2),
-  Promise.resolve(3)
+// TypeScript infers everything
+const result = await PromiseLogic.and([
+  Promise.resolve({ id: 1, name: 'Alice' }),
+  Promise.resolve({ id: 2, name: 'Bob' })
 ]);
+// result type: Array<{ id: number, name: string }>
 
-// Type-safe error handling
-try {
-  await PromiseLogic.nand(operations);
-} catch (error: PromiseLogicError) {
-  // error has full type information
+// Complex generic types work seamlessly
+async function processPromises<T>(promises: Promise<T>[]): Promise<T[]> {
+  return await PromiseLogic.and(promises);
 }
 ```
 
-## Advanced Usage
+## Entry Points
 
-### Custom Logic Composition
+| Import Path | Purpose | Recommended For |
+|------------|---------|----------------|
+| `promise-logic` | Default JavaScript version | General use, mixed codebases |
+| `promise-logic/typescript` | Enhanced TypeScript version | TypeScript projects, strict type safety |
 
-```javascript
-// Create complex logic flows
-async function advancedOperation(promises) {
-  const [successes, failures] = await Promise.all([
-    PromiseLogic.allFulfilled(promises),
-    PromiseLogic.allRejected(promises)
-  ]);
+## Migration Note
 
-  if (successes.length >= failures.length) {
-    return { data: successes, warnings: failures };
-  } else {
-    throw new Error('Operation mostly failed');
-  }
-}
-```
+If you're upgrading from earlier versions, note that the TypeScript system has been completely redesigned for better type safety and developer experience. All existing APIs remain compatible.
 
-### Performance Optimization
+## Development
 
-```javascript
-// Batch processing with logic gates
-const batches = chunkArray(operations, BATCH_SIZE);
-const batchResults = await PromiseLogic.allFulfilled(
-  batches.map(batch => PromiseLogic.and(batch))
-);
-
-// Flatten results
-const allResults = batchResults.flat();
-```
+```bash
+# Install dependencies
+npm install
 
-## Contributing
+# Build the project
+npm run build
 
-We welcome contributions! Please see our Contributing Guide for details.
+# Run tests
+npm test
 
-## License
+# Run tests in watch mode
+npm run test:watch
 
-MIT License - see LICENSE for details.
+# Check code coverage
+npm run test:coverage
+```
 
-## Links
+## Contributing
 
-- GitHub Repository: https://github.com/xier123456/promise-logic
-- npm Package: https://www.npmjs.com/package/promise-logic
-- Issue Tracker: https://github.com/xier123456/promise-logic/issues
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Add tests for new functionality
+5. Submit a pull request
 
----
+## License
 
-**PromiseLogic** - Making asynchronous logic as simple as digital circuits.
+MIT © 2026

package/dist/factory.cjs.js

@@ -14,6 +14,7 @@ function createLogicError(type, fulfilledCount, total, results) {
   const messages = {
     XOR_ERROR: `XOR condition failed: expected exactly 1 promise to fulfill, but ${fulfilledCount} fulfilled.`,
     NAND_ERROR: `NAND condition failed: all ${total} promises fulfilled (expected at least one rejection).`,
+    NOT_ERROR: `NOT condition failed: promise resolved (expected rejection).`,
     NOR_ERROR: `NOR condition failed: ${fulfilledCount} promises fulfilled (expected all rejected).`,
     MAJORITY_ERROR: `Majority condition failed: ${fulfilledCount}/${total} fulfilled (need majority).`,
     ALL_SUCCESSFUL_ERROR: `All successful condition failed: ${fulfilledCount}/${total} promises fulfilled (expected all to succeed).`,
@@ -32,6 +33,15 @@ class PromiseLogic {
     return Promise.any(iterable);
   }
 
+  
+static  not(promise) {
+  return Promise.resolve(promise).then(
+    (value) => Promise.reject(value),
+    (reason) => Promise.resolve(reason)
+  )
+  .catch((error) => Promise.resolve(error));
+}
+
   static race(iterable) {
     return Promise.race(iterable);
   }
@@ -121,6 +131,7 @@ class PromiseLogic {
     });
   }
 
+
   // 返回所有成功的Promise结果
   static allFulfilled(iterable) {
     return Promise.allSettled(iterable).then((results) => {
@@ -203,10 +214,13 @@ function createPromiseLogic(options = {}) {
     race: PromiseLogic.race,
     allSettled: PromiseLogic.allSettled,
     xor: PromiseLogic.xor,
+    not: PromiseLogic.not,
     nand: PromiseLogic.nand,
     nor: PromiseLogic.nor,
     xnor: PromiseLogic.xnor,
-    majority: PromiseLogic.majority
+    majority: PromiseLogic.majority,
+    allFulfilled: PromiseLogic.allFulfilled,
+    allRejected: PromiseLogic.allRejected
   };
   
   // 应用命名转换