Registry / database / graphql-versioned-transformer

graphql-versioned-transformer

library5.2.80jsnpmunverified

A GraphQL transform directive (@versioned) for AWS AppSync that adds object versioning and conflict resolution to @model types. Part of the Amplify GraphQL Transformer ecosystem, this package enables optimistic locking and conflict detection for GraphQL mutations. Version 5.2.80 targets the Amplify Gen 1 GraphQL Transformer v2, compatible with @aws-amplify/graphql-transformer-core. It is deprecated in favor of Amplify GraphQL Transformer v3+ built-in conflict resolution. Key differentiators: integrates directly with AppSync resolvers for DynamoDB, automatic version increment on updates, conditional writes for safe concurrent edits. Release cadence is tied to Amplify CLI releases, typically bi-weekly. Not intended for standalone use outside Amplify.

database devops

npm install graphql-versioned-transformer

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · GRAPHQL-VERSIONED-

graphql-versioned-transformer

databasejavascriptv5.2.80

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

VersionedTransformer

✓ import { VersionedTransformer } from 'graphql-versioned-transformer';

✗ const VersionedTransformer = require('graphql-versioned-transformer');

ESM-only package; CJS require will fail.

versionedTransformerFactory

✓ import { versionedTransformerFactory } from 'graphql-versioned-transformer';

✗ import { createVersionedTransformer } from 'graphql-versioned-transformer';

Factory function is the default export pattern for transformers.

VersionedDirective

✓ import { VersionedDirective } from 'graphql-versioned-transformer';

TypeScript type; use for custom GraphQL transformer definitions.

VersionedTransformerConfig

✓ import type { VersionedTransformerConfig } from 'graphql-versioned-transformer';

✗ import { VersionedTransformerConfig } from 'graphql-versioned-transformer';

Type-only import recommended when not used at runtime.

Shows how to instantiate VersionedTransformer, add it to GraphQLTransform, and transform a schema with @versioned directive on a @model type.

import { VersionedTransformer } from 'graphql-versioned-transformer'; import { GraphQLTransform } from '@aws-amplify/graphql-transformer-core'; const versionedTransformer = new VersionedTransformer(); const transform = new GraphQLTransform({ transformers: [versionedTransformer], }); const schema = ` type Todo @model @versioned { id: ID! title: String! description: String version: Int! } `; const result = await transform.transform(schema); console.log('Generated resources:', result.stacks);

Debug

Known issues

deprecatedThis package is deprecated in favor of built-in conflict resolution in Amplify GraphQL Transformer v3.

fix

Migrate to Amplify GraphQL Transformer v3 which supports versioning and conflict resolution without a separate directive. See Amplify documentation for migration guide.

affects: >=5.0.0

breakingIn version 5.0.0, the package was renamed from 'graphql-versioned-transformer' to 'graphql-versioned-transformer' (still same) but the transformer interface changed to match GraphQL Transformer v2. VersionedTransformer is no longer a constructor but a factory function.

fix

Use constructor: new VersionedTransformer() instead of factory. Check @aws-amplify/graphql-transformer-core peer dependency version.

affects: >=5.0.0

breakingSince v5, the @versioned directive only works with @model types and requires a `version` field on the model.

fix

Ensure every @model with @versioned includes a version: Int! field, otherwise the transformer will throw.

affects: >=5.0.0

gotchaCommon mistake: forgetting to add `version: Int!` field to the model schema leads to runtime errors.

fix

Always include a version field in your GraphQL schema for models using @versioned.

affects: >=5.0.0

gotchaThe package is not meant for standalone use; requires @aws-amplify/graphql-transformer-core to be installed as a peer dependency.

fix

Install the peer dependencies: npm i @aws-amplify/graphql-transformer-core graphql graphql-mapping-template graphql-transformer-common

affects: >=5.0.0

Errors

Common errors & fixes

Cannot find module 'graphql-versioned-transformer'

Package not installed or module resolution fails in CommonJS.

fix

Use npm i graphql-versioned-transformer and ensure your project is ESM (use import instead of require). If using CJS, consider upgrading to ESM or use dynamic import.

You must call .add() on a transformer instance to include it in the transformation

Incorrect usage: forgetting to instantiate transformer before using in GraphQLTransform.

fix

Correct code: const transformer = new VersionedTransformer(); transform.add(transformer); Or pass in transformers array.

Directive 'versioned' is not defined on the service

The @versioned directive was not added to the transformer list or the transformer is not registered.

fix

Ensure VersionedTransformer is included in the transformers array passed to GraphQLTransform constructor.

Field 'version' is not defined on type 'Todo'

Missing version field in GraphQL schema for a model using @versioned.

fix

Add 'version: Int!' to the model type.

Upgrade

Version history

5.2.80latest on npm

Audit

Dependencies

@aws-amplify/graphql-transformer-corerequiredRequired for directive registration and transformer context.

graphqlrequiredUsed for parsing and schema manipulation.

graphql-mapping-templaterequiredUsed to generate AppSync VTL mapping templates.

graphql-transformer-commonrequiredShared utilities for GraphQL transformers.

Agent activity

9 hits · last 30 days

node

Amazon

Resources

githubhttps://github.com/aws-amplify/amplify-category-api ↗

packagegraphql-versioned-transformer ↗

homepagehttps://github.com/aws-amplify/amplify-category-api#readme ↗