promise-logic 1.3.2 → 2.4.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,290 +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)
-const results = await PromiseLogic.and([
-  fetch('/api/users'),
-  fetch('/api/posts'),
-  fetch('/api/comments')
-]);
+// CommonJS
+const { PromiseLogic } = require('promise-logic');
 
-// OR logic - Any promise succeeds (short-circuits on first success)
-const data = await PromiseLogic.or([
-  fetchPrimaryService(),
-  fetchBackupService()
-]);
-
-// XOR logic - Exactly one promise must succeed
-const uniqueResult = await PromiseLogic.xor([
-  cacheLookup(),
-  databaseQuery()
+// Use logic gates
+const results = await PromiseLogic.and([
+  Promise.resolve('data1'),
+  Promise.resolve('data2')
 ]);
+// results = ['data1', 'data2']
 ```
 
-### Advanced Logic Operations
+### TypeScript (Enhanced)
 
-```javascript
-// NAND logic - Not all promises succeed (at least one failure)
-const hasFailures = await PromiseLogic.nand([
-  validateInput(),
-  checkPermissions(),
-  verifyResources()
-]);
+```typescript
+// TypeScript version with full type inference
+import { PromiseLogic } from 'promise-logic/typescript';
 
-// NOR logic - All promises must fail
-const allFailed = await PromiseLogic.nor([
-  experimentalFeature(),
-  deprecatedAPI()
-]);
+// Type-safe operations with automatic inference
+const numbers = await PromiseLogic.and<number>([
+  Promise.resolve(1),
+  Promise.resolve(2)
+]); 
 
-// Majority logic - More than half succeed
-const consensus = await PromiseLogic.majority([
-  server1.query(),
-  server2.query(),
-  server3.query()
-]);
+const strings = await PromiseLogic.or<string>([
+  Promise.resolve('hello'),
+  Promise.resolve('world')
+]); 
 ```
 
-### Extended Result Analysis
+## Core Logic Gates
+
+### `and(promises)`
+Resolves with all values when all promises fulfill. Equivalent to `Promise.all()`.
 
 ```javascript
-// Get only successful results
-const successes = await PromiseLogic.allFulfilled([
-  apiCall1(),
-  apiCall2(),
-  apiCall3()
+const results = await PromiseLogic.and([
+  Promise.resolve(1),
+  Promise.resolve(2),
+  Promise.resolve(3)
 ]);
+// results = [1, 2, 3]
+```
 
-// Get only failure reasons
-const failures = await PromiseLogic.allRejected([
-  riskyOperation1(),
-  riskyOperation2()
-]);
+### `or(promises)`
+Resolves with the first fulfilled promise. Equivalent to `Promise.any()`.
 
+```javascript
+const result = await PromiseLogic.or([
+  Promise.reject('error'),
+  Promise.resolve('success')
+]);
+// result = 'success'
 ```
 
-## API Reference
+### `xor(promises)`
+Exclusive OR - resolves only when exactly one promise fulfills.
 
-### Core Logic Gates
+```javascript
+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
+}
+```
 
-#### `PromiseLogic.and(iterable)`
-Equivalent to `Promise.all`. Resolves when all promises fulfill, rejects if any promise rejects.
+### `nand(promises)`
+Not AND - resolves when not all promises fulfill.
 
-#### `PromiseLogic.or(iterable)`
-Resolves with the first successful promise. Rejects only if all promises reject.
+```javascript
+const results = await PromiseLogic.nand([
+  Promise.resolve('success'),
+  Promise.reject('error')
+]);
+// results = ['success']
+```
 
-#### `PromiseLogic.xor(iterable)`
-Resolves when exactly one promise fulfills. Rejects if zero or multiple promises fulfill.
+### `nor(promises)`
+Not OR - resolves only when all promises reject.
 
-#### `PromiseLogic.nand(iterable)`
-Resolves when not all promises fulfill (at least one rejection). Rejects if all promises fulfill.
+```javascript
+const results = await PromiseLogic.nor([
+  Promise.reject('error1'),
+  Promise.reject('error2')
+]);
+// results = []
+```
 
-#### `PromiseLogic.nor(iterable)`
-Resolves when all promises reject. Rejects if any promise fulfills.
+### `xnor(promises)`
+Exclusive NOR - resolves when all promises have the same outcome.
 
-#### `PromiseLogic.xnor(iterable)`
-Resolves when all promises fulfill or all reject. Rejects in mixed scenarios.
+```javascript
+const results = await PromiseLogic.xnor([
+  Promise.resolve('a'),
+  Promise.resolve('b')
+]);
+// results = ['a', 'b']
+```
 
-#### `PromiseLogic.majority(iterable)`
-Resolves when more than half of promises fulfill. Rejects otherwise.
+### `majority(promises)`
+Resolves when majority (>50%) of promises fulfill.
 
-### Extended Operations
+```javascript
+const results = await PromiseLogic.majority([
+  Promise.resolve('a'),
+  Promise.resolve('b'),
+  Promise.reject('error')
+]);
+// results = ['a', 'b']
+```
 
-#### `PromiseLogic.allFulfilled(iterable)`
-Always resolves with an array of fulfilled values (empty if none).
+## NOT Gate - New in v2.3.2
 
-#### `PromiseLogic.allRejected(iterable)`
-Always resolves with an array of rejection reasons (empty if none).
+### `not(promise)`
+Inverts promise resolution - successful promises become rejections, and vice versa.
 
-### Utility Methods
+```javascript
+// Success -> Failure
+try {
+  await PromiseLogic.not(Promise.resolve('success'));
+} catch (error) {
+  console.log(error); // 'success'
+}
 
-#### `PromiseLogic.race(iterable)`
-Equivalent to `Promise.race`. Resolves or rejects with the first settled promise.
+// Failure -> Success
+const result = await PromiseLogic.not(Promise.reject('error'));
+console.log(result); // 'error'
+```
 
-#### `PromiseLogic.allSettled(iterable)`
-Equivalent to `Promise.allSettled`. Always resolves with settlement results.
+**Use Cases:**
+- Transform error handling patterns
+- Create conditional promise flows
+- Implement retry logic with inverted conditions
+- Build fallback mechanisms
 
-#### `PromiseLogic.createFlipFlop(initialState?)`
-Creates a stateful flip-flop utility for managing boolean state transitions.
+## Advanced Utilities
 
-## Factory Function
+### `race(promises)`
+Equivalent to `Promise.race()`.
 
-Create customized instances with method name transformations:
+### `allSettled(promises)`
+Equivalent to `Promise.allSettled()`.
 
-```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]);
-```
+### `allFulfilled(promises)`
+Resolves with all fulfilled values, ignoring rejections.
 
-## Real-World Examples
+### `allRejected(promises)`
+Resolves with all rejection reasons, ignoring fulfillments.
 
-### Service Orchestration
+### `createFlipFlop(initialState?)`
+Creates a stateful flip-flop for managing boolean state across async operations.
 
 ```javascript
-// Load balancing with fallback
-const userData = await PromiseLogic.or([
-  primaryUserService.getUser(id),
-  secondaryUserService.getUser(id),
-  cacheService.getUser(id)
-]);
+const flipFlop = PromiseLogic.createFlipFlop(false);
 
-// Multi-step validation
-const isValid = await PromiseLogic.and([
-  validateEmail(email),
-  validatePassword(password),
-  checkRateLimit(ipAddress)
-]);
+// Get current state
+console.log(flipFlop.getState()); // false
 
-// Consensus-based decision making
-const configuration = await PromiseLogic.majority([
-  configServer1.getConfig(),
-  configServer2.getConfig(),
-  configServer3.getConfig()
-]);
-```
+// Toggle state
+await flipFlop.toggle();
+console.log(flipFlop.getState()); // true
 
-### Error Recovery & Analysis
+// Wait for specific state
+await flipFlop.waitFor(true); // Resolves immediately if already true
 
-```javascript
-// Graceful degradation
-const [successfulResults, failedOperations] = await Promise.all([
-  PromiseLogic.allFulfilled(operations),
-  PromiseLogic.allRejected(operations)
-]);
+// Async state change
+setTimeout(() => flipFlop.set(false), 100);
+await flipFlop.waitForChange(); // Waits for state change
 ```
 
-### State Management
+## TypeScript Support - Enhanced in v2.3.2
 
-```javascript
-// Flip-flop for toggle operations
-const toggle = PromiseLogic.createFlipFlop(false);
+The TypeScript version (`promise-logic/typescript`) provides:
 
-// Toggle state and wait for change
-await toggle.toggle();
-console.log(toggle.getState()); // true
+- **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
 
-// Set specific state
-await toggle.setState(false);
-```
-
-## Error Handling
+```typescript
+import { PromiseLogic } from 'promise-logic/typescript';
 
-All logic gates throw `PromiseLogicError` with descriptive messages:
+// 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 }>
 
-```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);
+// Complex generic types work seamlessly
+async function processPromises<T>(promises: Promise<T>[]): Promise<T[]> {
+  return await PromiseLogic.and(promises);
 }
 ```
 
-## TypeScript Support
+## Entry Points
 
-Full TypeScript support with precise type inference:
+| 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 |
 
-```typescript
-import { PromiseLogic } from 'promise-logic';
+## Migration Note
 
-// Type inference for successful results
-const numbers: number[] = await PromiseLogic.and([
-  Promise.resolve(1),
-  Promise.resolve(2),
-  Promise.resolve(3)
-]);
-
-// Type-safe error handling
-try {
-  await PromiseLogic.nand(operations);
-} catch (error: PromiseLogicError) {
-  // error has full type information
-}
-```
+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.
 
-## Advanced Usage
+## Development
 
-### Custom Logic Composition
+```bash
+# Install dependencies
+npm install
 
-```javascript
-// Create complex logic flows
-async function advancedOperation(promises) {
-  const [successes, failures] = await Promise.all([
-    PromiseLogic.allFulfilled(promises),
-    PromiseLogic.allRejected(promises)
-  ]);
+# Build the project
+npm run build
 
-  if (successes.length >= failures.length) {
-    return { data: successes, warnings: failures };
-  } else {
-    throw new Error('Operation mostly failed');
-  }
-}
-```
+# Run tests
+npm test
 
-### Performance Optimization
+# Run tests in watch mode
+npm run test:watch
 
-```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();
+# Check code coverage
+npm run test:coverage
 ```
 
 ## Contributing
 
-We welcome contributions! Please see our Contributing Guide for details.
+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
 
-MIT License - see LICENSE for details.
-
-## Links
-
-- 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
-
----
-
-**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
   };
   
   // 应用命名转换
@@ -222,4 +236,3 @@ function createPromiseLogic(options = {}) {
 }
 
 exports.createPromiseLogic = createPromiseLogic;
-//# sourceMappingURL=factory.cjs.js.map

package/dist/factory.esm.js

@@ -12,6 +12,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).`,
@@ -30,6 +31,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);
   }
@@ -119,6 +129,7 @@ class PromiseLogic {
     });
   }
 
+
   // 返回所有成功的Promise结果
   static allFulfilled(iterable) {
     return Promise.allSettled(iterable).then((results) => {
@@ -201,10 +212,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
   };
   
   // 应用命名转换
@@ -220,4 +234,3 @@ function createPromiseLogic(options = {}) {
 }
 
 export { createPromiseLogic };
-//# sourceMappingURL=factory.esm.js.map

package/dist/index.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
   };
   
   // 应用命名转换
@@ -225,4 +239,3 @@ exports.PromiseLogic = PromiseLogic;
 exports.PromiseLogicError = PromiseLogicError;
 exports.createLogicError = createLogicError;
 exports.createPromiseLogic = createPromiseLogic;
-//# sourceMappingURL=index.cjs.js.map