{"id":18821362,"url":"https://github.com/borderless/context","last_synced_at":"2025-04-14T00:32:36.490Z","repository":{"id":46907463,"uuid":"246739897","full_name":"borderless/context","owner":"borderless","description":"Tiny, type-safe, JavaScript-native `context` implementation","archived":false,"fork":false,"pushed_at":"2023-12-12T06:17:51.000Z","size":131,"stargazers_count":18,"open_issues_count":0,"forks_count":2,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-10-13T15:12:04.509Z","etag":null,"topics":["context","context-api","javascript","types","typescript"],"latest_commit_sha":null,"homepage":null,"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/borderless.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}},"created_at":"2020-03-12T04:02:04.000Z","updated_at":"2022-05-07T08:07:12.000Z","dependencies_parsed_at":"2022-09-12T07:24:34.523Z","dependency_job_id":null,"html_url":"https://github.com/borderless/context","commit_stats":null,"previous_names":["borderlesslabs/context"],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/borderless%2Fcontext","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/borderless%2Fcontext/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/borderless%2Fcontext/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/borderless%2Fcontext/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/borderless","download_url":"https://codeload.github.com/borderless/context/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223612915,"owners_count":17173632,"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":["context","context-api","javascript","types","typescript"],"created_at":"2024-11-08T00:39:41.860Z","updated_at":"2024-11-08T00:39:42.811Z","avatar_url":"https://github.com/borderless.png","language":"TypeScript","readme":"# Context\n\n[![NPM version][npm-image]][npm-url]\n[![NPM downloads][downloads-image]][downloads-url]\n[![Build status][travis-image]][travis-url]\n[![Test coverage][coveralls-image]][coveralls-url]\n[![Bundle size][bundlephobia-image]][bundlephobia-url]\n\n\u003e Tiny, type-safe, JavaScript-native `context` implementation.\n\n**Why?** Working on a project across browsers, workers and node.js requires different implementations on the same thing, e.g. `fetch` vs `require('http')`. Go's [`context`](https://blog.golang.org/context) package provides a nice abstraction to bring all the interfaces together. By implementing a JavaScript first variation, we can achieve the same benefits.\n\n## Installation\n\n```sh\nnpm install @borderless/context --save\n```\n\n## Usage\n\nContext values are unidirectional.\n\n```ts\nimport { background, withValue } from \"@borderless/context\";\n\n// Extend the default `background` context with a value.\nconst ctx = withValue(background, \"test\", \"test\");\n\nctx.value(\"test\"); //=\u003e \"test\"\nbackground.value(\"test\"); // Invalid.\n```\n\n### Abort\n\nUse `withAbort` to support cancellation of execution in your application.\n\n```ts\nimport { withAbort } from \"@borderless/context\";\n\nconst [ctx, abort] = withAbort(parentCtx);\n\nonUserCancelsTask(() =\u003e abort(new Error(\"User canceled task\")));\n```\n\n### Timeout\n\nUse `withTimeout` when you want to abort after a specific duration:\n\n```ts\nimport { withTimeout } from \"@borderless/context\";\n\nconst [ctx, abort] = withTimeout(parentCtx, 5000); // You can still `abort` manually.\n```\n\n### Using Abort\n\nThe `useAbort` method will return a `Promise` which rejects when aborted.\n\n```ts\nimport { useAbort } from \"@borderless/context\";\n\n// Race between the abort signal and making an ajax request.\nPromise.race([useAbort(ctx), ajax(\"http://example.com\")]);\n```\n\n## Example\n\n### Abort Controller\n\nUse `context` with other abort signals, such as `fetch`.\n\n```ts\nimport { useAbort, Context } from \"@borderless/context\";\n\nfunction request(ctx: Context\u003c{}\u003e, url: string) {\n  const controller = new AbortController();\n  withAbort(ctx).catch(e =\u003e controller.abort());\n  return fetch(url, { signal: controller.signal });\n}\n```\n\n### Application Tracing\n\nDistributed application tracing is a natural example for `context`:\n\n```ts\nimport { Context, withValue } from \"@borderless/context\";\n\n// Use a unique symbol for tracing.\nconst spanKey = Symbol(\"span\");\n\n// Start a new span, and automatically use \"parent\" span.\nexport function startSpan\u003cT extends { [spanKey]?: Span }\u003e(\n  ctx: Context\u003cT\u003e,\n  name: string\n): [Span, Context\u003cT \u0026 { [spanKey]: Span }\u003e] {\n  const span = tracer.startSpan(name, {\n    childOf: ctx.value(spanKey)\n  });\n\n  return [span, withValue(ctx, spanKey, span)];\n}\n\n// server.js\nexport async function app(req, next) {\n  const [span, ctx] = startSpan(req.ctx, \"app\");\n\n  req.ctx = ctx;\n\n  try {\n    return await next();\n  } finally {\n    span.finish();\n  }\n}\n\n// middleware.js\nexport async function middleware(req, next) {\n  const [span, ctx] = startSpan(req.ctx, \"middleware\");\n\n  req.ctx = ctx;\n\n  try {\n    return await next();\n  } finally {\n    span.finish();\n  }\n}\n```\n\n### Libraries\n\nJavaScript and TypeScript libraries can accept a typed `context` argument.\n\n```ts\nimport { Context, withValue } from \"@borderless/context\";\n\nexport function withSentry\u003cT\u003e(ctx: Context\u003cT\u003e) {\n  return withValue(ctx, sentryKey, someSentryImplementation);\n}\n\nexport function captureException(\n  ctx: Context\u003c{ [sentryKey]: SomeSentryImplementation }\u003e,\n  error: Error\n) {\n  return ctx.value(sentryKey).captureException(error);\n}\n```\n\n## License\n\nMIT\n\n[npm-image]: https://img.shields.io/npm/v/@borderless/context.svg?style=flat\n[npm-url]: https://npmjs.org/package/@borderless/context\n[downloads-image]: https://img.shields.io/npm/dm/@borderless/context.svg?style=flat\n[downloads-url]: https://npmjs.org/package/@borderless/context\n[travis-image]: https://img.shields.io/travis/BorderlessLabs/context.svg?style=flat\n[travis-url]: https://travis-ci.org/BorderlessLabs/context\n[coveralls-image]: https://img.shields.io/coveralls/BorderlessLabs/context.svg?style=flat\n[coveralls-url]: https://coveralls.io/r/BorderlessLabs/context?branch=master\n[bundlephobia-image]: https://img.shields.io/bundlephobia/minzip/@borderless/context.svg\n[bundlephobia-url]: https://bundlephobia.com/result?p=@borderless/context\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fborderless%2Fcontext","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fborderless%2Fcontext","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fborderless%2Fcontext/lists"}