dspx 0.2.0-alpha.1 → 0.2.0-alpha.11

package/LICENSE

@@ -1,21 +1,224 @@
-MIT License
-
-Copyright (c) 2025 Alan Kochukalam George
-
-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.
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1.  Definitions.
+
+    "License" shall mean the terms and conditions for use, reproduction,
+    and distribution as defined by Sections 1 through 9 of this document.
+
+    "Licensor" shall mean the copyright owner or entity authorized by
+    the copyright owner that is granting the License.
+
+    "Legal Entity" shall mean the union of the acting entity and all
+    other entities that control, are controlled by, or are under common
+    control with that entity. For the purposes of this definition,
+    "control" means (i) the power, direct or indirect, to cause the
+    direction or management of such entity, whether by contract or
+    otherwise, or (ii) ownership of fifty percent (50%) or more of the
+    outstanding shares, or (iii) beneficial ownership of such entity.
+
+    "You" (or "Your") shall mean an individual or Legal Entity
+    exercising permissions granted by this License.
+
+    "Source" form shall mean the preferred form for making modifications,
+    including but not limited to software source code, documentation
+    source, and configuration files.
+
+    "Object" form shall mean any form resulting from mechanical
+    transformation or translation of a Source form, including but
+    not limited to compiled object code, generated documentation,
+    and conversions to other media types.
+
+    "Work" shall mean the work of authorship, whether in Source or
+    Object form, made available under the License, as indicated by a
+    copyright notice that is included in or attached to the work
+    (an example is provided in the Appendix below).
+
+    "Derivative Works" shall mean any work, whether in Source or Object
+    form, that is based on (or derived from) the Work and for which the
+    editorial revisions, annotations, elaborations, or other modifications
+    represent, as a whole, an original work of authorship. For the purposes
+    of this License, Derivative Works shall not include works that remain
+    separable from, or merely link (or bind by name) to the interfaces of,
+    the Work and Derivative Works thereof.
+
+    "Contribution" shall mean any work of authorship, including
+    the original version of the Work and any modifications or additions
+    to that Work or Derivative Works thereof, that is intentionally
+    submitted to Licensor for inclusion in the Work by the copyright owner
+    or by an individual or Legal Entity authorized to submit on behalf of
+    the copyright owner. For the purposes of this definition, "submitted"
+    means any form of electronic, verbal, or written communication sent
+    to the Licensor or its representatives, including but not limited to
+    communication on electronic mailing lists, source code control systems,
+    and issue tracking systems that are managed by, or on behalf of, the
+    Licensor for the purpose of discussing and improving the Work, but
+    excluding communication that is conspicuously marked or otherwise
+    designated in writing by the copyright owner as "Not a Contribution."
+
+    "Contributor" shall mean Licensor and any individual or Legal Entity
+    on behalf of whom a Contribution has been received by Licensor and
+    subsequently incorporated within the Work.
+
+2.  Grant of Copyright License. Subject to the terms and conditions of
+    this License, each Contributor hereby grants to You a perpetual,
+    worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+    copyright license to reproduce, prepare Derivative Works of,
+    publicly display, publicly perform, sublicense, and distribute the
+    Work and such Derivative Works in Source or Object form.
+
+3.  Grant of Patent License. Subject to the terms and conditions of
+    this License, each Contributor hereby grants to You a perpetual,
+    worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+    (except as stated in this section) patent license to make, have made,
+    use, offer to sell, sell, import, and otherwise transfer the Work,
+    where such license applies only to those patent claims licensable
+    by such Contributor that are necessarily infringed by their
+    Contribution(s) alone or by combination of their Contribution(s)
+    with the Work to which such Contribution(s) was submitted. If You
+    institute patent litigation against any entity (including a
+    cross-claim or counterclaim in a lawsuit) alleging that the Work
+    or a Contribution incorporated within the Work constitutes direct
+    or contributory patent infringement, then any patent licenses
+    granted to You under this License for that Work shall terminate
+    as of the date such litigation is filed.
+
+4.  Redistribution. You may reproduce and distribute copies of the
+    Work or Derivative Works thereof in any medium, with or without
+    modifications, and in Source or Object form, provided that You
+    meet the following conditions:
+
+    (a) You must give any other recipients of the Work or
+    Derivative Works a copy of this License; and
+
+    (b) You must cause any modified files to carry prominent notices
+    stating that You changed the files; and
+
+    (c) You must retain, in the Source form of any Derivative Works
+    that You distribute, all copyright, patent, trademark, and
+    attribution notices from the Source form of the Work,
+    excluding those notices that do not pertain to any part of
+    the Derivative Works; and
+
+    (d) If the Work includes a "NOTICE" text file as part of its
+    distribution, then any Derivative Works that You distribute must
+    include a readable copy of the attribution notices contained
+    within such NOTICE file, excluding those notices that do not
+    pertain to any part of the Derivative Works, in at least one
+    of the following places: within a NOTICE text file distributed
+    as part of the Derivative Works; within the Source form or
+    documentation, if provided along with the Derivative Works; or,
+    within a display generated by the Derivative Works, if and
+    wherever such third-party notices normally appear. The contents
+    of the NOTICE file are for informational purposes only and
+    do not modify the License. You may add Your own attribution
+    notices within Derivative Works that You distribute, alongside
+    or as an addendum to the NOTICE text from the Work, provided
+    that such additional attribution notices cannot be construed
+    as modifying the License.
+
+    You may add Your own copyright statement to Your modifications and
+    may provide additional or different license terms and conditions
+    for use, reproduction, or distribution of Your modifications, or
+    for any such Derivative Works as a whole, provided Your use,
+    reproduction, and distribution of the Work otherwise complies with
+    the conditions stated in this License.
+
+5.  Submission of Contributions. Unless You explicitly state otherwise,
+    any Contribution intentionally submitted for inclusion in the Work
+    by You to the Licensor shall be under the terms and conditions of
+    this License, without any additional terms or conditions.
+    Notwithstanding the above, nothing herein shall supersede or modify
+    the terms of any separate license agreement you may have executed
+    with Licensor regarding such Contributions.
+
+6.  Trademarks. This License does not grant permission to use the trade
+    names, trademarks, service marks, or product names of the Licensor,
+    except as required for reasonable and customary use in describing the
+    origin of the Work and reproducing the content of the NOTICE file.
+
+7.  Disclaimer of Warranty. Unless required by applicable law or
+    agreed to in writing, Licensor provides the Work (and each
+    Contributor provides its Contributions) on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+    implied, including, without limitation, any warranties or conditions
+    of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+    PARTICULAR PURPOSE. You are solely responsible for determining the
+    appropriateness of using or redistributing the Work and assume any
+    risks associated with Your exercise of permissions under this License.
+
+8.  Limitation of Liability. In no event and under no legal theory,
+    whether in tort (including negligence), contract, or otherwise,
+    unless required by applicable law (such as deliberate and grossly
+    negligent acts) or agreed to in writing, shall any Contributor be
+    liable to You for damages, including any direct, indirect, special,
+    incidental, or consequential damages of any character arising as a
+    result of this License or out of the use or inability to use the
+    Work (including but not limited to damages for loss of goodwill,
+    work stoppage, computer failure or malfunction, or any and all
+    other commercial damages or losses), even if such Contributor
+    has been advised of the possibility of such damages.
+
+9.  Accepting Warranty or Additional Liability. While redistributing
+    the Work or Derivative Works thereof, You may choose to offer,
+    and charge a fee for, acceptance of support, warranty, indemnity,
+    or other liability obligations and/or rights consistent with this
+    License. However, in accepting such obligations, You may act only
+    on Your own behalf and on Your sole responsibility, not on behalf
+    of any other Contributor, and only if You agree to indemnify,
+    defend, and hold each Contributor harmless for any liability
+    incurred by, or claims asserted against, such Contributor by reason
+    of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+Copyright 2025 Alan Kochukalam George
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
+---
+
+This product includes code derived from the following open-source project:
+
+FFTPACK (Apache License 2.0)
+Copyright (c) 2004–2016 University Corporation for Atmospheric Research/NCAR
+Developed by Paul N. Swarztrauber
+https://www.netlib.org/fftpack/
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
+---

package/README.md

@@ -1,7 +1,6 @@
 # Work in Progress
 
 > The project’s in heavy development.  
-> Once Phases 1 and 2 (core DSP + FFT/IIR/FIR) are stable, I’ll push the first npm release.  
 > Expect breaking changes until then!
 
 # dspx
@@ -18,6 +17,7 @@ A modern DSP library built for Node.js backends processing real-time biosignals,
 - 🎯 **SIMD Acceleration** – AVX2/SSE2/NEON optimizations provide 2-8x speedup on batch operations and rectification
 - 🔧 **TypeScript-First** – Full type safety with excellent IntelliSense
 - 📡 **Redis State Persistence** – Fully implemented state serialization/deserialization including circular buffer contents and running sums
+- 🔥 **Kafka Streaming (Experimental)** – Real-time data ingestion and log streaming via Apache Kafka (testing in progress)
 - ⏱️ **Time-Series Processing** – NEW! Support for irregular timestamps and time-based windows
 - 🔗 **Fluent Pipeline API** – Chain filter operations with method chaining
 - 🎯 **Zero-Copy Processing** – Direct TypedArray manipulation for minimal overhead
@@ -453,6 +453,39 @@ await pipeline.process(chunk2, { sampleRate: 2000, channels: 1 });
 pipeline.clearState();
 ```
 
+### With Kafka Streaming (Experimental)
+
+> ⚠️ **Note:** Kafka integration is experimental and requires additional testing. See the [Contributing](#-contributing) section if you'd like to help!
+
+```typescript
+import { createDspPipeline, createKafkaConsumer } from "dspx";
+
+// Create DSP pipeline
+const pipeline = createDspPipeline();
+pipeline
+  .MovingAverage({ mode: "moving", windowSize: 10 })
+  .Rms({ mode: "moving", windowSize: 5 });
+
+// Consume sensor data from Kafka topic
+const consumer = await createKafkaConsumer({
+  brokers: ["localhost:9092"],
+  groupId: "dsp-processors",
+  topics: ["sensor-data"],
+  onMessage: async ({ value }) => {
+    const samples = new Float32Array(value.data);
+    const output = await pipeline.process(samples, {
+      channels: 1,
+      sampleRate: 44100,
+    });
+    console.log("Processed:", output[0]);
+  },
+});
+
+await consumer.run();
+```
+
+**See [Kafka Integration Guide](https://github.com/A-KGeorge/dsp_ts_redis/blob/main/docs/KAFKA_INTEGRATION.md) for real-time streaming examples.**
+
 ### Multi-Channel Processing
 
 ```typescript
@@ -577,6 +610,102 @@ const result2 = await moving.process(new Float32Array([1, 2, 3, 4, 5]));
 - **Batch**: Quality control metrics, batch statistics, data summarization
 - **Moving**: Signal smoothing, noise reduction, trend analysis, low-pass filtering
 
+##### Convolution Filter
+
+```typescript
+// Batch Mode - Process entire buffer with kernel
+pipeline.Convolution({ mode: "batch", kernel: Float32Array });
+
+// Moving Mode - Stateful streaming convolution
+pipeline.Convolution({
+  mode: "moving",
+  kernel: Float32Array,
+  method: "auto" | "direct" | "fft", // auto (default): switches at kernel size 64
+});
+```
+
+Implements high-performance 1D convolution with automatic FFT acceleration for large kernels. Supports arbitrary kernels for filtering, edge detection, feature extraction, and more.
+
+**Modes:**
+
+| Mode       | Description                        | State     | Output                            | Use Case                                 |
+| ---------- | ---------------------------------- | --------- | --------------------------------- | ---------------------------------------- |
+| `"batch"`  | Convolve kernel with entire buffer | Stateless | Full convolution of input         | Offline processing, batch filtering      |
+| `"moving"` | Stateful streaming convolution     | Stateful  | Overlap-add with state continuity | Real-time filtering, streaming workloads |
+
+**Parameters:**
+
+- `mode`: `"batch"` or `"moving"` - determines computation strategy
+- `kernel`: Float32Array - convolution kernel/filter coefficients
+- `method` (optional): `"auto"` (default), `"direct"`, or `"fft"`
+  - `"auto"`: Uses direct SIMD for kernel ≤ 64, FFT for kernel > 64
+  - `"direct"`: Always use direct convolution (SIMD-accelerated)
+  - `"fft"`: Always use FFT-based convolution (overlap-add for moving mode)
+
+**Features:**
+
+- **Automatic FFT acceleration**: Auto-switches at kernel size 64 for optimal performance
+- **SIMD optimization**: AVX2/SSE2 accelerated direct convolution (4-8x throughput)
+- **Zero allocations**: Pre-allocated buffers eliminate per-call overhead
+- **Cache-friendly**: De-interleaved processing for multi-channel signals
+- **Overlap-add**: Efficient chunked processing for moving mode FFT
+- **Per-channel state**: Independent convolution state for each channel
+
+**Performance Characteristics (Moving Mode):**
+
+| Kernel Size | Method Used   | Throughput (samples/sec) | vs Naive JS                             |
+| ----------- | ------------- | ------------------------ | --------------------------------------- |
+| K=8         | Direct (SIMD) | ~19M                     | Naive JS faster (110M) - see note below |
+| K=32        | Direct (SIMD) | ~12M                     | Naive JS faster (36M) - see note below  |
+| K=64        | Direct (SIMD) | ~7M                      | Naive JS faster (18M) - threshold point |
+| K=128       | FFT (overlap) | **82M**                  | **8.5x faster** than naive JS (9.6M)    |
+| K=256       | FFT (overlap) | **77M**                  | **15x faster** than naive JS (5M)       |
+
+**Example:**
+
+```typescript
+// Batch mode: Simple edge detection kernel
+const edgeKernel = new Float32Array([-1, 0, 1]); // Horizontal gradient
+const batch = createDspPipeline().Convolution({
+  mode: "batch",
+  kernel: edgeKernel,
+});
+const edges = await batch.process(signal);
+
+// Moving mode: Gaussian smoothing (auto FFT for K=7)
+const gaussianKernel = new Float32Array([0.06, 0.24, 0.4, 0.24, 0.06]);
+const moving = createDspPipeline().Convolution({
+  mode: "moving",
+  kernel: gaussianKernel,
+  method: "auto", // Uses direct SIMD (K < 64)
+});
+const smoothed = await moving.process(noisySignal);
+
+// Large kernel: Automatic FFT acceleration (K=128)
+const largeKernel = new Float32Array(128).fill(1 / 128); // Moving average K=128
+const fftConv = createDspPipeline().Convolution({
+  mode: "moving",
+  kernel: largeKernel,
+  method: "auto", // Auto-switches to FFT for 9x speedup
+});
+const filtered = await fftConv.process(data);
+```
+
+**Use Cases:**
+
+- **Signal Processing**: Custom FIR filters, bandpass/bandstop filters, matched filtering
+- **Computer Vision**: Edge detection (Sobel, Prewitt), Gaussian blur, sharpening
+- **Feature Extraction**: Wavelet convolution, pattern matching, template detection
+- **Audio Processing**: Impulse response convolution, reverb, echo effects
+- **Time Series**: Smoothing, differentiation, integration kernels
+
+**Mathematical Properties:**
+
+- **Linearity**: Conv(a·x₁ + b·x₂, h) = a·Conv(x₁, h) + b·Conv(x₂, h)
+- **Commutative**: x ⊛ h = h ⊛ x
+- **Associative**: (x ⊛ h₁) ⊛ h₂ = x ⊛ (h₁ ⊛ h₂)
+- **FFT Equivalence**: Time-domain convolution = Frequency-domain multiplication
+
 ##### RMS (Root Mean Square) Filter
 
 ```typescript
@@ -1778,9 +1907,32 @@ All 441 tests pass after these fixes. Run `npm test` to verify.
 
 ---
 
-## �📄 License
+## 🤝 Contributing
+
+We welcome contributions! Here are areas where help is particularly needed:
+
+### High Priority
+
+- **Kafka Integration Testing** – The Kafka streaming feature is experimental and needs comprehensive integration tests. Help us validate producer/consumer patterns, error handling, and performance under load.
+- **Additional Filters** – Implement new DSP filters (bandpass, highpass, lowpass, etc.) following the existing architecture patterns.
+
+### How to Contribute
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. Make your changes with tests
+4. Run `npm test` to ensure all tests pass
+5. Commit your changes (`git commit -m 'Add amazing feature'`)
+6. Push to the branch (`git push origin feature/amazing-feature`)
+7. Open a Pull Request
+
+For questions or discussions, please open an issue first!
+
+---
+
+### 📄 License
 
-MIT © Alan Kochukalam George
+Apache License 2.0 © Alan Kochukalam George
 
 ---
 

package/binding.gyp

@@ -13,16 +13,19 @@
         "src/native/core/WampFilter.cc",
         "src/native/core/WaveformLengthFilter.cc",
         "src/native/core/FftEngine.cc",
+        "src/native/core/Fftpack.cc",
         "src/native/core/MovingFftFilter.cc",
         "src/native/core/FirFilter.cc",
         "src/native/core/IirFilter.cc",
         "src/native/FftBindings.cc",
         "src/native/FilterBindings.cc",
+        "src/native/UtilityBindings.cc",
         "src/native/utils/CircularBufferArray.cc",
         "src/native/utils/CircularBufferVector.cc",
         "src/native/utils/NapiUtils.cc",
         "src/native/utils/SlidingWindowFilter.cc",
-        "src/native/utils/TimeSeriesBuffer.cc"
+        "src/native/utils/TimeSeriesBuffer.cc",
+        "src/native/adapters/FilterStage.cc"
       ],
       "include_dirs": [
         "<!@(node -p \"require('node-addon-api').include\")",
@@ -38,7 +41,7 @@
       "cflags!": [ "-fno-exceptions" ],
       "cflags_cc!": [ "-fno-exceptions" ],
       "cflags": [ "-O3", "-ffast-math" ],
-      "cflags_cc": [ "-std=c++17", "-O3", "-ffast-math" ],
+      "cflags_cc": [ "-std=c++17", "-O3", "-ffast-math" ],      
       "msvs_settings": {
         "VCCLCompilerTool": {
           "ExceptionHandling": 1,
@@ -52,12 +55,42 @@
         "GCC_ENABLE_CPP_EXCEPTIONS": "YES",
         "CLANG_CXX_LIBRARY": "libc++",
         "MACOSX_DEPLOYMENT_TARGET": "10.15",
-        "OTHER_CPLUSPLUSFLAGS": [ "-std=c++17", "-stdlib=libc++", "-O3", "-ffast-math" ],
+        "OTHER_CPLUSPLUSFLAGS": [ "-std=c++17", "-stdlib=libc++", "-O3", "-ffast-math"],
         "GCC_OPTIMIZATION_LEVEL": "3"
       },
       "conditions": [
+        # Condition for Windows
         ["OS=='win'", {
           "defines": [ "_HAS_EXCEPTIONS=1" ]
+        }],
+        # Condition for x64 architecture (Linux/macOS)
+        ['target_arch=="x64"', {
+          "cflags+": [ "-msse3", "-mavx", "-mavx2" ],
+          "cflags_cc+": [ "-msse3", "-mavx", "-mavx2" ],
+          'xcode_settings': {
+            'OTHER_CPLUSPLUSFLAGS+': [ '-msse3', '-mavx', '-mavx2' ]
+          }
+        }],
+        # Condition for ia32 architecture (Linux/macOS - if you support 32-bit x86)
+        ['target_arch=="ia32"', {
+           "cflags+": [ "-msse3", "-mavx", "-mavx2" ], # Or adjust based on 32-bit support
+           "cflags_cc+": [ "-msse3", "-mavx", "-mavx2" ],
+          'xcode_settings': {
+            'OTHER_CPLUSPLUSFLAGS+': [ '-msse3', '-mavx', '-mavx2' ]
+          }
+        }],
+        # Condition for arm64 architecture (Android, iOS, M1/M2 Macs, Tensor G4, etc.)
+        ['target_arch=="arm64"', {
+          "cflags+": [ "-march=armv8-a+fp+simd" ],  # Enable NEON and FP on ARMv8
+          "cflags_cc+": [ "-march=armv8-a+fp+simd" ],
+          'xcode_settings': {
+            'OTHER_CPLUSPLUSFLAGS+': [ '-march=armv8-a+fp+simd' ]
+          }
+        }],
+        # Condition for 32-bit ARM (older Android devices)
+        ['target_arch=="arm"', {
+          "cflags+": [ "-mfpu=neon", "-mfloat-abi=hard" ],  # 32-bit ARM NEON
+          "cflags_cc+": [ "-mfpu=neon", "-mfloat-abi=hard" ],
         }]
       ]
     }