aws-tanstack-query

Generate type-safe TanStack Query options from AWS SDK v3 clients.

Installation

npm install aws-tanstack-query

Quick Start

Create a generate.ts file:

import { SmithyTanStackQuery, generate } from 'aws-tanstack-query';

const dynamodb = new SmithyTanStackQuery({
  name: 'DynamoDB',
  client: '@aws-sdk/client-dynamodb',
  outDir: './src/generated/dynamodb',
});

await generate([dynamodb]);

Run it:

npx tsx generate.ts
# or
bun run generate.ts

Generated Code

This generates type-safe query options you can use directly with TanStack Query:

import { useQuery, useMutation } from '@tanstack/react-query';
import { getItemQueryOptions, putItemMutationOptions, dynamoDBKeys } from './generated/dynamodb';
import { DynamoDBClient } from '@aws-sdk/client-dynamodb';

const client = new DynamoDBClient({});

// Queries
function useGetItem(tableName: string, key: Record<string, any>) {
  return useQuery(
    getItemQueryOptions({
      client,
      input: { TableName: tableName, Key: key },
    })
  );
}

// Mutations with invalidation
function usePutItem() {
  const queryClient = useQueryClient();

  return useMutation({
    ...putItemMutationOptions({ client }),
    onSuccess: () => {
      queryClient.invalidateQueries({ queryKey: dynamoDBKeys.all });
    },
  });
}

Options

new SmithyTanStackQuery({
  // Required
  name: 'DynamoDB',                        // Service name for generated code
  client: '@aws-sdk/client-dynamodb',      // AWS SDK package name
  outDir: './src/generated/dynamodb',      // Output directory

  // Optional
  include: ['Get*', 'Put*', 'Query'],      // Glob patterns to include
  exclude: ['*Backup*'],                   // Glob patterns to exclude
  mutations: true,                         // Generate mutations (default: true)
  queryKeyPrefix: ['aws', 'dynamodb'],     // Custom query key prefix
  format: true,                            // Format with Prettier (default: true)
});

Multiple Clients

import { SmithyTanStackQuery, generate } from 'aws-tanstack-query';

const dynamodb = new SmithyTanStackQuery({
  name: 'DynamoDB',
  client: '@aws-sdk/client-dynamodb',
  outDir: './src/generated/dynamodb',
});

const s3 = new SmithyTanStackQuery({
  name: 'S3',
  client: '@aws-sdk/client-s3',
  outDir: './src/generated/s3',
});

await generate([dynamodb, s3]);

Generated Files

src/generated/dynamodb/
├── index.ts           # Re-exports everything
├── query-keys.ts      # Query key factory (dynamoDBKeys)
├── queries.ts         # queryOptions for read operations
├── mutations.ts       # mutationOptions for write operations
└── create-queries.ts  # Factory function

CLI

You can also use the CLI:

# Create a config file
npx aws-tanstack-query init

# Generate from config
npx aws-tanstack-query generate

License

MIT