{"_id":"@codeforbreakfast/eventsourcing-transport-contracts","_rev":"4-1b3b007855808966de731597d9617f97","name":"@codeforbreakfast/eventsourcing-transport-contracts","dist-tags":{"latest":"0.2.2"},"versions":{"0.1.0":{"name":"@codeforbreakfast/eventsourcing-transport-contracts","version":"0.1.0","keywords":["transport","abstractions","contracts","interface","websocket","http","sse","message-transport","connection","streaming","effect","effect-ts","functional-programming","fp","typescript","type-safe"],"author":"Code for Breakfast","license":"MIT","_id":"@codeforbreakfast/eventsourcing-transport-contracts@0.1.0","maintainers":[{"name":"graemef","email":"graemef@gmail.com"}],"homepage":"https://github.com/codeforbreakfast/eventsourcing#readme","bugs":{"url":"https://github.com/codeforbreakfast/eventsourcing/issues"},"dist":{"shasum":"07d022868c7a2abe1c4fda8bd5a9b3e738e882de","tarball":"https://registry.npmjs.org/@codeforbreakfast/eventsourcing-transport-contracts/-/eventsourcing-transport-contracts-0.1.0.tgz","fileCount":7,"integrity":"sha512-tyG1PA4ELXIDaTfvl/iKxv3jJ4b9GM+c4/8yaYqIn/K2fYz611HCkp85Qm9O7pFF5eJin+mQiHafxPTSUbhebw==","signatures":[{"sig":"MEYCIQCdX9BhsotKz0nWvnltdLcIxAvcXWN8DgiAVGz933FSzAIhAJVwzkhBPsNHt7YGQ3Hn5SFG/xXl4H5PZf2mRUtHOkNU","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":20404},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","shasum":"07d022868c7a2abe1c4fda8bd5a9b3e738e882de","engines":{"node":">=18.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","default":"./dist/index.js"},"./package.json":"./package.json"},"scripts":{"lint":"eslint . --ext .ts,.tsx","test":"echo 'Contracts-only package - tests in implementations'","build":"bun build ./src/index.ts --outdir ./dist --target bun --format esm --external effect --external @effect/* && bun x tsc --build","clean":"rm -rf dist","typecheck":"tsc --noEmit","test:watch":"bun test --watch","prepublishOnly":"bun run clean && bun run build","publish:package":"bun publish --access public"},"_npmUser":{"name":"graemef","email":"graemef@gmail.com"},"_integrity":"sha512-tyG1PA4ELXIDaTfvl/iKxv3jJ4b9GM+c4/8yaYqIn/K2fYz611HCkp85Qm9O7pFF5eJin+mQiHafxPTSUbhebw==","repository":{"url":"https://github.com/codeforbreakfast/eventsourcing.git","type":"git","directory":"packages/eventsourcing-transport-contracts"},"_npmVersion":"10.8.3","description":"Pure transport layer abstractions and contracts for event sourcing - Define transport interfaces that any implementation (WebSocket, HTTP, SSE) can implement","directories":{},"sideEffects":false,"_nodeVersion":"24.3.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"effect":"3.17.14","eslint":"9.36.0","vitest":"3.2.4","typescript":"5.9.2","@types/node":"24.5.2"},"peerDependencies":{"effect":"^3.17.0"},"_npmOperationalInternal":{"tmp":"tmp/eventsourcing-transport-contracts_0.1.0_1758660234006_0.7770844038018214","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"@codeforbreakfast/eventsourcing-transport-contracts","version":"0.2.0","keywords":["transport","abstractions","contracts","interface","websocket","http","sse","message-transport","connection","streaming","effect","effect-ts","functional-programming","fp","typescript","type-safe"],"author":"Code for Breakfast","license":"MIT","_id":"@codeforbreakfast/eventsourcing-transport-contracts@0.2.0","maintainers":[{"name":"graemef","email":"graemef@gmail.com"}],"homepage":"https://github.com/codeforbreakfast/eventsourcing#readme","bugs":{"url":"https://github.com/codeforbreakfast/eventsourcing/issues"},"dist":{"shasum":"448ef1e1fed9882026cff4de0076f598a4c73868","tarball":"https://registry.npmjs.org/@codeforbreakfast/eventsourcing-transport-contracts/-/eventsourcing-transport-contracts-0.2.0.tgz","fileCount":7,"integrity":"sha512-vQgUei9uYPSvRxbnorTjnPURJftOCvT+6n/0HE8R6wK1L6M4bFIeP+3IddhvuoI8dqFJVNL7wU8Z/kh1bszytw==","signatures":[{"sig":"MEQCIEIIF2lByoRHJnwBDgWL1qmgSV7IYKWDedLT6ifRGQMoAiA8wFBFeSlDRUSTQvfRThAUeof3SuRE9DHp6bRUKqny/A==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":20404},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","shasum":"448ef1e1fed9882026cff4de0076f598a4c73868","engines":{"node":">=18.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","default":"./dist/index.js"},"./package.json":"./package.json"},"scripts":{"lint":"eslint . --ext .ts,.tsx","test":"echo 'Contracts-only package - tests in implementations'","build":"bun build ./src/index.ts --outdir ./dist --target bun --format esm --external effect --external @effect/* && bun x tsc --build","clean":"rm -rf dist","typecheck":"tsc --noEmit","test:watch":"bun test --watch","prepublishOnly":"bun run clean && bun run build","publish:package":"bun publish --access public"},"_npmUser":{"name":"graemef","email":"graemef@gmail.com"},"_integrity":"sha512-vQgUei9uYPSvRxbnorTjnPURJftOCvT+6n/0HE8R6wK1L6M4bFIeP+3IddhvuoI8dqFJVNL7wU8Z/kh1bszytw==","repository":{"url":"https://github.com/codeforbreakfast/eventsourcing.git","type":"git","directory":"packages/eventsourcing-transport-contracts"},"_npmVersion":"10.8.3","description":"Pure transport layer abstractions and contracts for event sourcing - Define transport interfaces that any implementation (WebSocket, HTTP, SSE) can implement","directories":{},"sideEffects":false,"_nodeVersion":"24.3.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"effect":"3.17.14","eslint":"9.36.0","vitest":"3.2.4","typescript":"5.9.2","@types/node":"24.5.2"},"peerDependencies":{"effect":"^3.17.0"},"_npmOperationalInternal":{"tmp":"tmp/eventsourcing-transport-contracts_0.2.0_1758660742291_0.3136917516210713","host":"s3://npm-registry-packages-npm-production"}},"0.2.1":{"name":"@codeforbreakfast/eventsourcing-transport-contracts","version":"0.2.1","keywords":["transport","abstractions","contracts","interface","websocket","http","sse","message-transport","connection","streaming","effect","effect-ts","functional-programming","fp","typescript","type-safe"],"author":"Code for Breakfast","license":"MIT","_id":"@codeforbreakfast/eventsourcing-transport-contracts@0.2.1","maintainers":[{"name":"graemef","email":"graemef@gmail.com"}],"homepage":"https://github.com/codeforbreakfast/eventsourcing#readme","bugs":{"url":"https://github.com/codeforbreakfast/eventsourcing/issues"},"dist":{"shasum":"64f726442449eba00c2247507d18c8113abd8a76","tarball":"https://registry.npmjs.org/@codeforbreakfast/eventsourcing-transport-contracts/-/eventsourcing-transport-contracts-0.2.1.tgz","fileCount":7,"integrity":"sha512-hHS2OP8b9b7x3USWNhMbQkqXcgUw0wKKNiiM397+9B5YUshKYKEl40ZJmALQONQ3nY6FCcFj5VPdWACSV3canQ==","signatures":[{"sig":"MEYCIQDhbkEaGCNfSR8ApWopcT9sxqRdoCI1hO7U6ACWoCjJwQIhAIJTcxkm3M8KCsezqZb+L/56eTe4KpDx8mQMv7mlxTEj","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":20404},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","shasum":"64f726442449eba00c2247507d18c8113abd8a76","engines":{"node":">=18.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","default":"./dist/index.js"},"./package.json":"./package.json"},"scripts":{"lint":"eslint . --ext .ts,.tsx","test":"echo 'Contracts-only package - tests in implementations'","build":"bun build ./src/index.ts --outdir ./dist --target bun --format esm --external effect --external @effect/* && bun x tsc --build","clean":"rm -rf dist","typecheck":"tsc --noEmit","test:watch":"bun test --watch","prepublishOnly":"bun run clean && bun run build","publish:package":"bun publish --access public"},"_npmUser":{"name":"graemef","email":"graemef@gmail.com"},"_integrity":"sha512-hHS2OP8b9b7x3USWNhMbQkqXcgUw0wKKNiiM397+9B5YUshKYKEl40ZJmALQONQ3nY6FCcFj5VPdWACSV3canQ==","repository":{"url":"https://github.com/codeforbreakfast/eventsourcing.git","type":"git","directory":"packages/eventsourcing-transport-contracts"},"_npmVersion":"10.8.3","description":"Pure transport layer abstractions and contracts for event sourcing - Define transport interfaces that any implementation (WebSocket, HTTP, SSE) can implement","directories":{},"sideEffects":false,"_nodeVersion":"24.3.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"effect":"3.17.14","eslint":"9.36.0","vitest":"3.2.4","typescript":"5.9.2","@types/node":"24.5.2"},"peerDependencies":{"effect":"^3.17.0"},"_npmOperationalInternal":{"tmp":"tmp/eventsourcing-transport-contracts_0.2.1_1758697835797_0.39703660282496234","host":"s3://npm-registry-packages-npm-production"}},"0.2.2":{"name":"@codeforbreakfast/eventsourcing-transport-contracts","version":"0.2.2","description":"Pure transport layer abstractions and contracts for event sourcing - Define transport interfaces that any implementation (WebSocket, HTTP, SSE) can implement","type":"module","main":"./dist/index.js","module":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","default":"./dist/index.js"},"./package.json":"./package.json"},"scripts":{"build":"bun build ./src/index.ts --outdir ./dist --target bun --format esm --external effect --external @effect/* && bun x tsc --build","test":"echo 'Contracts-only package - tests in implementations'","test:watch":"bun test --watch","lint":"eslint . --ext .ts,.tsx","typecheck":"tsc --noEmit","clean":"rm -rf dist","publish:package":"npm publish --access public"},"keywords":["transport","abstractions","contracts","interface","websocket","http","sse","message-transport","connection","streaming","effect","effect-ts","functional-programming","fp","typescript","type-safe"],"author":{"name":"Code for Breakfast"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/codeforbreakfast/eventsourcing.git","directory":"packages/eventsourcing-transport-contracts"},"bugs":{"url":"https://github.com/codeforbreakfast/eventsourcing/issues"},"homepage":"https://github.com/codeforbreakfast/eventsourcing#readme","peerDependencies":{"effect":"^3.17.0"},"devDependencies":{"@types/node":"24.5.2","effect":"3.17.14","typescript":"5.9.2","vitest":"3.2.4","eslint":"9.36.0"},"publishConfig":{"access":"public"},"sideEffects":false,"engines":{"node":">=18.0.0"},"_id":"@codeforbreakfast/eventsourcing-transport-contracts@0.2.2","gitHead":"9510ad686c016cbbf486f3572a78ce3b8e031131","_nodeVersion":"20.19.5","_npmVersion":"10.8.2","dist":{"integrity":"sha512-01O+danCh4BMs46e1Yvmp63RsCymHm+D08UpAoHYYnwMsbBwLvZRIYLtYPbspRZcBhECSX/yxuzi0b6Vr9scdg==","shasum":"9ef4c7d205d4f502ff7184a47774885607eede36","tarball":"https://registry.npmjs.org/@codeforbreakfast/eventsourcing-transport-contracts/-/eventsourcing-transport-contracts-0.2.2.tgz","fileCount":15,"unpackedSize":35695,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCICp0HSUnYCWdOPAw1wSl0B0zOBMDqQmM5vcPpchkD3JtAiEAplpKp0bjdCFPwgPcJsxPNVewf/NOJICUwvvyPiBYvNo="}]},"_npmUser":{"name":"graemef","email":"graemef@gmail.com"},"directories":{},"maintainers":[{"name":"graemef","email":"graemef@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/eventsourcing-transport-contracts_0.2.2_1758706996911_0.165399761588366"},"_hasShrinkwrap":false}},"time":{"created":"2025-09-23T20:43:53.945Z","modified":"2025-09-24T09:43:17.263Z","0.1.0":"2025-09-23T20:43:54.211Z","0.2.0":"2025-09-23T20:52:22.481Z","0.2.1":"2025-09-24T07:10:35.991Z","0.2.2":"2025-09-24T09:43:17.084Z"},"bugs":{"url":"https://github.com/codeforbreakfast/eventsourcing/issues"},"author":{"name":"Code for Breakfast"},"license":"MIT","homepage":"https://github.com/codeforbreakfast/eventsourcing#readme","keywords":["transport","abstractions","contracts","interface","websocket","http","sse","message-transport","connection","streaming","effect","effect-ts","functional-programming","fp","typescript","type-safe"],"repository":{"type":"git","url":"git+https://github.com/codeforbreakfast/eventsourcing.git","directory":"packages/eventsourcing-transport-contracts"},"description":"Pure transport layer abstractions and contracts for event sourcing - Define transport interfaces that any implementation (WebSocket, HTTP, SSE) can implement","maintainers":[{"name":"graemef","email":"graemef@gmail.com"}],"readme":"# @codeforbreakfast/eventsourcing-transport-contracts\n\nPure transport layer abstractions and contracts for event sourcing. Define transport interfaces that any implementation (WebSocket, HTTP, SSE) can implement.\n\n## Overview\n\nThis package provides the core abstractions for building transport layers in event sourcing systems. It contains **only contracts and testing utilities** - no implementations. This ensures clean separation between transport protocols and the business logic that uses them.\n\n## Key Features\n\n- **Protocol Agnostic**: Abstractions work with any transport (WebSocket, HTTP, SSE, etc.)\n- **Type Safe**: Full TypeScript support with generic message types\n- **Effect-Native**: Built on Effect for functional programming patterns\n- **Contract Testing**: Complete test suite to verify transport implementations\n- **Connection Management**: Standardized connection lifecycle management\n- **Stream Support**: First-class support for message streaming\n- **Error Handling**: Comprehensive error types for transport failures\n\n## Core Interfaces\n\n### `ConnectedTransport<TMessage>`\n\nThe main interface representing a fully connected transport that can send and receive messages:\n\n```typescript\ninterface ConnectedTransport<TMessage extends TransportMessage = TransportMessage>\n  extends ConnectionManager,\n    MessagePublisher<TMessage>,\n    MessageSubscriber<TMessage>,\n    RequestResponse {}\n```\n\n### `TransportConnector<TMessage>`\n\nThe factory interface for creating connected transports. This design prevents calling transport methods before establishing a connection:\n\n```typescript\ninterface TransportConnector<TMessage extends TransportMessage = TransportMessage> {\n  readonly connect: (\n    url: string\n  ) => Effect.Effect<ConnectedTransport<TMessage>, ConnectionError, Scope.Scope>;\n}\n```\n\n### `TransportMessage<TPayload>`\n\nThe base message type that all transport implementations must handle:\n\n```typescript\ninterface TransportMessage<TPayload = unknown> {\n  readonly id: string;\n  readonly type: string;\n  readonly payload: TPayload;\n  readonly metadata?: Record<string, unknown>;\n  readonly timestamp?: Date;\n}\n```\n\n## Error Types\n\nThe package provides standardized error types:\n\n- `TransportError` - General transport operation failures\n- `ConnectionError` - Connection establishment/management failures\n- `MessageParseError` - Message serialization/deserialization failures\n\n## Contract Testing\n\nUse `runTransportContractTests` to verify your transport implementation meets all requirements:\n\n```typescript\nimport { runTransportContractTests } from '@codeforbreakfast/eventsourcing-transport-contracts';\n\nrunTransportContractTests('My Transport', () => setupMyTransport(), {\n  supportsReconnection: true,\n  supportsOfflineBuffering: false,\n  guaranteesOrdering: true,\n  supportsMultiplexing: true,\n});\n```\n\n## Optional Features\n\nTransports can optionally support advanced features:\n\n```typescript\ninterface TransportFeatures {\n  readonly supportsReconnection?: boolean;\n  readonly supportsOfflineBuffering?: boolean;\n  readonly supportsBackpressure?: boolean;\n  readonly guaranteesOrdering?: boolean;\n  readonly supportsMultiplexing?: boolean;\n  readonly supportsBatching?: boolean;\n  readonly supportsCompression?: boolean;\n}\n```\n\n## Usage Example\n\n```typescript\nimport { Effect, Stream } from 'effect';\nimport type {\n  TransportConnector,\n  TransportMessage,\n} from '@codeforbreakfast/eventsourcing-transport-contracts';\n\n// Define your message types\ninterface MyMessage extends TransportMessage<string> {\n  type: 'chat' | 'notification';\n}\n\n// Use a transport connector\nconst useTransport = (connector: TransportConnector<MyMessage>) =>\n  Effect.gen(function* () {\n    // Connect to transport\n    const transport = yield* connector.connect('ws://localhost:8080');\n\n    // Subscribe to messages\n    const messageStream = yield* transport.subscribe((msg) => msg.type === 'chat');\n\n    // Send a message\n    yield* transport.publish({\n      id: crypto.randomUUID(),\n      type: 'chat',\n      payload: 'Hello, world!',\n      timestamp: new Date(),\n    });\n\n    // Process incoming messages\n    yield* Stream.runForEach(messageStream, (message) =>\n      Effect.logInfo(`Received: ${message.payload}`)\n    );\n  });\n```\n\n## Design Principles\n\n### 1. Protocol Independence\n\nThe abstractions work with any underlying protocol. Whether you're using WebSockets, Server-Sent Events, HTTP long polling, or custom TCP protocols, the same interfaces apply.\n\n### 2. Connection Safety\n\nThe `TransportConnector` pattern ensures you cannot call transport methods before establishing a connection. This prevents a whole class of runtime errors.\n\n### 3. Type Safety\n\nGeneric message types ensure compile-time safety for your specific message formats while allowing the transport layer to remain generic.\n\n### 4. Effect Integration\n\nBuilt on Effect for composable, type-safe error handling and resource management. Connections are automatically cleaned up when scopes exit.\n\n### 5. Testing First\n\nThe contract test suite ensures any implementation correctly handles edge cases like reconnection, message ordering, and error conditions.\n\n## Related Packages\n\n- `@codeforbreakfast/eventsourcing-websocket-transport` - WebSocket implementation\n- `@codeforbreakfast/eventsourcing-store` - Event store abstractions\n- `@codeforbreakfast/eventsourcing-aggregates` - Aggregate root patterns\n\n## License\n\nMIT\n","readmeFilename":"README.md"}