How $meta and meta works in middleware and procedure level?

[tresorama]

Don't want to waste time of anyone, so @dosu please partecipate the conversation and include code examples with clear comments of "what is happening behind the scene".

In orpc there is the concept of metadata, with $meta and meta APIs.
Questions:

1. $meta is for definition of which meta is required to be set? or what else?
2. $meta can be added to both middleware and procedure? What it does on both?
3. meta can be added to both middleware and procedure? What it does on both?
4. These API can be used to "attach" things in middleware declaration, and be able to consume these things inside procedure handler and outside of it?

   const procedure = os
     .use(middlewareCustom)
     .handler(async (stuff) => {
       // "inside" means here
     })
   
   // "outside" means here
   procedure['...']

[unnoq]

The $ prefix indicates that this method is related to configuration or settings and always has a value, even if it is not explicitly defined. Middleware only cares about the type, not the semantic meaning of the actual value.

[tresorama]

Could you please re-explain?
I'm not getting it...

$meta is for declaring the type (similar to $context) and meta is for fullfilling the required value of $meta?

[unnoq]

$meta requires an initial meta definition. Since some fields may be required, you must provide the initial meta to ensure that the meta object always satisfies the schema defined in $meta.

When $meta is defined before .middleware, the middleware can only be used in procedures that have the same meta type, or at least one that does not conflict.

Let's try https://deepwiki.com/middleapi/orpc

[tresorama]

@unnoq Do you know why the bot Dosu didn't replied?

[tresorama]

Here is an example with code with two appraoch:

1. create a oprc builder with $meta
2. create an orpc middleware with $meta

1 is correct for Typescript, instead 2 is incorrect for TS.

import { os } from "@orpc/server";

const builderWithCache = os
  .$meta<{ cache: boolean; }>({
    cache: false
  })
  .use(async (stuff, input) => {

    // if cache not enable -> skip
    if (!stuff.procedure["~orpc"].meta.cache) return stuff.next();

    // get cached data
    const cached = getCachedByProcedureData({
      procedureKey: stuff.procedure["~orpc"].route.operationId ?? stuff.procedure["~orpc"].route.path,
      inputNotSerialized: input
    });
    
    // if cache -> return from cache
    if (cached.cacheData) return cached.cacheData;

    // if not cached -> create cache + return
    const result = await stuff.next();
    saveToCache(cached.cacheKey, result);
    return result;

  });

const middlewareCache = os
  .$meta<{ cache: boolean; }>({
    cache: false
  })
  .middleware(async (stuff, input) => {
    // if cache not enable -> skip
    if (!stuff.procedure["~orpc"].meta.cache) return stuff.next();

    // get cached data
    const cached = getCachedByProcedureData({
      procedureKey: stuff.procedure["~orpc"].route.operationId ?? stuff.procedure["~orpc"].route.path,
      inputNotSerialized: input
    });
    
    // if cache -> return from cache
    if (cached.cacheData) return cached.cacheData;

    // if not cached -> create cache + return
    const result = await stuff.next();
    saveToCache(cached.cacheKey, result);
    return result;
  });


// with builder

const procWithBuilder = builderWithCache
  .meta({
    cache: true,
  })
  .handler(async () => {
    return {
      data: {
        hello: 'world'
      }
    };
  });

// with middleware

const procWithMiddleware = os
  .use(middlewareCache)
  /*
  ❌🔥 TS ERROR ☝️
  Argument of type 'DecoratedMiddleware<Record<never, never>, Record<never, never>, unknown, any, any, { cache: boolean; } & Record<never, never>>' is not assignable to parameter of type 'Middleware<Record<never, never>, Record<never, never>, unknown, unknown, ORPCErrorConstructorMap<Record<never, never>>, Record<never, never>>'.
  Types of parameters 'options' and 'options' are incompatible.
    Type 'MiddlewareOptions<Record<never, never>, unknown, ORPCErrorConstructorMap<Record<never, never>>, Record<never, never>>' is not assignable to type 'MiddlewareOptions<Record<never, never>, any, any, { cache: boolean; } & Record<never, never>>'.
      Type 'Record<never, never>' is not assignable to type '{ cache: boolean; } & Record<never, never>'.
        Property 'cache' is missing in type 'Record<never, never>' but required in type '{ cache: boolean; }'
  */
  .meta({
    cache: true
  })
  .handler(async () => {
    return {
      data: {
        hello: 'world'
      }
    };
  });


// internal - cache

function getCachedByProcedureData(data: {
  procedureKey?: string,
  inputNotSerialized?: any,
}) {

  // enure procedere key
  if (!data.procedureKey) {
    throw new Error("Cannot create cache key: Procedure key not found");
  }

  // ensure input are serializable
  let inputStringified: string | undefined;
  try {
    inputStringified = JSON.stringify(data.inputNotSerialized ?? {});
  } catch (error) {
    throw new Error("Cannot create cache key: Failed to stringify input");
  }

  // create cache key
  const cacheKey = `procedure:${data.procedureKey}__input:${inputStringified}`;

  // get from cache
  // TODO: do it
  return {
    cacheKey,
    cacheData: null,
  }

}

function saveToCache(cacheKey: string, cacheData: any) {
  // TODO: do it
}

[unnoq]

❌🔥 TS ERROR ☝️

Your middleware require cache: boolean but your os doesn't have it, make cache become optional cache?: boolean or define meta first and use middleware after os.$meta.use

[unnoq]

@dosu

[dosubot[bot]]

Here’s how $meta and meta work in orpc, especially with middleware and procedures:

$meta is used to define the shape and default values of metadata at the builder level. This sets up the type for all downstream middleware and procedures. meta is used to override or extend those values for a specific procedure or middleware instance. Both APIs merge metadata objects, so new keys are added, not replaced.

When you use middleware that expects a required meta property (like cache: boolean), you must first define that property with $meta on the builder. If you skip this, TypeScript will infer the meta type as Record<never, never>, causing type errors when the middleware expects a specific shape. You can fix this by either making the property optional (cache?: boolean) or by defining it up front with $meta before using the middleware. source

Accessing meta:

• Inside a handler or middleware, use stuff.procedure["~orpc"].meta to read the current meta.
• Outside (for static inspection, docs, etc.), you can access meta via procedure['~orpc'].meta.

Behind the scenes:

• Both $meta and meta ultimately call a mergeMeta function, which shallow merges the objects.
• Middleware and handlers always receive the merged meta via the procedure reference.
• Decorated procedures and middleware preserve the meta type/value, so you can attach, merge, and access meta at any point in the chain.
• This pattern lets you drive reusable logic (auth, permissions, caching) and influence docs (OpenAPI) by attaching meta at the right level. source

Example:

import { os } from "@orpc/server";

// Correct: define meta shape first
const builderWithCache = os
  .$meta<{ cache: boolean }>({ cache: false })
  .use(async (stuff, input) => {
    if (!stuff.procedure["~orpc"].meta.cache) return stuff.next();
    // ...cache logic...
    return stuff.next();
  });

const procWithBuilder = builderWithCache
  .meta({ cache: true }) // override for this procedure
  .handler(async () => ({ data: { hello: 'world' } }));

// Incorrect: missing $meta, causes TS error
const middlewareCache = os
  .$meta<{ cache: boolean }>({ cache: false })
  .middleware(async (stuff, input) => {
    if (!stuff.procedure["~orpc"].meta.cache) return stuff.next();
    // ...cache logic...
    return stuff.next();
  });

const procWithMiddleware = os
  .use(middlewareCache) // ❌ TS error: meta type not defined
  .meta({ cache: true })
  .handler(async () => ({ data: { hello: 'world' } }));

Best practice:
Always define required meta fields with $meta before using middleware that expects them. Use meta to override or extend values for specific procedures. This ensures type safety and makes meta available everywhere you need it.

For more advanced use (like permissions or OpenAPI docs), you can attach meta at the builder, middleware, or procedure level and consume it inside handlers, middleware, or externally for documentation generation. source

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}