Skip to content

feat(graphile-meta): grid metadata, and a valid name for every enum label - #1996

Merged
devin-ai-integration[bot] merged 4 commits into
mainfrom
feat/meta-sheets-fields
Nov 16, 2026
Merged

devin-ai-integration[bot] merged 4 commits into
mainfrom
feat/meta-sheets-fields

Conversation

@yyyyaaa

@yyyyaaa yyyyaaa commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

Additive _meta fields that let a data grid build every read and write from metadata, plus a fix for enum labels that broke the whole schema build. Consumed by the Sheets table model in constructive-io/blocks (constructive-io/blocks#63).

_meta additions (graphile-meta)

  • MetaTable.kind (table or view) and MetaTable.description.
  • MetaField.isComputed, and MetaField.file (kind, isMultiple, filesType) for image, upload and attachment columns.
  • MetaType.maxLength, precision and scale; srid and dimensions are now populated.
  • dotPath per tree-path column, read from how that column is really served: a plain path is served as /top/science (false), a list of paths as top.science (true).
  • Relation key pairs: refKeys on belongs-to, remoteKeys on has-one and has-many. Like the foreign key constraints they repeat, they name every key column, even one the other table hides; the README tells clients to check each name.
  • README: a backward relation appears only when an index covers its foreign key columns.

Enum labels with a space or a dash (graphile-settings)

Cause. Each enum label becomes a GraphQL enum value name, which must match [_A-Za-z][_0-9A-Za-z]*. The enumValue inflector upper-cased the default name, which keeps spaces, dashes and apostrophes, so a label such as in progress, done-ish, won't fix or 進行中 produced an invalid name and the whole API of that database failed to build:

Enum type 'Status' attempted to define a value with invalid name "IN PROGRESS".

A second fault: labels that differ only in case (Done, done) shared one name, and a row holding the earlier label could not be read.

Fix. enum-value-names.ts names all labels of an enum together:

Label Name
todo, in_progress, café TODO, IN_PROGRESS, CAFE (unchanged)
on hold, done-ish, won't fix ON_HOLD, DONE_ISH, WON_T_FIX
1st review _1ST_REVIEW
🙂 (nothing usable) _ + a hash of the label
a-b after a b (taken) A_B_ + a hash of the label

The hash is FNV-1a of the label's UTF-8 bytes, so a name does not move when other labels are added or reordered.

Compatibility. Every name that is valid and unique today is unchanged. The only name that changes in a schema that builds today is the earlier label of a case-only pair, which could not be read before. Order-by and filter names are not affected.

The three snapshots change only by the new Meta fields, the MetaFileField type and the new dotPath description.

After merge: run the constructive-db "Schema SDK Update" workflow.

🤖 Generated with Claude Code

https://claude.ai/code/session_017WbsG7HDw7AL26N4UZGgrM

… name

- A label with a space, a dash, an apostrophe or non-Latin letters (`in progress`,
  `done-ish`, `won't fix`) became an invalid enum value name, and the whole API of
  that database failed to build. Each run of other characters now becomes `_`.
- A label with nothing usable left, or a name already taken, gets a short suffix
  hashed from the label itself, so names do not move when labels are added.
- Labels that differ only in case no longer share one name; the later one keeps it.
- Every name that is valid and unique today is unchanged.
…e limits

- `MetaTable.kind` and `description`, `MetaField.isComputed`, `MetaField.file`
  (kind, list, files type), `MetaType` length, precision and scale, and populated
  `srid`, `dimensions` and a per-column `dotPath` for tree paths.
- Relation key pairs: `refKeys` on belongs-to and `remoteKeys` on has-one/has-many.
- The README states the real rule for backward relations: an index must cover the
  foreign key columns.
- A torture seed covering every column kind the backend can create, with an
  integration suite that reads `_meta` and the rows back.
@luxor-code-review

luxor-code-review Bot commented Nov 13, 2026 •

Copy link
Copy Markdown

Review complete. 🟡 1 medium

💬 Inline comments (1)

🧹 Nitpicks (1) — 🟢 1 low
  • 🟢 dotPath flips from always-true to per-codec value (encoding-meta-builders.ts:118) — buildScalarEncoding for ltree changed from a constant dotPath: true to servesDotPath(attr.codec), so _meta responses for slash-serving ltree columns now report dotPath: false (or null) where every prior version reported true (graphile/graphile-meta/src/encoding-meta-builders.ts:118).

The change expands the graphile-meta PostGraphile v5 plugin so _meta exposes rich table/field metadata, and it backfills tests plus a seed fixture in graphile-settings to exercise the new paths.

Files Change
graphile/graphile-meta/src/* New metadata builders for relations, encoding, storage/search smart tags, and file domains, plus TableMeta/MetaField type additions (kind, isComputed, refKeys, remoteKeys, etc.) wired through the plugin and table builders
graphile/graphile-settings/src/plugins/* enum-value-names and custom-inflector plugin updates for derived enum value naming
graphile/graphile-settings/sql/sheets-torture-seed.sql Torture-test seed covering typmods, generated/identity columns, ltree, geometry/vector, and file domains
graphile/graphile-settings/__tests__/*, graphile/graphile-meta/__tests__/* New integration tests and regenerated snapshots for the expanded metadata schema

Reviewed commit: 4c15806

@luxor-code-review luxor-code-review Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This PR extends the _meta GraphQL schema with per-table and per-field metadata (kinds, computed flags, relation key lists, encoding details like ltree paths and file/encoding domains) and adds integration tests and a torture-seed SQL fixture to cover them.

Key findings

…visibility

`refKeys` and `remoteKeys` repeat the columns of the foreign key constraints, which
were never filtered, and they must pair with `keys` position by position. The README
now says so and tells clients to check each name against the other table's fields.
The `exposedColumns` comment no longer claims that every column fact goes through it.
@yyyyaaa

yyyyaaa commented Nov 14, 2026

Copy link
Copy Markdown
Contributor Author

Tenki nitpick on dotPath: intended. The earlier constant true was wrong for slash-serving tree-path columns; the per-column value is documented in the README and in the PR description.

- `grid-meta.test.ts` already covers each new `_meta` field, and
  `enum-value-names.integration.test.ts` covers the enum fix end to end.
- The rest of the suite checked existing behavior and exported fixtures for
  Blocks, which belongs outside this repository.
@yyyyaaa
yyyyaaa requested a review from pyramation November 16, 2026 03:26
@devin-ai-integration
devin-ai-integration Bot merged commit 987cada into main Nov 16, 2026
19 checks passed
@devin-ai-integration
devin-ai-integration Bot deleted the feat/meta-sheets-fields branch November 16, 2026 03:31
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant