WunderGraph composes APIs and databases into a type-safe gateway. UUID v7 as a record identifier flows through the WunderGraph operation layer without special treatment — it is a string ID that the underlying database stores as a UUID. See UUID v7 in JavaScript for the generation API.

Client-side UUID v7 in a WunderGraph mutation

import { createClient } from './.wundergraph/generated/client';
import { v7 as uuidv7 } from 'uuid';

const client = createClient();

// Generate UUID v7 client-side and pass to the operation
async function createOrder(customerId: string, total: number) {
  const id = uuidv7(); // UUID v7 — time-ordered, RFC 9562

  const result = await client.mutate({
    operationName: 'CreateOrder',
    input: {
      id,
      customerId,
      total,
      status: 'pending',
    },
  });

  if (result.error) throw result.error;
  return result.data;
}

WunderGraph operation definition (.graphql)

# .wundergraph/operations/CreateOrder.graphql
mutation CreateOrder($id: String!, $customerId: String!, $total: Float!) {
  db_createOneOrder(data: {
    id:          $id
    customer_id: $customerId
    total:       $total
    status:      "pending"
  }) {
    id
    status
  }
}

WunderGraph hook — server-side UUID v7 enforcement

// .wundergraph/webhooks/mutatingPreResolve.ts
import { v7 as uuidv7 } from 'uuid';

export default {
  async mutatingPreResolve({ input, user }) {
    // Enforce UUID v7 — override any client-supplied ID
    return {
      ...input,
      id: uuidv7(),
    };
  },
};

Cursor pagination operation

# .wundergraph/operations/ListOrders.graphql
query ListOrders($cursor: String, $limit: Int!) {
  db_findManyOrder(
    where:   { id: { gt: $cursor } }
    orderBy: [{ id: asc }]
    take:    $limit
  ) {
    id
    total
    status
  }
}
async function listOrders(cursor?: string, limit = 20) {
  const result = await client.query({
    operationName: 'ListOrders',
    input: { cursor, limit },
  });
  const items      = result.data?.db_findManyOrder ?? [];
  const nextCursor = items.length === limit ? items.at(-1)?.id : undefined;
  return { items, nextCursor };
}

Further reading

External references

Frequently asked questions

What is WunderGraph?

WunderGraph is an API composition and developer platform. It provides a type-safe API layer that sits between clients and backend services — GraphQL federation via Cosmo, REST API composition, and direct database access. Developers define operations and WunderGraph generates type-safe client SDKs. See What is a UUID for identifier context.

How does UUID v7 work in WunderGraph typed operations?

WunderGraph operations accept typed inputs. Define your mutation input with an id: ID! or id: String! field. Generate UUID v7 on the client before calling the operation: const id = uuidv7(). WunderGraph forwards the ID to your data source unchanged — the time-ordered UUID v7 flows from client to database. See UUID v7 in JavaScript.

Can WunderGraph hooks validate UUID v7 inputs?

Yes. WunderGraph's mutatingPreResolve hook runs before the mutation resolves. Use it to validate that the id field is a valid UUID v7 string, generate one if missing, or enforce server-side generation by overriding client-supplied IDs. This keeps ID policy consistent across all clients.