Esinx Async Context

https://www.npmjs.com/package/@esinx/async-context
Admin
Esinx Async Context is a TypeScript library for async context management using a React-like context...
Tokens:10,273
Snippets:129
Trust Score:9.6
Update:5 months ago
Show doc for...
Tokens:
Raw
### Install @esinx/async-context

Source: https://www.npmjs.com/package/%40esinx/async-context?activeTab=dependents

Install the library using npm, yarn, or pnpm.

```bash
npm install @esinx/async-context
# or
yarn add @esinx/async-context
# or
pnpm add @esinx/async-context
```

--------------------------------

### Install async-context

Source: https://www.npmjs.com/package/%40esinx/async-context?activeTab=dependencies

Install the async-context library using npm, yarn, or pnpm.

```bash
npm install async-context
# or
yarn add async-context
# or
pnpm add async-context
```

--------------------------------

### use

Source: https://www.npmjs.com/package/%40esinx/async-context

Gets the current value from a context handle.

```APIDOC
## use<T>(handle: ContextHandle<T>): T

Gets the current value from a context handle.

### Parameters
- **handle** (ContextHandle<T>) - The context handle to retrieve the value from.

### Returns
- **T** - The current value of the context.

### Example
```javascript
const currentUser = use(userContext)
```
```

--------------------------------

### Async Context Example: Without Async Context

Source: https://www.npmjs.com/package/%40esinx/async-context?activeTab=dependents

Demonstrates the traditional, more verbose way of passing context through multiple async functions using explicit parameters.

```typescript
// Without async context - tedious parameter passing
async function handleRequest(userId: string, requestId: string) {
	const user = await fetchUser(userId, requestId)
	const data = await processData(user, requestId)
	await saveResult(data, userId, requestId)
}

async function fetchUser(userId: string, requestId: string) {
	console.log(`[${requestId}] Fetching user ${userId}`)
	// ... fetch logic
}

async function processData(user: User, requestId: string) {
	console.log(`[${requestId}] Processing data for ${user.id}`)
	// ... processing logic
}
```

--------------------------------

### use

Source: https://www.npmjs.com/package/%40esinx/async-context?activeTab=code

Gets the current value from a context handle. This is a standalone function that can be used anywhere within the scope where the context is active.

```APIDOC
## use<T>(handle: ContextHandle<T>): T

### Description
Gets the current value from a context handle.

### Parameters
- **handle** (ContextHandle<T>) - The context handle to retrieve the value from.

### Returns
- **T** - The current value of the context.

### Example
```typescript
const currentUser = use(userContext)
```
```

--------------------------------

### use

Source: https://www.npmjs.com/package/%40esinx/async-context?activeTab=readme

A standalone function to get the current value from a context handle. It provides a convenient way to access context values directly within asynchronous functions.

```APIDOC
## use<T>(handle: ContextHandle<T>): T

Gets the current value from a context handle.

### Parameters
- **handle** (ContextHandle<T>) - The context handle from which to retrieve the value.

### Returns
- **T** - The current value of the context.

### Example
```javascript
const currentUser = use(userContext)
```
```

--------------------------------

### createContext

Source: https://www.npmjs.com/package/%40esinx/async-context

Creates a new context handle with an initial or default value.

```APIDOC
## createContext<T>(initialValue: T): ContextHandle<T>

Creates a new context handle with an initial/default value.

### Parameters
- **initialValue** (T) - The default value for the context.

### Returns
- **ContextHandle<T>** - An object with `run` and `use` methods.

### Example
```javascript
const stringContext = createContext<string>('default')
const numberContext = createContext<number>(0)
const userContext = createContext<User | null>(null)
```
```

--------------------------------

### Async Context vs. Traditional Parameter Passing

Source: https://www.npmjs.com/package/%40esinx/async-context

Illustrates the verbosity of passing context manually through async functions compared to the implicit management provided by async context.

```typescript
// Without async context - tedious parameter passing
async function handleRequest(userId: string, requestId: string) {
	const user = await fetchUser(userId, requestId)
	const data = await processData(user, requestId)
	await saveResult(data, userId, requestId)
}

async function fetchUser(userId: string, requestId: string) {
	console.log(`[${requestId}] Fetching user ${userId}`)
	// ... fetch logic
}

async function processData(user: User, requestId: string) {
	console.log(`[${requestId}] Processing data for ${user.id}`)
	// ... processing logic
}
```

```typescript
// With async context - clean and maintainable
const userContext = createContext<User | null>(null)
const requestContext = createContext<string>('')

async function handleRequest(userId: string, requestId: string) {
	await requestContext.run(requestId, async () => {
		const user = await fetchUser(userId)
		await userContext.run(user, async () => {
			const data = await processData()
			await saveResult(data)
		})
	})
}

async function fetchUser(userId: string) {
	const requestId = use(requestContext)
	console.log(`[${requestId}] Fetching user ${userId}`)
	// ... fetch logic
}

async function processData() {
	const user = use(userContext)
	const requestId = use(requestContext)
	console.log(`[${requestId}] Processing data for ${user.id}`)
	// ... processing logic
}
```

--------------------------------

### runWithContext

Source: https://www.npmjs.com/package/%40esinx/async-context?activeTab=dependencies

Creates a reusable function that, when called, will execute operations with a specific context value pre-applied. This is useful for setting up common contexts like user roles.

```APIDOC
## runWithContext<T>(handle: ContextHandle<T>, value: T)

### Description
Creates a reusable function that runs operations with a specific context value.

### Parameters
- **handle** (ContextHandle<T>) - The context handle to associate the value with.
- **value** (T) - The value to be used when the returned function is invoked.

### Returns
- A function that takes an async callback and runs it with the specified context value.
```

--------------------------------

### ContextHandle Methods

Source: https://www.npmjs.com/package/%40esinx/async-context

The object returned by `createContext` provides methods to manage and access context values.

```APIDOC
## ContextHandle<T>

The object returned by `createContext` with the following methods:

### `run<Result>(value: T, fn: () => Promise<Result>): Promise<Result>`

Runs an async function with a specific context value.

#### Parameters
- **value** (T) - The value to set for the context within the `fn` scope.
- **fn** (() => Promise<Result>) - The async function to execute with the context.

#### Returns
- **Promise<Result>** - The result of the `fn` execution.

#### Example
```javascript
const result = await handle.run('new-value', async () => {
	// Context is 'new-value' within this scope
	return await someAsyncOperation()
})
```

### `use(): T`

Gets the current context value (same as the standalone `use` function).

#### Returns
- **T** - The current context value.

#### Example
```javascript
const currentValue = handle.use()
```
```

--------------------------------

### createContext

Source: https://www.npmjs.com/package/@esinx/async-context

Creates a new context handle with an initial or default value. This handle can then be used to manage and access context-specific data.

```APIDOC
## createContext<T>(initialValue: T): ContextHandle<T>

Creates a new context handle with an initial/default value.

### Parameters
- **initialValue** (T) - The default value for the context.

### Returns
- **ContextHandle<T>** - An object with methods to manage the context.

### Example
```typescript
const stringContext = createContext<string>('default')
const numberContext = createContext<number>(0)
```
```

--------------------------------

### ContextHandle.use

Source: https://www.npmjs.com/package/%40esinx/async-context?activeTab=readme

Retrieves the current value of the context associated with this handle. This is equivalent to using the standalone `use` function.

```APIDOC
## handle.use(): T

Gets the current context value (same as the standalone `use` function).

### Returns
- **T** - The current value of the context.

### Example
```javascript
const currentValue = handle.use()
```
```

--------------------------------

### ContextHandle.use

Source: https://www.npmjs.com/package/%40esinx/async-context?activeTab=dependencies

Retrieves the current value of the context associated with this handle. This is equivalent to calling the standalone `use` function.

```APIDOC
## handle.use(): T

### Description
Gets the current context value.

### Returns
- **T** - The current value of the context.
```

--------------------------------

### ContextHandle Methods

Source: https://www.npmjs.com/package/@esinx/async-context

The ContextHandle object provides methods to interact with the created context, including running functions within a specific context value and retrieving the current value.

```APIDOC
## ContextHandle<T>

The object returned by `createContext` with the following methods:

### `run<Result>(value: T, fn: () => Promise<Result>): Promise<Result>`

Runs an asynchronous function with a specific context value. The provided value will be available within the scope of the `fn` function.

#### Parameters
- **value** (T) - The value to set for the context within the `fn` scope.
- **fn** (() => Promise<Result>) - The asynchronous function to execute with the context.

#### Returns
- **Promise<Result>** - A promise that resolves with the result of the `fn` execution.

#### Example
```typescript
const result = await handle.run('new-value', async () => {
	// Context is 'new-value' within this scope
	return await someAsyncOperation()
})
```

### `use(): T`

Gets the current context value. This is a convenience method on the handle itself, equivalent to the standalone `use` function.

#### Returns
- **T** - The current value of the context.

#### Example
```typescript
const currentValue = handle.use()
```
```

--------------------------------

### createContext

Source: https://www.npmjs.com/package/%40esinx/async-context?activeTab=versions

Creates a new context handle with an initial or default value. This handle can then be used to manage and access context values within asynchronous operations.

```APIDOC
## createContext<T>(initialValue: T): ContextHandle<T>

Creates a new context handle with an initial/default value.

### Parameters
- **initialValue** (T) - The default value for the context.

### Returns
- **ContextHandle<T>** - An object with methods to manage the context.

### Example
```typescript
const stringContext = createContext<string>('default')
const numberContext = createContext<number>(0)
const userContext = createContext<User | null>(null)
```
```

--------------------------------

### createContext

Source: https://www.npmjs.com/package/%40esinx/async-context?activeTab=code

Creates a new context handle with an initial or default value. This handle can then be used to manage and access context values within asynchronous operations.

```APIDOC
## createContext<T>(initialValue: T): ContextHandle<T>

### Description
Creates a new context handle with an initial/default value.

### Parameters
- **initialValue** (T) - The default value for the context.

### Returns
- **ContextHandle<T>** - An object with methods to manage the context.

### Example
```typescript
const stringContext = createContext<string>('default')
const numberContext = createContext<number>(0)
const userContext = createContext<User | null>(null)
```
```

--------------------------------

### ContextHandle.run

Source: https://www.npmjs.com/package/%40esinx/async-context?activeTab=readme

Runs an asynchronous function with a specific context value. Any asynchronous operations within the provided function `fn` will have access to this context value.

```APIDOC
## handle.run<Result>(value: T, fn: () => Promise<Result>): Promise<Result>

Runs an async function with a specific context value.

### Parameters
- **value** (T) - The value to set for the context within the scope of `fn`.
- **fn** (() => Promise<Result>) - The asynchronous function to execute with the context.

### Returns
- **Promise<Result>** - A promise that resolves with the result of the `fn` execution.

### Example
```javascript
const result = await handle.run('new-value', async () => {
	// Context is 'new-value' within this scope
	return await someAsyncOperation()
})
```
```

--------------------------------

### runWithContext

Source: https://www.npmjs.com/package/%40esinx/async-context?activeTab=readme

Creates a reusable function that executes operations with a specific context value pre-applied. This is useful for creating specialized functions that always run within a defined context.

```APIDOC
## runWithContext<T>(handle: ContextHandle<T>, value: T)

Creates a reusable function that runs operations with a specific context value.

### Parameters
- **handle** (ContextHandle<T>) - The context handle to associate the value with.
- **value** (T) - The value to be used when the returned function is invoked.

### Returns
- A function that takes an async callback and runs it with the specified context value.

### Example
```javascript
const runAsAdmin = runWithContext(userContext, adminUser)

const result = await runAsAdmin(async () => {
	// This runs with adminUser as the context
	return await performAdminOperation()
})
```
```

--------------------------------

### ContextHandle.run

Source: https://www.npmjs.com/package/%40esinx/async-context?activeTab=dependencies

Runs an asynchronous function within a specific context value. Any `use` calls within this function's scope will retrieve the provided `value`.

```APIDOC
## handle.run<Result>(value: T, fn: () => Promise<Result>): Promise<Result>

### Description
Runs an async function with a specific context value.

### Parameters
- **value** (T) - The value to set for the context within the `fn` scope.
- **fn** (() => Promise<Result>) - The asynchronous function to execute with the context.

### Returns
- **Promise<Result>** - A promise that resolves with the result of the `fn` execution.
```

--------------------------------

### runWithContext

Source: https://www.npmjs.com/package/%40esinx/async-context

Creates a reusable function that runs operations with a specific context value.

```APIDOC
## runWithContext<T>(handle: ContextHandle<T>, value: T)

Creates a reusable function that runs operations with a specific context value.

### Parameters
- **handle** (ContextHandle<T>) - The context handle to use.
- **value** (T) - The value to set for the context when the returned function is called.

### Returns
- **Function** - A function that takes an async callback and runs it with the specified context value.

### Example
```javascript
const runAsAdmin = runWithContext(userContext, adminUser)

const result = await runAsAdmin(async () => {
	// This runs with adminUser as the context
	return await performAdminOperation()
})
```
```

--------------------------------

### runWithContext

Source: https://www.npmjs.com/package/%40esinx/async-context?activeTab=versions

Creates a reusable function that runs operations with a specific context value. This is useful for creating pre-configured context runners.

```APIDOC
## runWithContext<T>(handle: ContextHandle<T>, value: T)

Creates a reusable function that runs operations with a specific context value.

### Parameters
- **handle** (ContextHandle<T>) - The context handle to use.
- **value** (T) - The value to set for the context when the returned function is called.

### Returns
- **Function** - A function that takes an async callback and runs it with the specified context value.

### Example
```typescript
const runAsAdmin = runWithContext(userContext, adminUser)

const result = await runAsAdmin(async () => {
	// This runs with adminUser as the context
	return await performAdminOperation()
})
```
```

--------------------------------

### runWithContext

Source: https://www.npmjs.com/package/%40esinx/async-context?activeTab=code

Creates a reusable function that runs operations with a specific context value. This is useful for creating pre-configured context runners.

```APIDOC
## runWithContext<T>(handle: ContextHandle<T>, value: T)

### Description
Creates a reusable function that runs operations with a specific context value.

### Parameters
- **handle** (ContextHandle<T>) - The context handle to associate the value with.
- **value** (T) - The value to be used when the returned function is invoked.

### Returns
- A function that accepts an async callback and runs it with the specified context value.

### Example
```typescript
const runAsAdmin = runWithContext(userContext, adminUser)

const result = await runAsAdmin(async () => {
	// This runs with adminUser as the context
	return await performAdminOperation()
})
```
```
Tokens:
Raw