{"_id":"@alienfishconsulting/core-context","_rev":"4-96e281abca9ae748b117aad1d26e39d7","name":"@alienfishconsulting/core-context","dist-tags":{"latest":"1.1.0"},"versions":{"1.0.1":{"name":"@alienfishconsulting/core-context","version":"1.0.1","keywords":["async-local-storage","async-hooks","nodejs","typescript","context","express","request-context","functional"],"author":{"url":"https://github.com/alienfishconsulting","name":"Terry \"Lee\" Allen, Jr","email":"lee@alienfishconsulting.com"},"license":"MIT","_id":"@alienfishconsulting/core-context@1.0.1","maintainers":[{"name":"leeallenaf","email":"lee@alienfishconsulting.com"}],"homepage":"https://github.com/alienfish-consulting/core/tree/main/packages/context#readme","bugs":{"url":"https://github.com/alienfish-consulting/core/issues"},"dist":{"shasum":"15283441ef03603bcf430e61ac5af934e60121f8","tarball":"https://registry.npmjs.org/@alienfishconsulting/core-context/-/core-context-1.0.1.tgz","fileCount":7,"integrity":"sha512-A8QLglD2v9zITQ/hAW/0l+wueC5KF+levKF2C+73T0Y2L/YY0levWrt25VMPN/efOGYa6HOuvjT8nxbvC0iJxQ==","signatures":[{"sig":"MEUCIQC/WW+jJshP5jEzNdDuonM+46M8qgFgr5F+sci/o68UygIgVNNDQlK4/H2nqRFCqo7PI5jzGlbSZnHixIVdx3XPuYA=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":24061},"main":"./dist/index.js","type":"module","_from":"file:alienfishconsulting-core-context-1.0.1.tgz","types":"./dist/index.d.ts","module":"./dist/index.js","engines":{"node":">=18.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","default":"./dist/index.js","require":"./dist/index.cjs","development":"./src/index.ts"},"./package.json":"./package.json"},"scripts":{"lint":"eslint src --ext .ts","test":"vitest run","build":"tsup","test:coverage":"vitest run --coverage"},"_npmUser":{"name":"leeallenaf","email":"lee@alienfishconsulting.com"},"_resolved":"/private/var/folders/tc/5mp8jdb51tsdw8n3xzwpwr8r0000gp/T/1dcc82de4cdf063a0eec9780804626bb/alienfishconsulting-core-context-1.0.1.tgz","_integrity":"sha512-A8QLglD2v9zITQ/hAW/0l+wueC5KF+levKF2C+73T0Y2L/YY0levWrt25VMPN/efOGYa6HOuvjT8nxbvC0iJxQ==","repository":{"url":"git+https://github.com/alienfish-consulting/core.git","type":"git","directory":"packages/core-context"},"_npmVersion":"10.9.2","description":"Strongly typed, functional AsyncLocalStorage wrapper with context propagation for Node.js and Express apps","directories":{},"sideEffects":false,"_nodeVersion":"22.14.0","dependencies":{"@paralleldrive/cuid2":"^2.2.2"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"eslint":"^8.56.0","typescript":"^5.3.3"},"_npmOperationalInternal":{"tmp":"tmp/core-context_1.0.1_1743700614878_0.5778902619444328","host":"s3://npm-registry-packages-npm-production"}},"1.0.2":{"name":"@alienfishconsulting/core-context","version":"1.0.2","keywords":["async-local-storage","async-hooks","nodejs","typescript","context","express","request-context","functional"],"author":{"url":"https://github.com/alienfishconsulting","name":"Terry \"Lee\" Allen, Jr","email":"lee@alienfishconsulting.com"},"license":"MIT","_id":"@alienfishconsulting/core-context@1.0.2","maintainers":[{"name":"leeallenaf","email":"lee@alienfishconsulting.com"}],"homepage":"https://github.com/alienfish-consulting/core/tree/main/packages/context#readme","bugs":{"url":"https://github.com/alienfish-consulting/core/issues"},"dist":{"shasum":"e03b694f00bc1ba4f29cd9b96d0b34fe3656f579","tarball":"https://registry.npmjs.org/@alienfishconsulting/core-context/-/core-context-1.0.2.tgz","fileCount":7,"integrity":"sha512-hJ+Q+++diG0fijFsWOwluswTOghYQk1iWQrFXTJyD24BKJo7vORJIBiXM0sCaEZdaMHdvvq8fgWQ7NF50f/67g==","signatures":[{"sig":"MEUCICEKwDvaOxDGnwu5y/ljV5hx3H2pjPwaBCrAsT6SY/dXAiEAhrS6sO9gTGsB9rTZkr/G1LuiTXBgDzxBP9s+dFjfTqg=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":24011},"main":"./dist/index.js","type":"module","_from":"file:alienfishconsulting-core-context-1.0.2.tgz","types":"./dist/index.d.ts","module":"./dist/index.js","engines":{"node":">=18.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","default":"./dist/index.js","require":"./dist/index.cjs","development":"./src/index.ts"},"./package.json":"./package.json"},"scripts":{"lint":"eslint src --ext .ts","test":"vitest","build":"tsup"},"_npmUser":{"name":"leeallenaf","email":"lee@alienfishconsulting.com"},"_resolved":"/private/var/folders/tc/5mp8jdb51tsdw8n3xzwpwr8r0000gp/T/e464ed3ccd3eba734251b29ae8e4f2ec/alienfishconsulting-core-context-1.0.2.tgz","_integrity":"sha512-hJ+Q+++diG0fijFsWOwluswTOghYQk1iWQrFXTJyD24BKJo7vORJIBiXM0sCaEZdaMHdvvq8fgWQ7NF50f/67g==","repository":{"url":"git+https://github.com/alienfish-consulting/core.git","type":"git","directory":"packages/core-context"},"_npmVersion":"10.9.2","description":"Strongly typed, functional AsyncLocalStorage wrapper with context propagation for Node.js and Express apps","directories":{},"sideEffects":false,"_nodeVersion":"22.14.0","dependencies":{"@paralleldrive/cuid2":"^2.2.2"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"eslint":"^8.56.0","typescript":"^5.3.3"},"_npmOperationalInternal":{"tmp":"tmp/core-context_1.0.2_1743708312676_0.9663514155258879","host":"s3://npm-registry-packages-npm-production"}},"1.0.3":{"name":"@alienfishconsulting/core-context","version":"1.0.3","keywords":["async-local-storage","async-hooks","nodejs","typescript","context","express","request-context","functional"],"author":{"url":"https://github.com/alienfishconsulting","name":"Terry \"Lee\" Allen, Jr","email":"lee@alienfishconsulting.com"},"license":"MIT","_id":"@alienfishconsulting/core-context@1.0.3","maintainers":[{"name":"leeallenaf","email":"lee@alienfishconsulting.com"}],"homepage":"https://github.com/alienfish-consulting/core/tree/main/packages/context#readme","bugs":{"url":"https://github.com/alienfish-consulting/core/issues"},"dist":{"shasum":"03192b3841335a062e5305e6bdcf4ff7023115a5","tarball":"https://registry.npmjs.org/@alienfishconsulting/core-context/-/core-context-1.0.3.tgz","fileCount":21,"integrity":"sha512-EAWuCgth+nctsVhjThM62fdBr0Xp37V442kuJI9csNiJFtmuqf3GGGb3Fn0WCLIaOqVMtYZveWqvIeuajGPDPg==","signatures":[{"sig":"MEUCIGqXGmgZ3Gjlm9krq7Wd+h2AUV3iswIMqmx7yFgFYQUdAiEAu47EctZOCpZCXfgwkAkTNFFOgcT0LKjgs2y8Dy5MKsk=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":34428},"main":"./dist/index.js","type":"module","_from":"file:alienfishconsulting-core-context-1.0.3.tgz","types":"./dist/index.d.ts","module":"./dist/index.js","engines":{"node":">=18.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","default":"./dist/index.js","require":"./dist/index.cjs","development":"./src/index.ts"},"./package.json":"./package.json"},"scripts":{"lint":"eslint src --ext .ts","test":"vitest run --coverage","build":"tsup"},"_npmUser":{"name":"leeallenaf","email":"lee@alienfishconsulting.com"},"_resolved":"/tmp/d9b22df6cc7a938e6dd7fb23024e55d1/alienfishconsulting-core-context-1.0.3.tgz","_integrity":"sha512-EAWuCgth+nctsVhjThM62fdBr0Xp37V442kuJI9csNiJFtmuqf3GGGb3Fn0WCLIaOqVMtYZveWqvIeuajGPDPg==","repository":{"url":"git+https://github.com/alienfish-consulting/core.git","type":"git","directory":"packages/core-context"},"_npmVersion":"10.8.2","description":"Strongly typed, functional AsyncLocalStorage wrapper with context propagation for Node.js and Express apps","directories":{},"sideEffects":false,"_nodeVersion":"20.19.0","dependencies":{"@paralleldrive/cuid2":"^2.2.2"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"eslint":"^8.56.0","typescript":"^5.3.3"},"_npmOperationalInternal":{"tmp":"tmp/core-context_1.0.3_1743720225872_0.5223167341108079","host":"s3://npm-registry-packages-npm-production"}},"1.1.0":{"name":"@alienfishconsulting/core-context","version":"1.1.0","description":"Strongly typed, functional AsyncLocalStorage wrapper with context propagation for Node.js and Express apps","author":{"name":"Terry \"Lee\" Allen, Jr","email":"lee@alienfishconsulting.com","url":"https://github.com/alienfishconsulting"},"keywords":["async-local-storage","async-hooks","nodejs","typescript","context","express","request-context","functional"],"publishConfig":{"access":"public"},"repository":{"type":"git","url":"git+https://github.com/alienfish-consulting/core.git","directory":"packages/core-context"},"bugs":{"url":"https://github.com/alienfish-consulting/core/issues"},"homepage":"https://github.com/alienfish-consulting/core/tree/main/packages/core-context#readme","type":"module","sideEffects":false,"engines":{"node":">=18.0.0"},"main":"./dist/index.js","module":"./dist/index.js","types":"./dist/index.d.ts","exports":{"./package.json":"./package.json",".":{"development":"./src/index.ts","types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs","default":"./dist/index.js"}},"dependencies":{"@paralleldrive/cuid2":"^2.2.2"},"license":"MIT","scripts":{"build":"tsup","test":"vitest run --coverage","lint":"eslint src --ext .ts"},"_id":"@alienfishconsulting/core-context@1.1.0","_integrity":"sha512-xbyn2nLegPkR3uT7TY5PvoTtwfCWnfHz4yVOHWShoJWO3aNfVcMjKakhwNCxEjUM1rVn2gs5kL6dR9HGLhz1JA==","_resolved":"/tmp/f18402736bff31e25a93136b774fe31d/alienfishconsulting-core-context-1.1.0.tgz","_from":"file:alienfishconsulting-core-context-1.1.0.tgz","_nodeVersion":"22.14.0","_npmVersion":"10.9.2","dist":{"integrity":"sha512-xbyn2nLegPkR3uT7TY5PvoTtwfCWnfHz4yVOHWShoJWO3aNfVcMjKakhwNCxEjUM1rVn2gs5kL6dR9HGLhz1JA==","shasum":"5715872006855193f699229478abb1dc3eb2c494","tarball":"https://registry.npmjs.org/@alienfishconsulting/core-context/-/core-context-1.1.0.tgz","fileCount":3,"unpackedSize":6724,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIGZcJ7WlfLVtuI4iM//U6kOUfCW937rqS6djIxAThOfXAiEAsWv4ecVzgVGPBJgE7zh2P8D3GzrM2+7Q4ibr+x8tW74="}]},"_npmUser":{"name":"leeallenaf","email":"lee@alienfishconsulting.com"},"directories":{},"maintainers":[{"name":"leeallenaf","email":"lee@alienfishconsulting.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/core-context_1.1.0_1744930410992_0.22023684198753846"},"_hasShrinkwrap":false}},"time":{"created":"2025-04-03T17:16:54.774Z","modified":"2025-04-17T22:53:31.354Z","1.0.1":"2025-04-03T17:16:55.050Z","1.0.2":"2025-04-03T19:25:12.872Z","1.0.3":"2025-04-03T22:43:46.059Z","1.1.0":"2025-04-17T22:53:31.166Z"},"bugs":{"url":"https://github.com/alienfish-consulting/core/issues"},"author":{"name":"Terry \"Lee\" Allen, Jr","email":"lee@alienfishconsulting.com","url":"https://github.com/alienfishconsulting"},"license":"MIT","homepage":"https://github.com/alienfish-consulting/core/tree/main/packages/core-context#readme","keywords":["async-local-storage","async-hooks","nodejs","typescript","context","express","request-context","functional"],"repository":{"type":"git","url":"git+https://github.com/alienfish-consulting/core.git","directory":"packages/core-context"},"description":"Strongly typed, functional AsyncLocalStorage wrapper with context propagation for Node.js and Express apps","maintainers":[{"name":"leeallenaf","email":"lee@alienfishconsulting.com"}],"readme":"# @alienfishconsulting/core-context\n\n[![npm version](https://img.shields.io/npm/v/@alienfishconsulting/core-context.svg)](https://www.npmjs.com/package/@alienfishconsulting/core-context)\n[![License](https://img.shields.io/npm/l/@alienfishconsulting/core-context.svg)](./LICENSE)\n![Node Version](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg)\n\n![CI](https://github.com/alienfish-consulting/core/actions/workflows/ci.yml/badge.svg?branch=development)\n![codecov](https://codecov.io/gh/alienfish-consulting/core/branch/main/graph/badge.svg)\n\n> Strongly typed, functional AsyncLocalStorage wrapper for managing request-scoped context in Node.js applications.\n\n---\n\n## โœจ Features\n\n- ๐Ÿ”’ Immutable `RequestContext` model for tracing and auditing\n- ๐Ÿง  Type-safe accessors for contextual fields (e.g., `requestId`, `userId`)\n- ๐Ÿ” Async context propagation across call stacks\n- ๐Ÿ“ฅ Header integration for tracing across services\n- ๐Ÿงช CI-enforced test coverage with Vitest & Nx\n- โš™๏ธ Framework-agnostic (no Express dependency)\n\n---\n\n## ๐Ÿ“ฆ Installation\n\n```bash\n pnpm add @alienfishconsulting/core-context\n```\n\nRequires Node.js โ‰ฅ18.\n\n## ๐Ÿงฑ Context Model\nThe RequestContext defines a consistent schema across async boundaries:\n\n```ts\ninterface RequestContext {\n requestId: string;\n correlationId: string;\n userId?: string;\n accountId?: string;\n transactionId?: string;\n}\n```\n\nAll fields are immutable and meant to persist across the request lifecycle.\n\n## ๐Ÿš€ Quick Start\n\n```ts\nimport {\n initWithDefaultContext,\n getContext,\n getContextField,\n runWithContext\n} from '@alienfishconsulting/core-context';\n\ninitWithDefaultContext(() => {\n const ctx = getContext();\n console.log('Request ID:', ctx?.requestId);\n});\n```\n\nOr use a custom context:\n\n```ts\nconst context = {\n requestId: 'abc123',\n correlationId: 'xyz456',\n};\n\nrunWithContext(context, () => {\n // context is now available inside this function\n});\n```\n\n## ๐Ÿ“ฅ Working with HTTP Headers\n```ts\nimport { extractContextFromHeaders, updateContextFromHeaders } from '@alienfishconsulting/core-context';\n\nconst headers = {\n 'x-request-id': 'abc123',\n 'x-user-id': 'user789',\n};\n\nupdateContextFromHeaders(headers);\n\n// Later...\nconst userId = getContextField('userId');\n```\n\n### ๐Ÿ”ง API Overview\n\n| Function |Description |\n|--|--|\n| `runWithContext(ctx, fn)` |\tRuns fn with the given context |\n| `initWithDefaultContext(fn)` |\tAuto-generates requestId/correlationId |\n| `getContext(fallback?: boolean)` |\tRetrieves the current context |\n| `assertContext()` |\tReturns context or throws if missing |\n| `bind(fn)` |\tReturns a function bound to the current context |\n| `extractContextFromHeaders(headers)` |\tBuilds a context from header values |\n| `updateContextFromHeaders(headers)`\t| Extracts + applies context to storage |\n| `getContextField(key)` |\tRetrieves a specific field from the context |\n\n\n## โœ… Best Practices\n\n- Always call runWithContext() at the top level of async workflows\n\n- Use bind() when passing callbacks to preserve context\n\n- Avoid mutating context values โ€” treat them as read-only\n\n- Integrate context extraction in your HTTP layer (e.g., middleware or handlers)\n\n## ๐Ÿงช Testing\nThis package is managed with Nx and uses Vitest for testing.\n\n```bash\npnpm nx test core-context\n```\n\n- โœ… 80% coverage required\n\n- ๐ŸŽฏ 100% coverage target\n\n- CI will fail if coverage is insufficient\n\n## ๐Ÿ›  Project Structure\n```bash\n core-context/\n โ”œโ”€โ”€ src/\n โ”‚ โ”œโ”€โ”€ accessors.ts # Context getters and safety checks\n โ”‚ โ”œโ”€โ”€ headers.ts # HTTP header integration\n โ”‚ โ”œโ”€โ”€ lifecycle.ts # runWithContext(), bind(), initWithDefaultContext()\n โ”‚ โ”œโ”€โ”€ storage.ts # Shared AsyncLocalStorage instance\n โ”‚ โ””โ”€โ”€ types.ts # RequestContext schema\n```\n\n## ๐Ÿงฉ Related Projects\nThis package is part of the @alienfishconsulting/core monorepo โ€” a collection of modular, enterprise-grade TypeScript utilities.\n\n# ๐Ÿ“„ License\n\nMIT \n\nยฉ Terry \"Lee\" Allen, Jr\n\n","readmeFilename":"README.md"}