makeAddPgTableOrderByPluginmakeAddPgTableOrderByPlugin 迁移
Some of the types are unchanged between V4 and V5:
以下部分类型定义在 V4 与 V5 之间保持不变:
export interface OrderByAscDescOptions {
unique?: boolean;
nulls?: NullsSortMethod;
}
export type NullsSortMethod =
| "first"
| "last"
| "first-iff-ascending"
| "last-iff-ascending"
| undefined;
The remaining (simplified) signatures for makeAddPgTableOrderByPlugin in V4 were:
V4 中 makeAddPgTableOrderByPlugin 其余相关的(简化)签名如下:
// V4 signature
function makeAddPgTableOrderByPlugin(
schemaName: string,
tableName: string,
ordersGenerator: (build: Build) => MakeAddPgTableOrderByPluginOrders,
hint?: string,
): Plugin;
export interface MakeAddPgTableOrderByPluginOrders {
[orderByEnumValue: string]: {
value: {
alias?: string;
specs: Array<OrderSpec>;
unique: boolean;
};
};
}
type OrderSpec =
| [OrderBySpecIdentity, boolean]
| [OrderBySpecIdentity, boolean, boolean];
type OrderBySpecIdentity =
| string
| SQL
| ((options: { queryBuilder: QueryBuilder }) => SQL);
export function orderByAscDesc(
baseName: string,
columnOrSqlFragment: OrderBySpecIdentity,
uniqueOrOptions: boolean | OrderByAscDescOptions = false,
): MakeAddPgTableOrderByPluginOrders;
In V5, the signature has changed a little.
到了 V5,这些签名发生了一些调整。
The first change is trivial: we've combined the first two arguments into a
"match" object which also optionally accepts the serviceName.
第一个变化很直观:原来的前两个参数被合并成了一个“匹配(match)”对象,且该对象还支持可选的 serviceName 属性。
The ordersGenerator has changed a bit more though:
而 ordersGenerator 的改动相对大一些:
-
orderByAscDesc's callback now acceptsqueryBuilderdirectly rather than extracting it from an objectorderByAscDesc的回调函数现在直接接收queryBuilder作为参数,不再需要从配置对象中解构获取; -
queryBuilder.getTableAlias()is now justqueryBuilder.aliasqueryBuilder.getTableAlias()已简化为queryBuilder.alias属性; -
sqlValueWithCodec(value, codec)should be used oversql.value(value)as it will take care of casting the value according to the rules ofcodec应优先使用
sqlValueWithCodec(value, codec)而非sql.value(value),因为它会依据codec的规则自动完成值类型转换; -
The return type of
orderByAscDesc's callback is now an object containing thefragmentalongside thecodecthat tells the system what type of data the fragment represents (int/bigint/text/etc).orderByAscDesc回调函数的返回值类型现在是一个包含fragment和codec的对象,其中codec用于告知系统该 SQL 片段所代表的数据类型(如 int、bigint、text 等)。
The (simplified) new signatures are:
V5 中的(简化)新签名如下:
export function addPgTableOrderBy(
match: {
serviceName?: string;
schemaName: string;
tableName: string;
},
ordersGenerator: (
build: GraphileBuild.Build,
) => MakeAddPgTableOrderByPluginOrders,
hint?: string,
): GraphileConfig.Plugin;
export interface MakeAddPgTableOrderByPluginOrders {
[orderByEnumValue: string]: GraphQLEnumValueConfig;
}
type OrderBySpecIdentity =
| string // Column name
| Omit<PgOrderSpec, "direction"> // Expression
| ((
queryBuilder: PgSelectQueryBuilder,
info: { scope: unknown },
) => Omit<PgOrderSpec, "direction">); // Callback, allows for joins/etc
export function orderByAscDesc(
baseName: string,
attributeOrSqlFragment: OrderBySpecIdentity,
uniqueOrOptions: boolean | OrderByAscDescOptions = false,
): MakeAddPgTableOrderByPluginOrders;
Example 1示例 1
V4:
const OrderByAveragePetIdPlugin = makeAddPgTableOrderByPlugin(
"graphile_utils",
"users",
(build) => {
const { pgSql: sql } = build;
const sqlIdentifier = sql.identifier(Symbol("pet"));
const customOrderBy = orderByAscDesc(
"PET_ID_AVERAGE", // this is a ridiculous and unrealistic column but it will serve for testing purposes
(helpers) => {
const { queryBuilder } = helpers;
const orderByFrag = sql.fragment`(
select avg(${sqlIdentifier}.id)
from graphile_utils.pets as ${sqlIdentifier}
where ${sqlIdentifier}.user_id = ${queryBuilder.getTableAlias()}.id
)`;
return orderByFrag;
},
{ nulls: "last-iff-ascending" },
);
return customOrderBy;
},
);
V5:
const OrderByAveragePetIdPlugin = addPgTableOrderBy(
{ schemaName: "graphile_utils", tableName: "users" },
(build) => {
const { sql } = build;
const sqlIdentifier = sql.identifier(Symbol("pet"));
const customOrderBy = orderByAscDesc(
"PET_ID_AVERAGE", // this is a ridiculous and unrealistic column but it will serve for testing purposes
(queryBuilder) => {
const orderByFrag = sql`(
select avg(${sqlIdentifier}.id)
from graphile_utils.pets as ${sqlIdentifier}
where ${sqlIdentifier}.user_id = ${queryBuilder.alias}.id
)`;
return { fragment: orderByFrag, codec: TYPES.int };
},
{ nulls: "last-iff-ascending" },
);
return customOrderBy;
},
);
Example 2示例 2
V4:
const OrderByMemberNamePlugin = makeAddPgTableOrderByPlugin(
"app_public",
"organization_memberships",
({ pgSql: sql }) => {
const sqlIdentifier = sql.identifier(Symbol("member"));
return orderByAscDesc(
"MEMBER_NAME",
// Order fragment callback:
({ queryBuilder }) => {
return sql.fragment`(
select ${sqlIdentifier}.name
from app_public.users as ${sqlIdentifier}
where ${sqlIdentifier}.id = ${queryBuilder.getTableAlias()}.user_id
limit 1
)`;
},
);
},
);
V5:
const OrderByMemberNamePlugin = addPgTableOrderBy(
{ schemaName: "app_public", tableName: "organization_memberships" },
({ sql }) => {
const sqlIdentifier = sql.identifier(Symbol("member"));
return orderByAscDesc(
"MEMBER_NAME",
// Order spec callback:
(queryBuilder) => {
const fragment = sql.fragment`(
select ${sqlIdentifier}.name
from app_public.users as ${sqlIdentifier}
where ${sqlIdentifier}.id = ${queryBuilder.alias}.user_id
limit 1
)`;
return {
fragment,
codec: TYPES.text,
};
},
);
},
);
V5 (alternative solution, using joins which were not possible in V4):
V5(替代方案:使用 V4 中尚不支持的 join 表连接):
const OrderByMemberNamePlugin = addPgTableOrderBy(
{ schemaName: "app_public", tableName: "organization_memberships" },
(build) => {
const {
sql,
input: {
pgRegistry: { pgResources },
},
} = build;
const usersSource = pgResources.find((s) => s.name === "users");
if (!usersSource) throw new Error(`Couldn't find users source`);
const sqlIdentifier = sql.identifier(Symbol("member"));
return orderByAscDesc(
"MEMBER_NAME",
// Order spec callback:
(queryBuilder) => {
queryBuilder.join({
type: "inner",
source: usersSource.source as SQL,
alias: sqlIdentifier,
conditions: [
sql`${sqlIdentifier}.id = ${queryBuilder.alias}.user_id`,
],
});
return {
fragment: sql`${sqlIdentifier}.name`,
codec: usersSource.codec.columns["name"].codec,
};
},
);
},
);