v4 merge

[igorls]

No description provided.

[Copilot]

Pull Request Overview

This PR merges version 4 changes, updating the API and project structure while adding new examples and documentation generation scripts. Key changes include new utility functions in src/functions.ts, multiple example scripts demonstrating advanced filtering and monitoring, and major updates to package.json and build artifacts with the removal of legacy bundle files.

Reviewed Changes

Copilot reviewed 64 out of 64 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
src/functions.ts	Adds utility functions (e.g., trimTrailingSlash, replaceMetaFields) with improved meta-field processing.
src/examples/*	Introduces new monitoring and filtering examples; some older examples are removed.
scripts/generate-documentation.mjs	Adds a documentation generation script using PowerShell and markitdown.
package.json	Updates version, dependencies, and engine requirements for v4.
lib/*	Removes legacy ESM and CommonJS bundle files to streamline the build.

Comments suppressed due to low confidence (1)

src/examples/advanced-filtering.ts:219

• Verify whether 'lastknwnrate' is the intended table name or a possible typo for 'lastknownrate'.

table: 'lastknwnrate',

[gemini-code-assist]

Hello @igorls, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

Summary of Changes

gemini-code-assist here, providing a summary of this pull request titled "v4 merge". Based on the extensive changes across the codebase, particularly the complete overhaul of the README and the introduction of new core files and test infrastructure, the clear intent of this PR is to introduce a major version update (v4) of the Hyperion Stream Client. This update appears to involve significant refactoring, introduction of new features like the AsyncIterator pattern and enhanced event handling, improved compatibility across different JavaScript environments, and a comprehensive update to the documentation and testing suite.

Highlights

• Major Version Update (v4): This PR represents a significant update to the Hyperion Stream Client, indicated by the version bump to 4.0.0-rc.2 and widespread changes.
• Refactored Core Architecture: The client's internal architecture has been refactored, introducing a new HyperionStream class to manage individual stream requests and their lifecycle, moving away from the previous async handler model.
• Enhanced API and Features: The client now supports the AsyncIterator pattern for consuming stream data (for await...of), alongside an improved event-based API. New options like libMonitor and connectionTimeout have been added, and stream requests now support ignore_live, filter_op, and replayOnReconnect.
• Improved Environment Support: Documentation and examples have been updated to explicitly cover Node.js (v18+), Browser ES Modules (with bundlers and Import Maps), and UMD bundle usage.
• Comprehensive Documentation and Testing: The README has been completely rewritten to serve as detailed documentation. A new script for generating full documentation has been added. The testing suite has been significantly expanded with new tests covering connection, streaming, error handling, API features, and browser compatibility.

Changelog

Click here to see the changelog

• .gitignore
  • Added build and documentation related files (lib, source.md, src.zip, FULL_DOCUMENTATION.md) to the ignore list.
• README.md
  • Complete rewrite of the README, providing detailed documentation for v4 features, installation, usage examples (event-based and async iterator), configuration options, and development instructions.
• examples/cjs_import.js
  • Removed old CommonJS example file.
• examples/esm_import.mjs
  • Removed old ES Module example file.
• examples/html_example.html
  • Removed old HTML example file.
• package.json
  • Updated package version to 4.0.0-rc.2.
  • Increased Node.js engine requirement to >=18.
  • Updated dependencies (async, socket.io-client).
  • Removed cross-fetch dependency.
  • Updated devDependencies and build tools versions.
  • Added tsx for running TypeScript examples directly.
  • Added new npm scripts for testing (test, test:watch, test:connection, test:streaming, test:error-handling, test:api) using Node.js native test runner.
  • Added serve:tests script for running browser tests.
  • Added generate-docs script.
• scripts/generate-documentation.mjs
  • New script to automate documentation generation by zipping source, running markitdown, and combining README with generated source docs.
• src/bundle-index.js
  • Removed generated file.
• src/bundle-index.js.map
  • Removed generated file.
• src/bundle-index.ts
  • Updated UMD bundle entry point to correctly export HyperionStreamClient for global access and as default/named exports.
  • Added TypeScript global declaration for window.HyperionStreamClient.
• src/examples/advanced-filtering.ts
  • New example file demonstrating advanced filtering and usage of the new API features.
• src/examples/basic-monitoring.ts
  • New example file demonstrating basic stream monitoring.
• src/examples/lib-monitor.ts
  • New example file demonstrating the libMonitor feature.
• src/functions.d.ts
  • Removed generated file.
• src/functions.js
  • Removed generated file.
• src/functions.js.map
  • Removed generated file.
• src/functions.ts
  • Added trimTrailingSlash helper function.
  • Added replaceMetaFields function to process Hyperion's @ prefixed metadata fields.
• src/hyperion-stream-client.d.ts
  • Removed generated file.
• src/hyperion-stream-client.js
  • Removed generated file.
• src/hyperion-stream-client.js.map
  • Removed generated file.
• src/hyperion-stream-client.ts
  • Major refactor of the core client logic.
  • Removed old async data handlers (setAsyncDataHandler, setAsyncLibDataHandler).
  • Introduced HyperionStream class to manage individual stream requests.
  • Added libMonitor option and logic to track the last irreversible block.
  • Updated connection handling, including adding connectionTimeout.
  • Refactored message processing to delegate to HyperionStream instances.
  • Updated streamActions and streamDeltas methods to return HyperionStream instances.
  • Added chainId property to the client.
  • Implemented stop method to cancel individual streams.
  • Updated event emission to use typed events.
• src/hyperion-stream.ts
  • New file introducing the HyperionStream class.
  • Handles the lifecycle, configuration, and message processing for a single stream request.
  • Implements the AsyncIterator pattern ([Symbol.asyncIterator]).
  • Manages event handlers specific to the stream (on, off, once).
  • Includes logic for processing history and live messages, and queueing.
  • Generates a unique hash for each stream request.
• src/interfaces.d.ts
  • Removed generated file.
• src/interfaces.js
  • Removed generated file.
• src/interfaces.js.map
  • Removed generated file.
• src/interfaces.ts
  • Updated HyperionClientOptions to include libMonitor and connectionTimeout.
  • Updated StreamActionsRequest and StreamDeltasRequest interfaces with new optional parameters (read_until, ignore_live, filter_op, filters, replayOnReconnect).
  • Updated RequestFilter interface to support more value types and operators.
  • Updated ActionContent and DeltaContent interfaces with additional fields and improved type definitions.
  • Updated IncomingData interface to be generic and include uuid.
  • Renamed LIBData to LIBUpdate.
  • Introduced new interfaces for stream events (HyperionStreamEvent, EventMap, HyperionStreamEventMap, TypedEventListener, EventData).
  • Defined StreamTypeMap to map stream types to their request and response interfaces.
  • Removed AsyncHandlerFunction type.
• test/api.test.js
  • New test file covering client API features like event handling, lastBlockNum, debug logging, and custom options.
• test/browser/README.md
  • New README file documenting the browser test setup and files.
• test/browser/console-logger.js
  • New helper script to display console output directly in browser HTML for easier debugging.
• test/browser/import-map-esm-test.html
  • New HTML test page for verifying ESM imports using import maps in browsers.
• test/browser/serve-tests.cjs
  • New simple HTTP server script to serve local test files for browser testing.
• test/browser/umd-global-test.html
  • New HTML test page for verifying UMD bundle loading and global access in browsers.
• test/connection.test.js
  • New test file covering client connection, error handling, reconnection, and timeout scenarios.
• test/error-handling.test.js
  • New test file covering stream request validation, simulated network/server errors, stream cancellation, and multiple streams.
• test/index.js
  • New main test file to serve as the entry point for running all Node.js native tests.
• test/setup.js
  • New file containing common test utilities like createTestClient, wait, TEST_TIMEOUT, and createMockSocket.
• test/streaming.test.js
  • New test file covering streaming actions and deltas using both event-based and async iterator APIs.
• tsconfig.base.json
  • Updated lib compiler option to include DOM for browser compatibility.
  • Added noImplicitAny and strictNullChecks for stricter type checking.
• tsconfig.commonjs.json
  • Added exclude option to exclude example files from the CommonJS build.
• tsconfig.json
  • Updated module, moduleResolution, and target compiler options to NodeNext/NodeNext/ESNext for modern Node.js environments.
• webpack.config.cjs
  • Removed externals configuration for cross-fetch as it's no longer a direct dependency.
  • Updated output.library configuration to correctly export the default export for UMD.
  • Added resolve.alias to map internal module paths for webpack.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point in your pull request via creating an issue comment (i.e. comment on the pull request page) using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in issue comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist is currently in preview and may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments to provide feedback.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

---

A stream of data flows,
Through WebSocket, the client knows.
Actions, deltas, block by block,
Code refactored, a solid rock.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces a significant refactoring of the Hyperion Stream Client, moving towards a more modular architecture with the introduction of the HyperionStream class to manage individual streams. The changes also add new features like LIB monitoring and enhanced filtering options. The documentation has been greatly improved, and a comprehensive test suite has been added, which is excellent! Overall, this is a substantial and positive update.

Summary of Findings

• Major Refactoring: The core architecture has been refactored to use a dedicated HyperionStream class for managing individual streams, improving modularity.
• Breaking Change: 'LIB' start_from: The client-side resolution of start_from: 'LIB' has been removed. This is a breaking change for users relying on this feature.
• Duplicate Stream Requests: The client now prevents creating multiple streams with identical parameters by throwing an error.
• New Features: Added LIB monitoring, ignore_live, replayOnReconnect options, and more flexible filtering with operators.
• Improved Documentation: The README.md has been significantly updated with detailed usage instructions, features, and examples.
• Enhanced Testing: A comprehensive test suite using Node.js Native Test Runner and browser tests has been added.
• TypeScript Improvements: Increased TypeScript strictness (noImplicitAny, strictNullChecks) and improved type definitions for events and streams.

Merge Readiness

The pull request introduces significant improvements and new features. However, there is a high-severity breaking change related to the handling of start_from: 'LIB' that should be addressed or clearly documented before merging. The design choice regarding duplicate stream requests is also worth considering. I recommend addressing these points before merging. I am unable to approve the pull request; please have others review and approve this code before merging.