How victor141516/pledge works
Project type and purpose
• This is an open-source, TypeScript-based library (“@victor141516/pledge”) that enables streaming of JavaScript objects containing promises over HTTP using the JSON Lines format.
• It provides both a server-side component (to serialize promises into a progressive stream) and a client-side component (to reconstruct the object and resolve promises as data arrives).
File structure
• Top-level folders:
• src/common: shared utilities (type definitions, identifier generation, type checking)
• src/server: server implementation (core logic, Express adapter, response creation)
• src/client: client implementation (readResponse entry point, items handler)
• dist/: compiled output mirroring src structure for publish
• tests/: unit, integration, and end-to-end specs covering both client and server code
• Key configuration artefacts: package.json, tsconfig.json, .gitignore
• Build scripts not explicit—bun.lock suggests Bun support but npm scripts live in package.json
README for insights
• Core flow described in “How It Works”:
a. Server replaces promises in the object with placeholders and streams a skeleton JSON line
b. As each promise resolves, it streams an individual JSON line with its resolved value
c. Client reconstructs the original object, inserting placeholder promises that resolve when their corresponding stream item arrives
• The library is framework-agnostic but ships with an Express middleware adapter
Main components and their relationships
a. Application (e.g., Express app)
b. pledgeMiddleware (server adapter) ← part of src/server/adapters/express
c. Server core:
• items-handler.ts: traverses object, extracts promises, assigns placeholder IDs
• create-response.ts: orchestrates JSON Lines streaming over HTTP
d. HTTP Layer: chunked transfer encoding, newline-delimited JSON
e. Client core:
• read-response.ts: reads incoming JSON Lines, reconstructs object skeleton, wires placeholder promises
• items-handler.ts: resolves individual promises in the reconstructed object
f. Common utilities (src/common): type definitions, identifier generation, validation of payloads
Architectural patterns and design principles
• Streaming pipeline: backpressure-safe, chunked JSON Lines
• Adapter pattern: Express middleware abstracts over any HTTP framework
• Separation of concerns: common logic separated from server/client specifics
• Type safety: full TS definitions ensure correct usage and inference