Unique Symbols: How to Use Symbols for Type Safety

If you’ve spent some time working with React, you might have stumbled upon React Query’s queryOptions() function. Its implementation looks shockingly simple:

export function queryOptions(options: unknown) {
  return options
}

However, the real magic lies in its overloaded function signatures. So, what’s so special about it?

If you’re unsure what an overloaded function is, you can check out this post: Function Overloading: How to Handle Multiple Function Signatures

Typed Database Queries

Inspired by React Query’s approach, I put together a helper function that might be useful for people working outside of React: a straightforward way to create typed queries, for example, SQL queries.

export declare const queryParamsSymbol: unique symbol;
export declare const queryReturnSymbol: unique symbol;

export type Query<
  TParams extends Record<string, any> = Record<string, any>,
  TReturn extends Record<string, any> | undefined = undefined,
  TStatement extends string = string,
> = {
  statement: TStatement;
  [queryParamsSymbol]: TParams;
  [queryReturnSymbol]: TReturn;
};

export function query<
  TParams extends Record<string, any> = Record<string, any>,
  TReturn extends Record<string, any> | undefined = undefined,
  TStatement extends string = string,
>(statement: TStatement): Query<TParams, TReturn> {
  return { statement: statement } as Query<TParams, TReturn, TStatement>;
}

Similar to queryOptions(), the function itself is pretty dull: it takes a SQL statement, wraps it in an object of type Query, and returns it.

Here’s a quick example of how you’d call it:

const getUserById = query<{ id: number }, { name: string; email: string }>(
  'SELECT name, email FROM users WHERE id = $id',
);

Notice how we pass two types as generic parameters. The first is the required query parameters — in this case, id. The second represents the query’s return type — name and email.

Under the hood, query() embeds those two types into the returned object, stashing them in queryParamsSymbol and queryReturnSymbol. These symbols are declared as unique symbol, which means they only exist in type-space and don’t appear in the transpiled JavaScript.

I use these symbols to temporarily store the parameter and return types and retrieve them whenever I need them.

type InferQueryParams<TQuery> = TQuery extends Query<infer Params, any> ? Params : never;

type UserQueryParams = InferQueryParams<typeof getUserById>;
//        ^? { id: number }

type InferQueryReturn<TQuery> = TQuery extends Query<any, infer Return> ? Return : never;

type UserQueryReturn = InferQueryReturn<typeof getUserById>;
//        ^? { name: string; email: string }

The InferQueryParams and InferQueryReturn are just utility types to confirm that our parameter and return types are being inferred correctly. You might not actually need them, but they’re handy for verifying our approach.

Database Client

Now that we know how to embed parameter and return types in a query object, how do we actually run these queries? Let’s take a look at a simple database client that can execute our typed queries:

class DatabaseClient {
  async execute<
    TParams extends Record<string, any>, 
    TReturn extends Record<string, any>
  >(
    query: Query<TParams, TReturn>,
    params: TParams,
  ): Promise<Array<TReturn>> {
    // execute the query and return the results
    // ...
    return [];
  }
}

const db = new DatabaseClient();

// Return type and parameters are inferred from the query object
const result = await db.execute(getUserById, { id: 1 });
//                                              ^? { id: number }
//      ^? Array<{ name: string; email: string }>
console.log(result);

In this example, we pass our typed getUserById query object to the db.execute() method. Because the Query type contains both the parameter and return-type information, TypeScript automatically infers them. We can easily confirm this by hovering over result and TypeScript will also suggest id as property of our parameters object.

TypeScript Playground

You can find the complete code example in this TypeScript Playground.