Add a `context` option for passing arbitrary data to hooks

[Chinoman10]

I'd like to propose a new context or ctx option (for greater, "anything goes" extensibility), which would solve two problems for me (one of which I've found a not-very-elegant workaround, but the other I haven't been able to yet), and potentially other users too.

Use-case 1:

Env Variables in Serverless environments

In typical serverless environments, such as Cloudflare Workers, environment variables (specially secrets) are passed along in a 'context', which is often "ping-ponged" between functions so each of the business logic functions can use it for whatever they need.
Because of this, I cannot statically (on build) define a KyInstance with an api-key header, since I won't have it when the instance is created.
My chosen workaround (I've had a few) was wrapping the ky.extends in a function that receives the api-key, and injects it. Something like this:

const api = (c: Context<{ Bindings: Bindings }>) =>
  ky.extend({
    prefixUrl: 'https://domain.com/v99',
    headers: {
     'api-key': c.env.API_KEY,
    },
  });
const smtp = (c: Context) =>
  api(c).extend((api) => ({
    prefixUrl: `${api.prefixUrl}/smtp/email`,
  }));
const contacts = (c: Context) =>
  api(c).extend((api) => ({
    prefixUrl: `${api.prefixUrl}/contacts`,
  }));

Which then I have to replace all my smtp.post('', { json: body }).json() with smtp(c).post(...).json().
If I could pass along something like: smtp.post('', { json: body, ctx: c }).json(), I would then be able to use a beforeRequest hook to inject the API key in the headers.

Custom Errors

Before I found out Ky existed, I used to do some code like this:

// utils.ts

const postJsonHeaderData = () => ({
  method: "POST",
  headers: {
    Accept: "application/json",
    "content-type": "application/json",
  },
});

export const requestJson = (bodyData: any) => ({
  ...structuredClone(postJsonHeaderData()),
  body: JSON.stringify(bodyData),
});

export const handleResponse = (r: Response, num?: number, errorDescription?: string) => {
  if (!r.ok)
      throw fetchError(r, num, errorDescription);

  const contentType = r.headers.get("Content-Type");
  if (contentType && contentType.includes("application/json"))
      return r.json();
  else
      return r.text();
}

const fetchError = (r: Response, num?: number, description?: string) => (
  new Error(
    `Error (${r.status}) with fetch #${num ?? 0}${description? ` (${description})`: ''} - '${
      r.statusText
    }' from URL: ${r.url}`
  )
);

export const genericError = (r: Response, num?: number, description?: string) => {
  return new Error(
    `Error (${r.status}) with request #${num ?? 0}${description? ` (${description})`: ''} - '${
      r.statusText
    }' from URL: ${r.url}`
  );
}

Which would be used as such:

// some-email-logic.ts

export async function createContact(env: Env, user: { email: string, attributes: { FIRSTNAME: string, LASTNAME: string }}):
  Promise<BrevoContact>
{
    const method = HttpMethods.POST;

    return fetch(`${BREVO_API_CONTACTS_ENDPOINT}`,
        requestJson(env.BREVO_API_KEY, method, user)
    ).then((r) => handleResponse(r, 0, `Creating ${user.email}'s contact on Brevo`));
}

Which gives me really good logging --> when an error occurs, the function that made the request already passed what it was trying to do in a 'human text', and I can use a request number (in this case 0) if I'm retrying multiple times.

I'm not sure how to do this with Ky, since I can't extend Ky Instances with custom functions or properties for me to use in the Hooks (onError, in this case).
If I had a ctx: Object (which I could extend to my heart's content), I could do something like this:

return await contacts(c)
    .post('', {
      json: user,
      ctx: {
        'task-description': `Creating ${user.email}'s contact on Brevo`)),
      },
    })
    .json<BrevoContact>();

Which would then be picked up a custom beforeError hook.

[sindresorhus]

Yeah, makes sense. It should be named context.

We should take inspiration from Got: https://github.com/sindresorhus/got/blob/main/documentation/2-options.md#context

[Chinoman10]

Yeah, makes sense. It should be named context.

We should take inspiration from Got: https://github.com/sindresorhus/got/blob/main/documentation/2-options.md#context

Brilliant 🥳
Wishing for this 🤞

[sholladay]

Overall, I'm in favor of adding this feature, as the flexibility can come in handy sometimes. But I've become very skeptical of these sorts of pseudo-global arbitrary data context objects. A lot of frameworks have them and it's usually a headache. What tends to happen in moderately sized codebases is it becomes completely non-obvious where the data is coming from and where the boundaries are, who else needs it (sometimes the object keys get set dynamically), on top of the usual limitations with objects like editors and other tooling not knowing if a property is unused, etc. TypeScript doesn't usually know if a type has been narrowed elsewhere. It can be pretty frustrating to work with in practice.

What I tend to do these days is have a module that exports the data as well as a function to update the data. Any module that needs it then imports it explicitly. When the data gets updated, even if it's completely re-assigned, the importers will automatically have the new data because of a feature in ES modules known as "live bindings". In other words, re-assignment of exported variables propagates across modules. It's very cool and it means you can more easily trace the data flow, while avoiding passing the data around so much.

Here's how that might look for you.

// context.js
export let context = {};

export const setContext = (newContext) => {
    context = newContext;
};

// api.js
import { context } from './context.js';

const api = ky.extend({
    prefixUrl: 'https://domain.com/v99',
    hooks: {
        beforeRequest: [
            (request) => {
                request.headers.set('api-key', context.env.API_KEY);
            }
        ]
    }
});

export const smtp = api.extend((api) => ({
    prefixUrl: `${api.prefixUrl}/smtp/email`,
}));

export const contacts = api.extend((api) => ({
    prefixUrl: `${api.prefixUrl}/contacts`,
}));

// index.js
import { smtp } from './api.js';
import { setContext } from './context.js';

// Your serverless function
const main = async (context) => {
    setContext(context);

    await smtp.post('', { json: {} }).json();
};

export default main;

Notice how simple all of that is. You don't even have to pass .post('', { context }). And it means you are in control instead of the library, plus you have a convenient place to add validation or other logic to that setContext() function, for example. It doesn't solve every problem, but it's much better.

[Chinoman10]

I had no idea that was even possible tbh.
To me it looks like a clear violation of changing the assignment of a const (which you normally can't do).
Changing the const's properties is commonplace, but not it's assignment.

Regardless, I'll test this out! If you are right (which I'd assume 😅) then I can ditch the (c) workaround I already did.
I'll try it with a function as well, for the error-logging use-case.

[sholladay]

That was just a typo on my part. It needs to be a let to be reassigned. I have corrected the example.

[Chinoman10]

Just when I thought I had my TS/JS foundation shook, it was just a typo after all, hahaha. This was hilarious :D
At least it gave me a good chuckle, so it wasn't for nothing :)
In any case, I haven't tried it out yet, but should be doable either today or over the weekend.