Iterator Cascade Callbacks

JavaScript/TypeScript Iterables with Rust-like ergonomics: .filter, .map, and more!

• ⬆ Top of Document
•  Requirements
• ⚡ Quick Start
• 藺 Usage
  • import code and types as TypeScript module
  • require as NodeJS library
  • Synchronous.Iterator_Cascade_Callbacks examples
  • Asynchronous.Iterator_Cascade_Callbacks examples
•  Notes
• Common issues and possible fixes
  • Could not find a declaration file for module
•  Contributing
  •  Forking
  •  Sponsor
•  Attribution
• ⚖ Licensing

Requirements

NodeJS development dependencies may be installed via NPM...

npm install

Notice as of version 1.0.0 NodeJS dependencies are for development only, ie. if utilizing this project within other applications or as a Git submodule, then no third-party dependencies are required.

Quick Start

NodeJS projects may use npm to install iterator-cascade-callbacks as a dependency...

npm install @javascript-utilities/iterator-cascade-callbacks

... or as a development dependency via --save-dev command-line flag...

npm install --save-dev @javascript-utilities/iterator-cascade-callbacks

... Check Usage for quick tips on how to import this project within your own source code.

API documentation should be reasonably up-to-date with quick examples, and tips.

Usage

Note; the examples/ directory contains sample projects, which likely will be more instructive than this set of sub-sections.

import code and types as TypeScript module

import { Asynchronous, Synchronous } from '@javascript-utilities/iterator-cascade-callbacks';

import type {
  Asynchronous as Asynchronous_Types,
  Synchronous as Synchronous_Types,
  Shared as Shared_Types
} from '@javascript-utilities/iterator-cascade-callbacks';

require as NodeJS library

const { Asynchronous, Synchronous } = require('@javascript-utilities/iterator-cascade-callbacks');

Synchronous.Iterator_Cascade_Callbacks examples

• examples/mjs_webpack_counter/ ⇒ Demonstrate utilizing Iterator Cascade Callbacks with synchronous Counter Iterator
• examples/mts_node_fibonacci/ ⇒ Demonstrate utilizing Iterator Cascade Callbacks with synchronous Fibonacci generator

Asynchronous.Iterator_Cascade_Callbacks examples

• examples/mts_node_fetch/ ⇒ Demonstrate utilizing Iterator Cascade Callbacks with asynchronous fetch generator

Notes

This repository may not be feature complete and/or fully functional, Pull Requests that add features or fix bugs are certainly welcomed.

At time of writing (late 2023-10-16) it seems TypeScript will not fully parse exports from the package.json file, so while this project does publish features as self contained files, TypeScript consumers will need to import or require from the related index file.

However, those that are authoring pure JavaScript projects may make use of target/feature specific transpiled files; asynchronous.mjs, asynchronous.js, synchronous.mjs, and/or synchronous.js instead. Which should reduce network/system overhead for applications that require only a sub-set of features offered by the Iterator Cascade Callbacks library.

Common issues and possible fixes

Could not find a declaration file for module

Error message example

src/index.ts:3:30 - error TS7016: Could not find a declaration file for module '@javascript-utilities/iterator-cascade-callbacks'. '...' implicitly has an 'any' type.

Try `npm i --save-dev @types/iterator-cascade-callbacks` if it exists or add a new declaration (.d.ts) file containing `declare module '@javascript-utilities/iterator-cascade-callbacks';`

3 import { Asynchronous } from '@javascript-utilities/iterator-cascade-callbacks';
                               ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Possible fix define --moduleResolution as either node16 or nodenext

tsconfig.json (snip)

{
  "compilerOptions": {
    "moduleResolution": "NodeNext",
    "...": "..."
  }
}

Contributing

Options for contributing to Iterator Cascade Callbacks and JavaScript Utilities

Forking

Start making a Fork of this repository to an account that you have write permissions for.

• Add remote for fork URL. The URL syntax is [email protected]:<NAME>/<REPO>.git...

cd ~/git/hub/javascript-utilities/iterator-cascade-callbacks

git remote add fork [email protected]:<NAME>/iterator-cascade-callbacks.git

• Commit your changes and push to your fork, eg. to fix an issue...

cd ~/git/hub/javascript-utilities/iterator-cascade-callbacks


git commit -F- <<'EOF'
:bug: Fixes #42 Issue


**Edits**


- `<SCRIPT-NAME>` script, fixes some bug reported in issue
EOF


git push fork main

Note, the -u option may be used to set fork as the default remote, eg. git push -u fork main however, this will also default the fork remote for pulling from too! Meaning that pulling updates from origin must be done explicitly, eg. git pull origin main

• Then on GitHub submit a Pull Request through the Web-UI, the URL syntax is https://github.com/<NAME>/<REPO>/pull/new/<BRANCH>

Note; to decrease the chances of your Pull Request needing modifications before being accepted, please check the dot-github repository for detailed contributing guidelines.

Sponsor

Thanks for even considering it!

Via Liberapay you may on a repeating basis.

Regardless of if you're able to financially support projects such as iterator-cascade-callbacks that javascript-utilities maintains, please consider sharing projects that are useful with others, because one of the goals of maintaining Open Source repositories is to provide value to the community.

Attribution

• GitHub -- github-utilities/make-readme

• Dev IO -- Iterators in Typescript

• GitHub -- Microsoft/TypeScript -- Issue 3841 -- T.constructor should be of type T

• geekAbyte -- Typeing Iterables and Iterators with TypeScript

• Medium -- How to chain functions in JavaScript

• Mozilla Developer Network -- Iterators and Generators

• StackOverflow -- check if function is a generator

• StackOverflow -- Checking whether something is iterable

• StackOverflow -- Interfaces with construct signatures not type checking

• StackOverflow -- How can I add new line/linebreak character in title attribute in HTML

• Anthony Fu -- Ship ESM & CJS in one Package

• NPM -- Workspaces

• GitHub -- TypeScript Issue 50794 -- Support package.json exports outside of Node

• GitHub -- TypeScript Issue 49971 Type imports not taking "exports" of package.json into account

• GitHub -- TSDoc Issue 298 -- ESlint plugin: The TSDoc tag "@notExported" is not recognized

• API Extractor -- Defining your own TSDoc tags

License

Iterator that chains callback function execution
Copyright (C) 2023 S0AndS0

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU Affero General Public License as published
by the Free Software Foundation, version 3 of the License.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License
along with this program.  If not, see <https://www.gnu.org/licenses/>.

For further details review full length version of AGPL-3.0 License.