docs/imporve documentaions

[lcweden]

This pull request significantly improves the clarity, usability, and maintainability of the jsontext library by enhancing documentation, refactoring stream classes for better encapsulation, and clarifying constants and public APIs. The most important changes are grouped below:

Documentation and Examples Improvements:

• Expanded and clarified the README.md with improved explanations, updated terminology (e.g., "structural symbol" instead of "delimiter"), and more practical usage examples, including a new section on replacing null values in streams. Also reorganized and simplified example pipelines for better approachability. [1] [2] [3] [4] [5]
• Added detailed JSDoc comments and usage examples to the stream classes (JSONTextDecoderStream, JSONTextEncoderStream, JSONTextLineStream, and JSONTextSelectorStream) to clarify their purpose and usage. [1] [2] [3] [4]

Stream Class Refactoring and API Consistency:

• Refactored all stream classes (JSONTextDecoderStream, JSONTextEncoderStream, JSONTextLineStream, JSONTextSelectorStream) to use private decoder/encoder fields and internal drain methods, improving encapsulation, error handling, and code clarity. [1] [2] [3] [4]
• Standardized stream constructors to accept options consistently and set sensible defaults for decoder/encoder options. [1] [2] [3]

Constants and Types Clarification:

• Added descriptive comments for all constants in src/common/constants.ts, including ASCII codes, Unicode escapes, token kinds, default options, and JSON Path segment types, improving maintainability and discoverability. [1] [2] [3] [4] [5]

API Documentation and Type Improvements:

• Improved and clarified JSDoc comments for core decoder and encoder classes, including more precise descriptions of error conditions, method behaviors, and return values. [1] [2] [3] [4] [5] [6] [7] [8]

Minor Fixes and Cleanups:

• Fixed import for Value in src/libs/stream-selector.ts to ensure proper type usage.

These changes collectively make the library easier to use, more robust, and better documented for both new and experienced users.