Skip to content

feat(meta-schema): expose i18n and realtime metadata in _meta query #1300

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
pyramation merged 2 commits into from
Jun 15, 2026
Merged

feat(meta-schema): expose i18n and realtime metadata in _meta query #1300

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
8b6b459
feat(meta-schema): expose i18n and realtime metadata in _meta query
pyramation Jun 15, 2026
533e462
fix: correct introspection snapshot type ordering (Float before MetaI…
pyramation Jun 15, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 27 additions & 0 deletions graphile/graphile-settings/__tests__/__snapshots__/meta-schema.test.ts.snap
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,11 @@ exports[`MetaSchemaPlugin _meta query contract contains required selection paths
"foreignKeyConstraints.refFields.name",
"foreignKeyConstraints.referencedFields",
"foreignKeyConstraints.referencedTable",
"i18n",
"i18n.translatableFields",
"i18n.translatableFields.name",
"i18n.translatableFields.type",
"i18n.translationTable",
"indexes",
"indexes.columns",
"indexes.fields",
Expand All @@ -49,6 +54,8 @@ exports[`MetaSchemaPlugin _meta query contract contains required selection paths
"query.delete",
"query.one",
"query.update",
"realtime",
"realtime.subscriptionFieldName",
"relations",
"relations.belongsTo",
"relations.belongsTo.fieldName",
Expand Down Expand Up @@ -276,6 +283,16 @@ exports[`MetaSchemaPlugin _meta query contract has stable printed GraphQL text 1
boostRecencyDecay
}
}
i18n {
translationTable
translatableFields {
name
type
}
}
realtime {
subscriptionFieldName
}
}
}
}"
Expand Down Expand Up @@ -575,6 +592,7 @@ exports[`MetaSchemaPlugin snapshot scenarios produces stable metadata for a mult
"referencedTable": "post",
},
],
"i18n": null,
"indexes": [
{
"columns": [
Expand Down Expand Up @@ -650,6 +668,7 @@ exports[`MetaSchemaPlugin snapshot scenarios produces stable metadata for a mult
"one": "comment",
"update": "updatecomment",
},
"realtime": null,
"relations": {
"belongsTo": [
{
Expand Down Expand Up @@ -913,6 +932,7 @@ exports[`MetaSchemaPlugin snapshot scenarios produces stable metadata for a mult
"referencedTable": "user",
},
],
"i18n": null,
"indexes": [
{
"columns": [
Expand Down Expand Up @@ -988,6 +1008,7 @@ exports[`MetaSchemaPlugin snapshot scenarios produces stable metadata for a mult
"one": "post",
"update": "updatepost",
},
"realtime": null,
"relations": {
"belongsTo": [
{
Expand Down Expand Up @@ -1596,6 +1617,7 @@ exports[`MetaSchemaPlugin snapshot scenarios produces stable metadata for a mult
"referencedTable": "tag",
},
],
"i18n": null,
"indexes": [
{
"columns": [
Expand Down Expand Up @@ -1706,6 +1728,7 @@ exports[`MetaSchemaPlugin snapshot scenarios produces stable metadata for a mult
"one": "post_tag",
"update": "updatepost_tag",
},
"realtime": null,
"relations": {
"belongsTo": [
{
Expand Down Expand Up @@ -1860,6 +1883,7 @@ exports[`MetaSchemaPlugin snapshot scenarios produces stable metadata for a mult
},
],
"foreignKeyConstraints": [],
"i18n": null,
"indexes": [
{
"columns": [
Expand Down Expand Up @@ -1962,6 +1986,7 @@ exports[`MetaSchemaPlugin snapshot scenarios produces stable metadata for a mult
"one": "tag",
"update": "updatetag",
},
"realtime": null,
"relations": {
"belongsTo": [],
"has": [
Expand Down Expand Up @@ -2340,6 +2365,7 @@ exports[`MetaSchemaPlugin snapshot scenarios produces stable metadata for a mult
},
],
"foreignKeyConstraints": [],
"i18n": null,
"indexes": [
{
"columns": [
Expand Down Expand Up @@ -2442,6 +2468,7 @@ exports[`MetaSchemaPlugin snapshot scenarios produces stable metadata for a mult
"one": "user",
"update": "updateuser",
},
"realtime": null,
"relations": {
"belongsTo": [],
"has": [
Expand Down
193 changes: 193 additions & 0 deletions graphile/graphile-settings/__tests__/meta-schema.test.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -393,6 +393,13 @@ query MetaContract {
hasUnifiedSearch
config { weights boostRecent boostRecencyField boostRecencyDecay }
}
i18n {
translationTable
translatableFields { name type }
}
realtime {
subscriptionFieldName
}
}
}
}
Expand Down Expand Up @@ -469,6 +476,10 @@ const REQUIRED_META_QUERY_PATHS = [
'search.config.boostRecencyDecay',
'fields.enumValues.name',
'fields.enumValues.values',
'i18n.translationTable',
'i18n.translatableFields.name',
'i18n.translatableFields.type',
'realtime.subscriptionFieldName',
];

function collectSelectionPaths(selections: readonly SelectionNode[], prefix = ''): string[] {
Expand Down Expand Up @@ -2200,6 +2211,188 @@ describe('MetaSchemaPlugin', () => {
});
});

describe('i18n metadata', () => {
it('returns null i18n for tables without @i18n tag', () => {
const build = createMockBuild({
user: {
codec: createMockCodec('user', {
id: createMockAttribute('uuid'),
name: createMockAttribute('text'),
}),
uniques: [],
relations: {},
},
});
const tables = callInitHook(build);
expect(tables[0].i18n).toBeNull();
});

it('detects @i18n tagged tables with translation table name', () => {
const baseCodec = {
name: 'post',
attributes: {
id: createMockAttribute('uuid'),
title: createMockAttribute('text'),
body: createMockAttribute('text'),
views: createMockAttribute('int4'),
},
isAnonymous: false,
extensions: {
pg: { schemaName: 'app_public' },
tags: { i18n: 'post_translations' },
},
};
const translationCodec = {
name: 'postTranslations',
attributes: {
post_id: createMockAttribute('uuid'),
lang_code: createMockAttribute('text'),
title: createMockAttribute('text'),
body: createMockAttribute('text'),
},
isAnonymous: false,
extensions: {
pg: { schemaName: 'app_public', name: 'post_translations' },
},
};
const build = createMockBuild({
post: {
codec: baseCodec,
uniques: [],
relations: {},
},
post_translations: {
codec: translationCodec,
uniques: [],
relations: {},
},
});
const tables = callInitHook(build);
const postTable = tables.find((t: any) => t.name === 'Post');
expect(postTable.i18n).toEqual({
translationTable: 'post_translations',
translatableFields: [
{ name: 'title', type: 'text' },
{ name: 'body', type: 'text' },
],
});
});

it('excludes non-text columns from translatable fields', () => {
const baseCodec = {
name: 'item',
attributes: {
id: createMockAttribute('uuid'),
label: createMockAttribute('text'),
count: createMockAttribute('int4'),
},
isAnonymous: false,
extensions: {
pg: { schemaName: 'app_public' },
tags: { i18n: 'item_translations' },
},
};
const translationCodec = {
name: 'itemTranslations',
attributes: {
item_id: createMockAttribute('uuid'),
lang_code: createMockAttribute('text'),
label: createMockAttribute('text'),
},
isAnonymous: false,
extensions: {
pg: { schemaName: 'app_public', name: 'item_translations' },
},
};
const build = createMockBuild({
item: {
codec: baseCodec,
uniques: [],
relations: {},
},
item_translations: {
codec: translationCodec,
uniques: [],
relations: {},
},
});
const tables = callInitHook(build);
const itemTable = tables.find((t: any) => t.name === 'Item');
expect(itemTable.i18n).toEqual({
translationTable: 'item_translations',
translatableFields: [{ name: 'label', type: 'text' }],
});
});
});

describe('realtime metadata', () => {
it('returns null realtime for tables without @realtime tag', () => {
const build = createMockBuild({
user: {
codec: createMockCodec('user', {
id: createMockAttribute('uuid'),
name: createMockAttribute('text'),
}),
uniques: [],
relations: {},
},
});
const tables = callInitHook(build);
expect(tables[0].realtime).toBeNull();
});

it('detects @realtime tagged tables', () => {
const realtimeCodec = {
name: 'message',
attributes: {
id: createMockAttribute('uuid'),
content: createMockAttribute('text'),
},
isAnonymous: false,
extensions: {
pg: { schemaName: 'app_public' },
tags: { realtime: true },
},
};
const build = createMockBuild({
message: {
codec: realtimeCodec,
uniques: [],
relations: {},
},
});
const tables = callInitHook(build);
expect(tables[0].realtime).toEqual({
subscriptionFieldName: 'onMessageChanged',
});
});

it('generates correct subscription field name from table type', () => {
const realtimeCodec = {
name: 'chat_room',
attributes: {
id: createMockAttribute('uuid'),
},
isAnonymous: false,
extensions: {
pg: { schemaName: 'app_public' },
tags: { realtime: true },
},
};
const build = createMockBuild({
chat_room: {
codec: realtimeCodec,
uniques: [],
relations: {},
},
});
const tables = callInitHook(build);
expect(tables[0].realtime).toEqual({
subscriptionFieldName: 'onChatRoomChanged',
});
});
});

describe('_meta query contract', () => {
it('contains required selection paths', () => {
const paths = getMetaQueryTablePaths(META_QUERY_CONTRACT).sort();
Expand Down
28 changes: 28 additions & 0 deletions graphile/graphile-settings/src/plugins/meta-schema/graphql-meta-field.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -251,6 +251,32 @@ function createMetaSchemaType(): GraphQLObjectType {
}),
});

const MetaI18nFieldType = new GraphQLObjectType({
name: 'MetaI18nField',
description: 'A translatable field',
fields: () => ({
name: { type: nn(GraphQLString), description: 'GraphQL field name' },
type: { type: nn(GraphQLString), description: 'PostgreSQL column type (text, citext)' },
}),
});

const MetaI18nType = new GraphQLObjectType({
name: 'MetaI18n',
description: 'i18n metadata for a table with @i18n tag',
fields: () => ({
translationTable: { type: nn(GraphQLString), description: 'Name of the translation table' },
translatableFields: { type: nnList(MetaI18nFieldType), description: 'Fields that are translatable' },
}),
});

const MetaRealtimeType = new GraphQLObjectType({
name: 'MetaRealtime',
description: 'Realtime metadata for a table with @realtime tag',
fields: () => ({
subscriptionFieldName: { type: nn(GraphQLString), description: 'The generated subscription field name (e.g. onPostChanged)' },
}),
});

const MetaTableType = new GraphQLObjectType({
name: 'MetaTable',
description: 'Information about a database table',
Expand All @@ -268,6 +294,8 @@ function createMetaSchemaType(): GraphQLObjectType {
query: { type: nn(MetaQueryType) },
storage: { type: MetaStorageType, description: 'Storage metadata (null if not a storage table)' },
search: { type: MetaSearchType, description: 'Search metadata (null if no search configured)' },
i18n: { type: MetaI18nType, description: 'i18n metadata (null if no @i18n tag)' },
realtime: { type: MetaRealtimeType, description: 'Realtime metadata (null if no @realtime tag)' },
}),
});

Expand Down
Loading
Loading