Restructure typescript

[avifenesh]

User Pain, Motivation, and Impact of the TS glide binding Restructure

Background: Why This Restructure Was Needed

Over the past months, users of glide have reported multiple pain points related to packaging, deployment, TypeScript support, and cross-platform use—especially when working with serverless environments, monorepos, and multiple package managers (npm, yarn, pnpm). The issues are well-documented across #3195, #3147, #2812, #2680, and #3599, and have become a recurring friction point for adoption and productivity.

---

What Was Broken & User Pain Points

1. Native Binaries and Packaging Complexity

• Current structure forced users to bundle all native .node binaries (for every OS/arch/libc), leading to:
  • Large deployments and slow CI/CD.
  • Risk of runtime failures from missing or mismatched binaries.
  • Frustration in monorepos or serverless builds that target multiple architectures.
• Platform-specific packages bundled both the native binary and the full JS wrapper, causing code duplication and bloat.
• Users compared this unfavorably to other native modules (e.g., sharp, next-swc, sentry-cli) that separate JS and native code cleanly.

2. TypeScript and Module Resolution Failures

• TypeScript projects encountered errors like Cannot find module 'glide-rs' or its corresponding type declarations.
• Type definitions that should be available from platform packages weren’t re-exported properly, breaking type-checking and editor experience.
• Users had to patch local installs (e.g., using [patch-package]) to inject missing types, creating fragile, non-scalable workarounds.

3. Package Manager Compatibility Issues

• Yarn and pnpm users experienced broken installs, missing dependencies, or failed builds due to the use of file: dependencies and non-standard package layout.
• npm ls and tools like esbuild/serverless-esbuild would fail pre-bundle due to dependency resolution errors.
• Inconsistent behavior between npm, yarn, and pnpm made onboarding and collaboration difficult.

4. Redundant and Unused Dependencies

• Packages (e.g., save) were present but unused, causing spurious errors and unnecessary bloat.
• Native and JS code were duplicated across platform-specific packages.

5. Documentation and Onboarding Confusion

• Users requested clearer installation, troubleshooting, and bundling instructions.
• Lack of public, working TypeScript examples exacerbated confusion.

---

Direct User Feedback (Examples)

• Users posted detailed minimal reproduction projects showing broken TypeScript builds.
• Multiple users described how bundling for multiple architectures led to duplicated JS code and inflated serverless bundles.
• Others highlighted that npm ls and CI/CD pipelines failed due to non-standard dependencies.
• The maintainers acknowledged the structure was a "broken CD" and committed to a full restructure.

---

How This PR (Restructure) Solves the Problems

Structural Overhaul

• Single JS/TS Base: All TypeScript/JS code lives in the main @valkey/valkey-glide package.
• Platform-Specific Native Binaries: Native code is isolated into platform packages (e.g., @valkey/valkey-glide-linux-arm64-gnu), eliminating redundant code and bloat.
• Runtime Platform Detection: At runtime, the correct native binary is loaded, following industry best practices.

TypeScript and Exports

• Proper Type Exports: All relevant types are exported directly from the main package, so TypeScript projects get type-checking and autocompletion out of the box.
• Exports Field: package.json uses the exports field, improving module resolution for all modern Node.js tools and editors.

Package Manager Compatibility

• No More file: Dependencies: All package dependencies are now standard, so npm, yarn, and pnpm work reliably.
• Compatibility Tests: CI now tests with all major package managers.

Clean Dependency Tree

• Remove Unused Dependencies: Unnecessary packages have been removed.
• Efficient Bundling: Only the code and binaries you need are bundled and deployed.

Documentation & CI/CD

• Updated Docs: Installation, troubleshooting, and platform support are all clearly documented.
• Modernized Workflows: CI/CD is streamlined, ensuring robust multi-platform builds and releases.

---

Impact: How It Helps Users

• Smaller, predictable bundles for serverless and monorepo users.
• TypeScript “just works”—no more hacks or patches.
• Consistent experience across npm, yarn, and pnpm.
• Simpler onboarding and easier troubleshooting.
• Future-proof structure for new platforms and use-cases.

---

Key Files to Review

• Package Structure:

  • node/package.json
  • node/rust-client/package.json

• CI/CD:

  • /.github/workflows/npm-cd.yml
  • /.github/workflows/node.yml

• Documentation:

  • node/README.md
  • node/DEVELOPER.md

• Tests:

  • node/pm-and-types-tests

---

Testing

• Test Infrastructure:
  • Added package manager compatibility and type declaration tests.
  • Tests now verify downstream usage and strict type checks.
• Compatibility tests with npm, yarn, and pnpm
• Type declaration tests with downstream packages
• Full test suite across all supported platforms
• Manual verification on Linux (GNU/musl) and macOS

All CI checks are passing.

---

References

• Issues: #3195, #3147, #2812, #2680, #3599
• PR: #3930: Restructure typescript
• Example reproduction: valkey-glide-tsc-mvp

---