{"id":24064892,"url":"https://github.com/gearonix/gatefetched","last_synced_at":"2025-04-23T19:50:11.545Z","repository":{"id":223903693,"uuid":"761275590","full_name":"gearonix/gatefetched","owner":"gearonix","description":"💡 An addon for farfetched, seamlessly integrating WebSocket and SSE protocols for real-time data transmission.","archived":false,"fork":false,"pushed_at":"2024-03-03T14:23:57.000Z","size":1078,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-14T06:02:39.147Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gearonix.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-02-21T15:10:41.000Z","updated_at":"2024-08-27T15:22:19.000Z","dependencies_parsed_at":"2024-02-22T17:54:58.010Z","dependency_job_id":"771c4fe9-eded-4cfa-a3b0-56a77c982f9f","html_url":"https://github.com/gearonix/gatefetched","commit_stats":null,"previous_names":["gearonix/farsocket","gearonix/gatefetched","grnxx/gatefetched","gearonixx/gatefetched"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gearonix%2Fgatefetched","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gearonix%2Fgatefetched/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gearonix%2Fgatefetched/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gearonix%2Fgatefetched/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gearonix","download_url":"https://codeload.github.com/gearonix/gatefetched/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250504561,"owners_count":21441608,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-01-09T10:53:22.130Z","updated_at":"2025-04-23T19:50:11.525Z","avatar_url":"https://github.com/gearonix.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"Gatefetched\n=====================\n\n[![npm](https://img.shields.io/npm/v/gatefetched)](https://www.npmjs.com/package/gatefetched)\n\u003ca href=\"https://github.com/gearonix/gatefetched\" rel=\"nofollow\"\u003e\n\u003cimg src=\"https://img.shields.io/github/license/gearonix/gatefetched\" alt=\"License\"\u003e\n\u003c/a\u003e\n\u003ca href=\"https://github.com/gearonix/gatefetched\" rel=\"nofollow\"\u003e\n\u003cimg src=\"https://img.shields.io/badge/PRs-welcome-brightgreen.svg\" alt=\"PRs Welcome\"\u003e\n\u003c/a\u003e\n\nAn add-on for [farfetched](https://github.com/igorkamyshev/farfetched), providing integration of Socket.IO, WebSocket, and Server-Sent Events (SSE) protocols for seamless real-time data transmission.\n\n\u003e [!WARNING]\n\u003e This library is at an early stage of development.\n\n## Table of Contents\n\n\u003c!-- START doctoc generated TOC please keep comment here to allow auto update --\u003e\n\u003c!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE --\u003e\n\n- [Quick Features](#quick-features)\n- [Installation](#installation)\n- [Usage](#usage)\n  - [Getting Started](#getting-started)\n  - [Public API](#public-api)\n  - [Adapter API](#adapter-api)\n  - [Scoped Gateways](#scoped-gateways)\n- [Examples](#examples)\n- [Public API](#public-api-1)\n  - [`createGateway`](#creategateway)\n    - [BaseCreateGatewayParams Interface](#basecreategatewayparams-interface)\n    - [ProtocolGateway Interface](#protocolgateway-interface)\n  - [`listener`](#listener)\n    - [BaseListenerConfig Interface](#baselistenerconfig-interface)\n    - [Listener Interface](#listener-interface)\n  - [`dispatcher`](#dispatcher)\n    - [BaseDispatcherConfig Interface](#basedispatcherconfig-interface)\n    - [Dispatcher Interface](#dispatcher-interface)\n\n\u003c!-- END doctoc generated TOC please keep comment here to allow auto update --\u003e\n\n\nQuick Features\n-----\n\n- Framework-agnostic\n- Comprehensive TypeScript support\n- Supports three protocols out of the box\n\n## Installation\n\nDepending on your package manager:\n\n```bash\n# using `pnpm`\n$ pnpm add gatefetched\n\n# using `yarn`\n$ yarn add gatefetched\n\n# using `npm`\n$ npm install --save gatefetched\n```\n\n\nUsage\n-----\n\n### Getting Started\n\nCreate an instance of the desired protocol:\n\n```typescript\nimport { io } from 'socket.io-client'\n\n// using socket.io-client\nconst instance = io('http://localhost:6868')\n\n// using native WebSocket API\nconst instance = new Websocket('http://localhost:6868')\n\n// using EventSource (SSE)\nconst instance = new EventSource('http://localhost:6868')\n```\n\nUtilize the `createGateway` method, which creates a wrapper over each protocol, providing a uniform API.\n\n```typescript\nimport { createGateway } from 'gatefetched'\n\nconst gateway = createGateway(instance)\n```\n\n`createGateway` automatically recognizes protocols and returns an object with `listener` and `dispatcher` methods, among other metadata.\n\n```typescript\n// underlying implementation socket.on\nconst channel = gateway.listener('my-channel')\n\n// callback with socket.emit\nconst sendMessage = gateway.dispatcher('send-message')\n\nconsole.info(gateway.adapter.kind) // socket.io\n\n// triggered upon arrival of a response for the 'my-channel' event\nchannel.finished.done.watch(console.log)\n// latest response data\nchannel.$data.watch(console.log)\n\nsendMessage.$sent.watch(console.log)\nsendMessage.$latestParams.watch(console.log)\n\n// dispatch is an effector event;\n// call it manually wherever needed\nsendMessage.dispatch()\n```\n\n- `listener` creates a listening channel (similar to *socket.on*, *ws.onmessage*), adding farfetched functionality.\n- `dispatcher` creates an API for sending messages to another party (*socket.emit*, *ws.send*). Not available in SSE.\n\n### Public API\n\n```typescript\ncreateGateway({\n  from: socket,\n   // Allows intercepting incoming and outgoing operations\n  intercept: console.info,\n  // Specify a set of methods \n  events: ['my-channel', 'send-message'] as const,\n  response: {\n    // All data in incoming transactions will be mapped\n    mapData: ({ payload }) =\u003e payload\n  }\n})\n```\n\nMost of the public API mirrors [farfetched](https://farfetched.pages.dev/tutorial/) – contracts, validators, mapping, etc.\n\nRefer to the farfetched documentation for a better understanding.\n\n```typescript\nimport { zodContract } from '@farfetched/zod'\nimport { declareParams } from '@farfetched/core'\n\nconst messageSent = gateway.listener({\n  name: 'my-channel',\n  response: {\n    // Utilize contracts for validation and typing\n    contract: zodContract(messageSentContract),\n    validate: ({result}) =\u003e result.message.length \u003e 0\n  },\n  initialData: {\n    id: null,\n    message: null\n  },\n  enabled: true,\n  // Listening doesn't start automatically; \n  // manually call messageSend.listen event\n  immediate: false,\n})\n\nconst sendMessage = gateway.dispatcher({\n  name: 'send-message',\n  params: declareParams\u003cstring\u003e(),\n  // Modify instance behavior\n  adapter: {\n    withAck: true\n  },\n  request: {\n    mapParams: (message) =\u003e ({message})\n  }\n})\n```\n\n### Adapter API\n\nYou can also listen for the *connect* and *disconnect* methods using the adapter API.\n\n```typescript\nconsole.info(gateway.adapter.kind) // socket.io\n  \n// Called upon connecting to the other party\ngateway.adapter.bindConnect((msg) =\u003e console.log(msg))\n\n// Called upon disconnection\ngateway.adapter.bindDisconnect(console.info)\n```\n\n### Scoped Gateways\n\nThe library provides an `attachGate` method, accepting the old gateway and any effector gate, returning a new gateway.\nThis gateway launches listeners and dispatchers only when the gate is open.\n\n```tsx\nimport { createGate } from 'effector-react'\nimport { attachGate } from 'gatefetched'\n\n// Use any effector binding\nconst MyGate = createGate()\n\n// Handlers and dispatchers are enabled only when the gate is open\nconst scopedGateway = attachGate(gateway, MyGate)\n\nconst dispatcher = scopedGateway.dispatcher({/* { ... } */})\n  \n// Calls queue up and execute only upon gate opening, \n// which occurs when the component is mounted.\ndispatcher.dispatch()\ndispatcher.dispatch()\n\nconst Parent = () =\u003e {\n  useGate(MyGate)\n  \n  return null\n}\n```\n\nPublic API\n-----\n\n### `createGateway`\n\n#### BaseCreateGatewayParams Interface\n\n- `from`: The protocol instance.\n  - Examples:\n    - `io('localhost')`\n    - `new WebSocket('localhost')`\n    - `new EventSource('localhost')`\n- `intercept` (optional): A callback invoked after any incoming or outgoing operation.\n  - Type: `(InterceptResponse) =\u003e void`\n- `response` (optional):\n  - `mapData` (optional): Serializes data globally. Each incoming message is transformed by this callback.\n\n#### ProtocolGateway Interface\n\n- `instance`: The protocol instance.\n  - Examples:\n    - `io('localhost')`\n- `adapter`: The adapter selected depending on the instance type. Provides deeper control over the provided instance.\n  - Examples:\n    - `IoAdapter`\n    - `SseAdapter`\n- `listener`: Method to create a listener API that listens to messages incoming from the other side.\n\n### `listener`\n\n#### BaseListenerConfig Interface\n\n- `name` (optional): Name of the event to listen. Default is `ANY_WEBSOCKET_EVENT`.\n- `initialData` (optional): Initial data. Default is `null`.\n- `immediate` (optional): If true, starts listening to the channel automatically. If false, manual call through the 'listen' event is required. Default is `true`.\n- `enabled` (optional): Indicates if the listener is enabled. If false, it stops accepting requests. Default is `true`.\n- `response` (optional):\n  - `contract` (optional): Contracts from farfetched. Default is `unknownContract`.\n  - `validate` (optional): Validate function from farfetched. Default is `validValidator`.\n  - `mapData` (optional): Serializes incoming data. Default is `identity`.\n- `adapter` (optional): Adapter options for manual configuration of protocol instance behavior.\n\n#### Listener Interface\n\n- `$enabled`: Indicates if the listener is enabled. If false, it stops accepting requests.\n- `$status`: Listener status. Possible values: 'initial', 'opened'. Default is 'initial'.\n- `$opened`: Store indicating if the listener is opened.\n- `$idle`: Store indicating if the listener is idle.\n- `$closed`: Store indicating if the listener is closed.\n- `$data`: Last data received from the other side. Default is `null`.\n- `listen`: Starts listening to the channel. Automatically triggered when 'immediate' is true.\n- `close`: Stops listening to the channel, changes $status to 'closed'.\n- `done`: Callback triggered upon receiving a message from the other side.\n- `finished`:\n  - `done`: Event triggered when the operation is successful.\n  - `skip`: Event triggered if `$enabled` is false during the call.\n- `failed`: Event triggered in case of any failure.\n- `@@unitShape`: Unit shape method providing a snapshot of the listener state.\n\n### `dispatcher`\n\n\n#### BaseDispatcherConfig Interface\n\n- `name`: Name of the event to send data.\n- `params` (optional): Declaration of parameters for sending data.\n- `enabled` (optional): Indicates if the listener is enabled. If false, it stops accepting requests. Default is `true`.\n- `request` (optional):\n  - `mapParams` (optional): Serializes outgoing params. Default is `identity`.\n- `adapter` (optional): Adapter options for manual configuration of protocol instance behavior.\n\n#### Dispatcher Interface\n\n- `$enabled`: Indicates if the dispatcher is enabled. If false, it stops accepting requests.\n- `$status`: Dispatcher status.\n- `$sent`: Store indicating if data has been sent.\n- `$idle`: Store indicating if the dispatcher is idle.\n- `dispatch`: Sends data to the other side.\n- `done`: Callback triggered immediately after sending data.\n- `finished`:\n  - `done`: Event triggered when the dispatch is successful.\n  - `skip`: Event triggered if `$enabled` is false during the call.\n- `$latestParams`: Parameters at the time of the last call.\n- `@@unitShape`: Unit shape method providing a snapshot of the dispatcher state.\n\n\nExamples\n-----\nTo better grasp its functionality, refer to the [examples](https://github.com/gearonix/gatefetched/tree/master/sample/).\n\n\n\n*@grnx*\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgearonix%2Fgatefetched","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgearonix%2Fgatefetched","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgearonix%2Fgatefetched/lists"}