Merge context type declarations for wrappers

[maxakuru]

Right now using universal in Typescript means you need to manually set main()'s parameter types. This is expected, not much we can do about it, but the pain point is when you're using wrappers that extend the context.

This works great:

import { UniversalContext, Request } from '@adobe/helix-universal';

export function main (req: Request, ctx: UniversalContext) {
  ...
}

This doesn't:

import { UniversalContext, Request } from '@adobe/helix-universal';
import wrap from '@adobe/helix-shared-wrap';
import { logger } from '@adobe/helix-universal-logger';

function _main(req: Request, ctx: UniversalContext) {
  ctx.log.info("woo"); // Type error, ctx.log doesn't exist
}

export const main = wrap(_main).with(logger);

Ignoring the last line which has its own type errors, the context doesn't "know" about the logger wrapper. Workaround could be to import each context and make a custom interface merging them, but that would be repeated every time it's used.

The context APIs seem pretty useful to expose, so I'm proposing a namespace that would be exposed, allowing wrapper functions to extend the context as they need.

Assuming @adobe/helix-universal-logger adds an extension to the namespace like this:

// index.d.ts
declare module '@adobe/helix-universal' {
  namespace HelixUniversal {
    export interface UniversalContext {
      info: (...msgs: any[]) => void;
      // ...
    }
  }
}

TS clients could then use:

import { HelixUniversal, Request } from '@adobe/helix-universal';
import wrap from '@adobe/helix-shared-wrap';
import { logger } from '@adobe/helix-universal-logger';

async function _main(req: Request, ctx: HelixUniversal.UniversalContext) {
  ctx.log.info("woo"); // 👍 
}

export const main = wrap(_main).with(logger);

wdyt @tripodsan @trieloff ?

[tripodsan]

that's ok for me. but maybe call the namespace just Helix ?

also see:

• In admin, I extend the context to add some properties internally https://github.com/adobe/helix-admin/blob/7972146d9d440c1a2c86bac6a1175209e222388f/src/index.d.ts#L84
• in helix-shared-body-data, we add context.data: https://github.com/adobe/helix-shared/blob/6e9d30f8331171a4e60e58973e6d9e6a23271dc3/packages/helix-shared-body-data/src/body-data-wrapper.d.ts#L49
• in helix-shared-ims, we add context.ims: https://github.com/adobe/helix-shared/blob/6e9d30f8331171a4e60e58973e6d9e6a23271dc3/packages/helix-shared-ims/src/ims.d.ts#L139
• in helix-shared-config, we add context.config: https://github.com/adobe/helix-shared/blob/6e9d30f8331171a4e60e58973e6d9e6a23271dc3/packages/helix-shared-config/src/config-wrapper.d.ts#L75

[maxakuru]

that's ok for me. but maybe call the namespace just Helix ?

agreed, that makes sense

also see:

• In admin, I extend the context to add some properties internally https://github.com/adobe/helix-admin/blob/7972146d9d440c1a2c86bac6a1175209e222388f/src/index.d.ts#L84

since this isn't something a client would wrap, would there be anywhere other than the Admin codebase that context.data is accessible? does Admin's context (or any service's context, I suppose) get forwarded to other services somehow?

we could an index signature of [key: string]: unknown would mean "the service can add any additional key-values without a type error", and if the service wants to strongly type their added types, they can extend with the same module declaration syntax

• in helix-shared-body-data, we add context.data: https://github.com/adobe/helix-shared/blob/6e9d30f8331171a4e60e58973e6d9e6a23271dc3/packages/helix-shared-body-data/src/body-data-wrapper.d.ts#L49
• in helix-shared-ims, we add context.ims: https://github.com/adobe/helix-shared/blob/6e9d30f8331171a4e60e58973e6d9e6a23271dc3/packages/helix-shared-ims/src/ims.d.ts#L139
• in helix-shared-config, we add context.config: https://github.com/adobe/helix-shared/blob/6e9d30f8331171a4e60e58973e6d9e6a23271dc3/packages/helix-shared-config/src/config-wrapper.d.ts#L75

these seem like wrappers, I can open PRs to add their types

[maxakuru]

added in #71
keeping this open as a reminder to add the wrapper types