Library Restructuring: Facade, Tree-Shaking, and API Ergonomics

[aamironline]

Need to restructure the Internet Object JS/TS library to ensure an ergonomic, future-proof API, maximize tree-shaking/bundle size efficiency, and set the stage for upcoming features (like streaming). This will improve developer experience, maintainability, and performance for all users.

Goals

• Provide a unified, ergonomic facade for the core API (one-import DX, with memorable aliases and discoverable full names).
• Support fully tree-shakable named exports for power users and minimal bundles.
• Ensure all exports are side-effect free and that importing a single feature brings in only its dependencies.
• Prepare the API surface for future streaming and advanced helpers (e.g., progressive parsing/writing).
• Update TypeScript types and JSDoc for comprehensive editor/IDE support.
• Clarify and document both import styles (default facade and named exports) in all docs and examples.
• Automate or validate tree-shaking and bundle size in CI (size-limit, Rollup, or similar).

Scope / Acceptance Criteria

• Refactor entrypoint:
  - Separate named exports and facade/default export for best tree-shaking.
• Implement and document short aliases and full names (e.g., io.doc, io.defs, io.document, io.definitions).
• Add and document streaming API placeholders in the facade (for future chunked read/write).
• Add "sideEffects": false to package.json and ensure entrypoints have no side effects.
• Ensure all main features are exported as both named exports and via the facade.
• Update README and code examples to show ergonomic usage patterns and best practices.
• Add or configure bundle-size/tree-shaking tests in CI.
• Maintain or improve current test coverage.

Outcome

• The library will be easier to use (and teach) for new users, and more efficient for advanced users.
• Future development (streaming, helpers, modularity) will be straightforward.
• Consumption in all major environments (Node, browser, serverless, bundlers) will be simple and efficient.

Notes

• This issue does not cover independent refactoring of individual classes or internal logic, only the structure, exports, DX, and preparation for growth.
• If you want to discuss specific naming, facade shape, or export conventions, please comment below.