@graphile/simplify-inflection

中文文档
9.0.1发布于 2026/10/30MITTypeScriptCommonJS零依赖构建来源已验证近 30 天下载 17.6万

Simplifies the graphile-build/graphile-build-pg inflection to trim the ByFooIdAndBarId from relations, etc

原始使用文档
文档目录9 节
  1. Incompatible database schemas
  2. Customising
  3. Changes:
  4. Installation:
  5. Usage:
  6. Naming your foreign key fields
  7. Handling field conflicts:
  8. Smart Tags
  9. @listSuffix

@graphile/simplify-inflection

GitHub Sponsors Discord chat room Follow Follow

This preset simplifies field names in the PostGraphile schema; e.g. allUsers becomes simply users, User.postsByAuthorId becomes simply User.posts, and Post.userByAuthorId becomes simply Post.author.

Adding this preset to your schema is almost certainly a breaking change, so do it before you ship anything!

This preset is recommended for all PostGraphile users with a compatible database schema. The main reason this preset is not enabled by default is because it increases the risk of conflicts where multiple relationships try and use the same field name, and because some people name their primary key and foreign key columns in a way that would cause conflicts. Conflicts can be avoided by careful use of naming conventions or by specifically tagging the conflicting relations with their preferred name.

Incompatible database schemas

This plugin assumes that your primary key and foreign key columns are:

  • named id, uuid, or pk; or
  • named ending in _id, _uuid, or _pk; or
  • named ending in Id, Uuid, or Pk.

If your database schema uses a different naming convention (and particularly if you name the primary key after the table itself, or the singularized version of it, with no prefix or suffix) then you are likely to receive a lot of naming conflicts if you use this plugin. If you are affected by this, this plugin is probably not for you (but feel free to fork it and make changes to accomodate your schemas naming conventions); however you may have luck using the "postgraphile/presets/relay" preset which hides primary key and foreign key columns throughout the schema, reducing the sources for these conflicts.

Customising

This preset is just one file, simply copy it into your project and customise it as you see fit.

Alternatively, you can write your own inflection plugin.

Changes:

Given these tables:

create table companies (
  id serial primary key,
  name text not null
);
create table beverages (
  id serial primary key,
  company_id int not null references companies,
  distributor_id int references companies,
  name text not null
);
  • Query.allCompanies 👉 Query.companies (disable via pgSimplifyAllRows = false)
  • Query.allBeverages 👉 Query.beverages
  • Beverage.companyByCompanyId 👉 Beverage.company
  • Beverage.companyByDistributorId 👉 Beverage.distributor
  • Company.beveragesByCompanyId 👉 Company.beverages (because the company_id column follows the [table_name]_id naming convention)
  • All update mutations now accept patch instead of companyPatch / beveragePatch (disable via pgSimplifyPatch = false)
  • If you prefer lists then you can use pgOmitListSuffix = true to omit the List suffix, and instead append Connection to connections
  • Fields where the singular and plural are the same and a distinct plural is required are force-pluralised ("fishes") to avoid conflicts (e.g. singularize("fish") === pluralize("fish")).

Note: Company.beveragesByDistributorId will remain, because distributor_id does not follow the [table_name]_id naming convention, but you could rename this yourself with a smart comment:

comment on constraint "beverages_distributor_id_fkey" on "beverages" is
  E'@foreignFieldName distributedBeverages';

or with a custom inflector plugin:

const plugin = {
  name: "MyCustomInflectionPlugin",
  version: "0.0.0",
  inflection: {
    replace: {
      getOppositeBaseName(previous, options, baseName) {
        return (
          {
            // These are the default opposites
            parent: "child",
            child: "parent",
            author: "authored",
            editor: "edited",
            reviewer: "reviewed",

            // 👇 Add/customise this line:
            distributor: "distributed",
          }[baseName] || previous(baseName)
        );
      },
    },
  },
};

Installation:

yarn add @graphile/simplify-inflection

or

npm install --save @graphile/simplify-inflection

Usage:

Add the preset to your Graphile Config file, under presets:

// graphile.config.mjs or similar

import { PgSimplifyInflectionPreset } from "@graphile/simplify-inflection";

export default {
  extends: [
    // ... (PostGraphileAmber, etc)
    PgSimplifyInflectionPreset,
  ],

  schema: {
    // ...
    /*
     * Uncomment if you want simple collections to lose the 'List' suffix
     * (and connections to gain a 'Connection' suffix).
     */
    //pgOmitListSuffix: true,
    /*
     * Uncomment if you want 'userPatch' instead of 'patch' in update
     * mutations.
     */
    //pgSimplifyPatch: false,
    /*
     * Uncomment if you want 'allUsers' instead of 'users' at root level.
     */
    //pgSimplifyAllRows: false,
    /*
     * Uncomment if you want primary key queries and mutations to have
     * `ById` (or similar) suffix; and the `nodeId` queries/mutations
     * to lose their `ByNodeId` suffix.
     */
    // pgShortPk: false,
  },
};

Naming your foreign key fields

By naming your foreign key along the lines of author_id or author_fk, e.g.:

CREATE TABLE posts (
  id serial primary key,
  author_id int not null references users,
  ...
);

We can automatically extract the field prefix: author and call the relation author rather than the default: user. This allows for a post to have an author, editor, reviewer, etc. all which point to users.

The reverse, however, is not so easy. On the User type, we can't call the reverse of all these different relations posts. The default inflector refers to these as postsByAuthorId, postsByEditorId, etc. However we'd rather use shorter names, so we introduce a new inflector: getOppositeBaseName. This inflector is passed a baseName (the part without the _id/_fk suffix, e.g. author, editor, reviewer above) and should return the opposite of that base name which will be prepended to the target type to produce, e.g. authoredPosts, editedPosts, reviewedPosts. Failing this, we just fall back to the default (verbose) inflector; it will be up to you to add smart comments or a custom inflector to override these.

Handling field conflicts:

In most cases, the conflict errors will guide you on how to fix these issues using smart comments.

Smart Tags

@listSuffix

@listSuffix allows you to override the default naming on a per-entity basis, overriding pgOmitListSuffix. For example, with pgOmitListSuffix: true, you can apply @listSuffix include to have the -List suffix appended to the simple collection generated for that table, and remove the -Connection suffix from the Relay connection. When pgOmitListSuffix is not true, you can use @listSuffix omit to selectively omit the -List suffix on simple collections and append -Connection to the Relay connection instead.

If @listSuffix is set, the only valid values are "omit" and "include". Any other value will cause an error.

@listSuffix omit@listSuffix include
Relay ConnectioncompaniesConnectioncompanies
Simple CollectioncompaniescompaniesList

NOTE: @listSuffix will have no effect when using @foreignSimpleFieldName.

Applies to:

  • tables
  • foreign key constraints
  • computed column functions returning SETOF <record type>

版本与发布记录

@graphile/simplify-inflection 共发布 45 个版本,首次发布于 2023/02/04;过去 12 个月发布了 26 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
9.0.1latest2026/10/3017 天前
9.0.1-aardvark.next-20260928202932snapshot-next2026/09/291 个月前
9.0.1-aardvark.next-202609251642492026/09/261 个月前
9.0.1-aardvark.next-202609222244162026/09/231 个月前
9.0.1-aardvark.next-202609191851302026/09/201 个月前
9.0.1-aardvark.next-202609180853272026/09/181 个月前

其他发布通道:prealpha → 8.0.0-alpha.1,alpha → 8.0.0-alpha.4,beta → 8.0.0-beta.8,rc → 8.0.0-rc.5,snapshot-next → 9.0.1-aardvark.next-20260928202932。

关于 @graphile/simplify-inflection 的常见问题

@graphile/simplify-inflection 是什么?

Simplifies the graphile-build/graphile-build-pg inflection to trim the ByFooIdAndBarId from relations, etc

如何安装 @graphile/simplify-inflection?

在项目目录运行 npm install @graphile/simplify-inflection,或使用 pnpm add / yarn add / bun add。

@graphile/simplify-inflection 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@graphile/simplify-inflection 支持 ESM 还是 CommonJS?

以 CommonJS 形式发布,可以直接 require();在 ES Module 项目中也可以用 import 引入(Node.js 会把 module.exports 作为默认导出)。

@graphile/simplify-inflection 可以商用吗?

@graphile/simplify-inflection 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@graphile/simplify-inflection 的下载量有多少?

根据 npm 官方下载统计,@graphile/simplify-inflection 在 2026/10/17 – 2026/11/15 这 30 天内被下载 175,600 次,日均约 5,853 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@graphile/simplify-inflection 还在维护吗?

最新版本 9.0.1 发布于 2026/10/30(17 天前);至今共发布 45 个版本,其中过去 12 个月发布了 26 个;首次发布于 2023/02/04。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。