@vantreeseba/drizzle-graphql 7.8.0 → 7.9.0

package/README.md

@@ -945,6 +945,56 @@ supplies no `orderBy`:
 An explicit `orderBy` always takes precedence, composite primary keys are ordered by every
 key column, and an unpaginated list query is left unordered so no sort is paid for.
 
+## Default ordering
+
+A table usually has one ordering that is right nearly every time it is read — newest first,
+priority first, name alphabetical. `defaults` names that ordering once, and every query that
+does not ask for its own gets it:
+
+```ts
+buildSchema(db, {
+  defaults: {
+    Todos: { orderBy: { priority: 'desc', createdAt: 'desc' } },
+    Users: { orderBy: { name: 'asc' } },
+  },
+});
+```
+
+```graphql
+# ordered by priority desc, then createdAt desc — nothing in the query says so
+{ todos { id title } }
+```
+
+Keys are the table's key in your Drizzle schema and the column's property name, so a typo in
+either fails at `buildSchema` time rather than silently doing nothing. Each column takes
+`'asc'`, `'desc'`, or a `{ direction, priority? }` object mirroring the `orderBy` argument.
+Columns sort highest `priority` first, and the shorthand leaves it unset, so the shorthand
+falls back to the order the keys are written in — the object form is there for when you would
+rather state the precedence than depend on that:
+
+```ts
+defaults: {
+  Todos: { orderBy: { createdAt: { direction: 'desc', priority: 1 }, priority: { direction: 'desc', priority: 2 } } },
+}
+```
+
+It applies to list queries, `<tableName>Single` queries, and to-many relation fields on both
+the eager and the lazy relation paths — a relation takes the default of the table it *reads*,
+not its parent's. To-one relation fields are a single row and take no ordering.
+
+Two details worth stating plainly:
+
+-   **Any `orderBy` in the request wins outright.** The default is a fallback for a missing
+    argument, not a base that client ordering is appended to. To ask for *no* ordering, pass
+    `orderBy: {}` — an empty object is still an argument, so it suppresses the default.
+-   **A default ordering makes an unpaginated list query pay for a sort.** That is the point,
+    but it is a cost a table with no `defaults` entry does not pay; a build with no `defaults`
+    behaves exactly as before.
+
+Cursor pagination composes with it: a default-ordered page is ordered by those columns plus
+the primary key tiebreak, and its `cursor` values encode that same total order, so paging works
+without the client restating the ordering.
+
 ## Cursor pagination
 
 `OFFSET` pagination degrades linearly and shifts under concurrent writes. List queries also

package/dist/README.md

@@ -945,6 +945,56 @@ supplies no `orderBy`:
 An explicit `orderBy` always takes precedence, composite primary keys are ordered by every
 key column, and an unpaginated list query is left unordered so no sort is paid for.
 
+## Default ordering
+
+A table usually has one ordering that is right nearly every time it is read — newest first,
+priority first, name alphabetical. `defaults` names that ordering once, and every query that
+does not ask for its own gets it:
+
+```ts
+buildSchema(db, {
+  defaults: {
+    Todos: { orderBy: { priority: 'desc', createdAt: 'desc' } },
+    Users: { orderBy: { name: 'asc' } },
+  },
+});
+```
+
+```graphql
+# ordered by priority desc, then createdAt desc — nothing in the query says so
+{ todos { id title } }
+```
+
+Keys are the table's key in your Drizzle schema and the column's property name, so a typo in
+either fails at `buildSchema` time rather than silently doing nothing. Each column takes
+`'asc'`, `'desc'`, or a `{ direction, priority? }` object mirroring the `orderBy` argument.
+Columns sort highest `priority` first, and the shorthand leaves it unset, so the shorthand
+falls back to the order the keys are written in — the object form is there for when you would
+rather state the precedence than depend on that:
+
+```ts
+defaults: {
+  Todos: { orderBy: { createdAt: { direction: 'desc', priority: 1 }, priority: { direction: 'desc', priority: 2 } } },
+}
+```
+
+It applies to list queries, `<tableName>Single` queries, and to-many relation fields on both
+the eager and the lazy relation paths — a relation takes the default of the table it *reads*,
+not its parent's. To-one relation fields are a single row and take no ordering.
+
+Two details worth stating plainly:
+
+-   **Any `orderBy` in the request wins outright.** The default is a fallback for a missing
+    argument, not a base that client ordering is appended to. To ask for *no* ordering, pass
+    `orderBy: {}` — an empty object is still an argument, so it suppresses the default.
+-   **A default ordering makes an unpaginated list query pay for a sort.** That is the point,
+    but it is a cost a table with no `defaults` entry does not pay; a build with no `defaults`
+    behaves exactly as before.
+
+Cursor pagination composes with it: a default-ordered page is ordered by those columns plus
+the primary key tiebreak, and its `cursor` values encode that same total order, so paging works
+without the client restating the ordering.
+
 ## Cursor pagination
 
 `OFFSET` pagination degrades linearly and shifts under concurrent writes. List queries also

package/dist/index.cjs

@@ -1184,14 +1184,8 @@ var createRelationResolverFactory = (db, tables, nullOrdering, filterCtx, limits
     if (localValue == null) {
       return isOne ? null : [];
     }
-    const {
-      where: whereArg,
-      orderBy: orderByArg,
-      limit: requestedLimit,
-      offset,
-      after,
-      deleted
-    } = args ?? {};
+    const { where: whereArg, limit: requestedLimit, offset, after, deleted } = args ?? {};
+    const orderByArg = isOne ? args?.orderBy : withDefaultOrderBy(args ?? {}, targetTableName, policies?.defaultOrderBy).orderBy;
     const limit = applyLimitPolicy(requestedLimit, limitPolicy, `${tableName}.${relationName}`);
     const distinct = (args ?? {}).distinct?.length ? (args ?? {}).distinct : void 0;
     const cursorSelected = !isOne && !!info && selectsCursorField(info, targetTable);
@@ -1323,6 +1317,13 @@ var inputFieldDocs = (docs, column, tableName, columnName, fieldType) => {
   }
   return resolved;
 };
+var withDefaultOrderBy = (args, tableName, defaults) => {
+  if (!defaults || args?.orderBy != null) {
+    return args;
+  }
+  const fallback = defaults(tableName);
+  return fallback ? { ...args, orderBy: fallback } : args;
+};
 var applyLimitPolicy = (limit, policy, fieldName) => {
   if (!policy) {
     return limit ?? void 0;
@@ -2789,11 +2790,12 @@ var withScope = (scope, tableName, table, condition, mode) => {
   const predicate = scope?.on(tableName, table, mode);
   return predicate ? (0, import_drizzle_orm4.and)(condition, predicate) : condition;
 };
-var bindPolicies = (policies, filterCtx) => policies?.scope || policies?.contextValues || policies?.softDelete || policies?.onWrite ? {
+var bindPolicies = (policies, filterCtx) => policies?.scope || policies?.contextValues || policies?.softDelete || policies?.onWrite || policies?.defaultOrderBy ? {
   scope: policies.scope || policies.softDelete ? (context) => resolveScope(policies, context, filterCtx) : void 0,
   contextValues: policies.contextValues,
   softDelete: policies.softDelete,
-  onWrite: policies.onWrite
+  onWrite: policies.onWrite,
+  defaultOrderBy: policies.defaultOrderBy
 } : void 0;
 var applyContextValues = (values, hooks, context) => {
   if (!hooks) {
@@ -2822,7 +2824,7 @@ var stripContextValues = (values, hooks) => {
   }
   return values;
 };
-var extractRelationsParamsInner = (relationMap, tables, tableName, typeName, originField, typeNameMapper, _isInitial = false, filterCtx, limits, scope) => {
+var extractRelationsParamsInner = (relationMap, tables, tableName, typeName, originField, typeNameMapper, _isInitial = false, filterCtx, limits, scope, defaultOrderBy) => {
   const relationsForTable = relationMap[tableName];
   if (!relationsForTable) {
     return void 0;
@@ -2864,7 +2866,7 @@ var extractRelationsParamsInner = (relationMap, tables, tableName, typeName, ori
     const thisRecord = {};
     thisRecord.columns = columns;
     const relationField = Object.values(baseField).find((e) => e.name === relName);
-    const relationArgs = relationField?.args;
+    const relationArgs = (0, import_drizzle_orm4.is)(relEntry.relation, import_drizzle_orm4.One) ? relationField?.args : relationField && withDefaultOrderBy(relationField.args ?? {}, targetTableName, defaultOrderBy);
     const offset = relationArgs?.offset ?? void 0;
     const limit = (0, import_drizzle_orm4.is)(relEntry.relation, import_drizzle_orm4.One) ? relationArgs?.limit ?? void 0 : applyLimitPolicy(relationArgs?.limit, limits?.(targetTableName), `${tableName}.${relName}`);
     const relWhere = relationArgs?.where;
@@ -2893,14 +2895,15 @@ var extractRelationsParamsInner = (relationMap, tables, tableName, typeName, ori
       false,
       filterCtx,
       limits,
-      scope
+      scope,
+      defaultOrderBy
     ) : void 0;
     thisRecord.with = relWith;
     args[relName] = thisRecord;
   }
   return args;
 };
-var extractRelationsParams = (relationMap, tables, tableName, info, typeName, typeNameMapper, filterCtx, limits, scope) => {
+var extractRelationsParams = (relationMap, tables, tableName, info, typeName, typeNameMapper, filterCtx, limits, scope, defaultOrderBy) => {
   if (!info) {
     return void 0;
   }
@@ -2914,7 +2917,8 @@ var extractRelationsParams = (relationMap, tables, tableName, info, typeName, ty
     true,
     filterCtx,
     limits,
-    scope
+    scope,
+    defaultOrderBy
   );
 };
 var pruneNonEagerRelations = (relationMap, shouldEagerLoad) => {
@@ -3325,7 +3329,8 @@ var prepareMutationRelationColumns = (params) => {
     typeNameMapper,
     void 0,
     params.limits,
-    params.scope
+    params.scope,
+    params.defaultOrderBy
   ) : void 0;
   const hasRelations = !!(withParams && Object.keys(withParams).length);
   const baseColumns = extractSelectedColumnsFromTreeSQLFormat(parsedInfo.fieldsByTypeName[typeName], table, {
@@ -3667,7 +3672,8 @@ var runRelationalSelect = async (opts) => {
       typeNameMapper,
       filterCtx,
       opts.limits,
-      scope
+      scope,
+      opts.defaultOrderBy
     ) : void 0
   };
   if (single) {
@@ -4273,7 +4279,8 @@ var generateSelectArray = (db, tableName, tables, relationMap, orderArgs, filter
   );
   return {
     name: fieldName,
-    resolver: async (_source, args, context, info) => {
+    resolver: async (_source, rawArgs, context, info) => {
+      const args = withDefaultOrderBy(rawArgs, tableName, policies?.defaultOrderBy);
       try {
         const parsedInfo = (0, import_graphql_parse_resolve_info2.parseResolveInfo)(info, { deep: true });
         const { executor, queryBase: requestQueryBase } = resolveQueryExecutor(db, context, tableName, queryBase);
@@ -4291,6 +4298,7 @@ var generateSelectArray = (db, tableName, tables, relationMap, orderArgs, filter
           single: false,
           filterCtx,
           limits,
+          defaultOrderBy: policies?.defaultOrderBy,
           scope: policies?.scope?.(context),
           pkNames,
           db: executor,
@@ -4316,7 +4324,8 @@ var generateSelectSingle = (db, tableName, tables, relationMap, orderArgs, filte
   const pkNames = mysqlPrimaryKeyPropNames(table);
   return {
     name: fieldName,
-    resolver: async (_source, args, context, info) => {
+    resolver: async (_source, rawArgs, context, info) => {
+      const args = withDefaultOrderBy(rawArgs, tableName, policies?.defaultOrderBy);
       try {
         const parsedInfo = (0, import_graphql_parse_resolve_info2.parseResolveInfo)(info, { deep: true });
         const { executor, queryBase: requestQueryBase } = resolveQueryExecutor(db, context, tableName, queryBase);
@@ -4333,6 +4342,7 @@ var generateSelectSingle = (db, tableName, tables, relationMap, orderArgs, filte
           single: true,
           filterCtx,
           limits,
+          defaultOrderBy: policies?.defaultOrderBy,
           scope: policies?.scope?.(context),
           pkNames,
           db: executor
@@ -5741,7 +5751,8 @@ var generateSelectArray2 = (db, tableName, tables, relationMap, orderArgs, filte
   );
   return {
     name: fieldName,
-    resolver: async (_source, args, context, info) => {
+    resolver: async (_source, rawArgs, context, info) => {
+      const args = withDefaultOrderBy(rawArgs, tableName, policies?.defaultOrderBy);
       try {
         const parsedInfo = (0, import_graphql_parse_resolve_info3.parseResolveInfo)(info, { deep: true });
         const { executor, queryBase: requestQueryBase } = resolveQueryExecutor(db, context, tableName, queryBase);
@@ -5762,6 +5773,7 @@ var generateSelectArray2 = (db, tableName, tables, relationMap, orderArgs, filte
             single: false,
             filterCtx,
             limits,
+            defaultOrderBy: policies?.defaultOrderBy,
             pkNames,
             db: executor,
             scope,
@@ -5871,7 +5883,8 @@ var generateSelectSingle2 = (db, tableName, tables, relationMap, orderArgs, filt
   const pkNames = pgPrimaryKeyPropNames(table);
   return {
     name: fieldName,
-    resolver: async (_source, args, context, info) => {
+    resolver: async (_source, rawArgs, context, info) => {
+      const args = withDefaultOrderBy(rawArgs, tableName, policies?.defaultOrderBy);
       try {
         const parsedInfo = (0, import_graphql_parse_resolve_info3.parseResolveInfo)(info, { deep: true });
         const { executor, queryBase: requestQueryBase } = resolveQueryExecutor(db, context, tableName, queryBase);
@@ -5890,6 +5903,7 @@ var generateSelectSingle2 = (db, tableName, tables, relationMap, orderArgs, filt
             single: true,
             filterCtx,
             limits,
+            defaultOrderBy: policies?.defaultOrderBy,
             pkNames,
             db: executor,
             scope
@@ -5983,7 +5997,8 @@ var generateInsertArray2 = (db, tableName, table, tables, relationMap, baseType,
               pkNames,
               parsedInfo,
               limits,
-              scope
+              scope,
+              defaultOrderBy: policies?.defaultOrderBy
             });
             const returning = nestedEntries ? nested.withJoinColumns(tableName, mergedOps(nestedEntries), { ...columns }, table) : columns;
             const runInsert = async (target, values) => {
@@ -6073,7 +6088,8 @@ var generateInsertSingle2 = (db, tableName, table, tables, relationMap, baseType
               pkNames,
               parsedInfo,
               limits,
-              scope
+              scope,
+              defaultOrderBy: policies?.defaultOrderBy
             });
             const returning = nestedEntry ? nested.withJoinColumns(tableName, nestedEntry.ops, { ...columns }, table) : columns;
             const runInsert = async (target, values) => {
@@ -6175,7 +6191,8 @@ var generateUpsert2 = (db, tableName, table, tables, relationMap, baseType, onCo
               pkNames,
               parsedInfo,
               limits,
-              scope
+              scope,
+              defaultOrderBy: policies?.defaultOrderBy
             });
             const returning = nestedEntries ? nested.withJoinColumns(tableName, mergedOps(nestedEntries), { ...columns }, table) : columns;
             const runUpsert = async (target, values) => {
@@ -6273,7 +6290,8 @@ var generateUpdate2 = (db, tableName, table, tables, relationMap, setArgs, filte
               pkNames,
               parsedInfo,
               limits,
-              scope
+              scope,
+              defaultOrderBy: policies?.defaultOrderBy
             });
             const entry = nested?.enabled(tableName) ? nested.split(tableName, set) : void 0;
             const nestedOps = entry && nested.hasOps(entry.ops) ? entry.ops : void 0;
@@ -6387,7 +6405,8 @@ var generateUpdateMany2 = (db, tableName, table, tables, relationMap, updateMany
               pkNames,
               parsedInfo,
               limits,
-              scope
+              scope,
+              defaultOrderBy: policies?.defaultOrderBy
             });
             const entries = updates.map(({ where, set }) => {
               const split = nested?.enabled(tableName) ? nested.split(tableName, set) : void 0;
@@ -7191,7 +7210,8 @@ var generateSelectArray3 = (db, tableName, tables, relationMap, orderArgs, filte
   );
   return {
     name: fieldName,
-    resolver: async (_source, args, context, info) => {
+    resolver: async (_source, rawArgs, context, info) => {
+      const args = withDefaultOrderBy(rawArgs, tableName, policies?.defaultOrderBy);
       try {
         const parsedInfo = (0, import_graphql_parse_resolve_info4.parseResolveInfo)(info, { deep: true });
         const { executor, queryBase: requestQueryBase } = resolveQueryExecutor(db, context, tableName, queryBase);
@@ -7209,6 +7229,7 @@ var generateSelectArray3 = (db, tableName, tables, relationMap, orderArgs, filte
           single: false,
           filterCtx,
           limits,
+          defaultOrderBy: policies?.defaultOrderBy,
           pkNames,
           db: executor,
           scope: policies?.scope?.(context),
@@ -7234,7 +7255,8 @@ var generateSelectSingle3 = (db, tableName, tables, relationMap, orderArgs, filt
   const pkNames = sqlitePrimaryKeyPropNames(table);
   return {
     name: fieldName,
-    resolver: async (_source, args, context, info) => {
+    resolver: async (_source, rawArgs, context, info) => {
+      const args = withDefaultOrderBy(rawArgs, tableName, policies?.defaultOrderBy);
       try {
         const parsedInfo = (0, import_graphql_parse_resolve_info4.parseResolveInfo)(info, { deep: true });
         const { executor, queryBase: requestQueryBase } = resolveQueryExecutor(db, context, tableName, queryBase);
@@ -7251,6 +7273,7 @@ var generateSelectSingle3 = (db, tableName, tables, relationMap, orderArgs, filt
           single: true,
           filterCtx,
           limits,
+          defaultOrderBy: policies?.defaultOrderBy,
           pkNames,
           db: executor,
           scope: policies?.scope?.(context)
@@ -7315,7 +7338,8 @@ var generateInsertArray3 = (db, tableName, table, tables, relationMap, baseType,
               pkNames,
               parsedInfo,
               limits,
-              scope
+              scope,
+              defaultOrderBy: policies?.defaultOrderBy
             });
             const returning = nestedEntries ? nested.withJoinColumns(tableName, mergedOps(nestedEntries), { ...columns }, table) : columns;
             const runInsert = async (target, values) => {
@@ -7405,7 +7429,8 @@ var generateInsertSingle3 = (db, tableName, table, tables, relationMap, baseType
               pkNames,
               parsedInfo,
               limits,
-              scope
+              scope,
+              defaultOrderBy: policies?.defaultOrderBy
             });
             const returning = nestedEntry ? nested.withJoinColumns(tableName, nestedEntry.ops, { ...columns }, table) : columns;
             const runInsert = async (target, values) => {
@@ -7507,7 +7532,8 @@ var generateUpsert3 = (db, tableName, table, tables, relationMap, baseType, onCo
               pkNames,
               parsedInfo,
               limits,
-              scope
+              scope,
+              defaultOrderBy: policies?.defaultOrderBy
             });
             const returning = nestedEntries ? nested.withJoinColumns(tableName, mergedOps(nestedEntries), { ...columns }, table) : columns;
             const runUpsert = async (target, values) => {
@@ -7605,7 +7631,8 @@ var generateUpdate3 = (db, tableName, table, tables, relationMap, setArgs, filte
               pkNames,
               parsedInfo,
               limits,
-              scope
+              scope,
+              defaultOrderBy: policies?.defaultOrderBy
             });
             const entry = nested?.enabled(tableName) ? nested.split(tableName, set) : void 0;
             const nestedOps = entry && nested.hasOps(entry.ops) ? entry.ops : void 0;
@@ -7719,7 +7746,8 @@ var generateUpdateMany3 = (db, tableName, table, tables, relationMap, updateMany
               pkNames,
               parsedInfo,
               limits,
-              scope
+              scope,
+              defaultOrderBy: policies?.defaultOrderBy
             });
             const entries = updates.map(({ where, set }) => {
               const split = nested?.enabled(tableName) ? nested.split(tableName, set) : void 0;
@@ -8734,6 +8762,46 @@ var buildSchema = (db, config) => {
     limitPolicyCache.set(tableName, resolved);
     return resolved;
   } : void 0;
+  const defaultsConfig = config?.defaults;
+  const defaultOrderByByTable = /* @__PURE__ */ new Map();
+  if (defaultsConfig) {
+    const defaultsTableNames = new Set(tableKeys);
+    for (const [tableName, tableDefaults] of Object.entries(defaultsConfig)) {
+      if (!defaultsTableNames.has(tableName)) {
+        throw new Error(
+          `Drizzle-GraphQL Error: config.defaults names '${tableName}', which is not a table in the Drizzle schema.`
+        );
+      }
+      const orderBy = tableDefaults?.orderBy;
+      if (!orderBy || !Object.keys(orderBy).length) {
+        continue;
+      }
+      const columns = (0, import_drizzle_orm11.getColumns)(schema[tableName]);
+      const normalized = {};
+      for (const [columnName, entry] of Object.entries(orderBy)) {
+        if (!columns[columnName]) {
+          throw new Error(
+            `Drizzle-GraphQL Error: config.defaults.${tableName}.orderBy names '${columnName}', which is not a column of '${tableName}'.`
+          );
+        }
+        const direction = typeof entry === "string" ? entry : entry?.direction;
+        if (direction !== "asc" && direction !== "desc") {
+          throw new Error(
+            `Drizzle-GraphQL Error: config.defaults.${tableName}.orderBy.${columnName} must be 'asc', 'desc', or { direction, priority? }.`
+          );
+        }
+        const priority = typeof entry === "string" ? void 0 : entry?.priority;
+        if (priority !== void 0 && !Number.isInteger(priority)) {
+          throw new Error(
+            `Drizzle-GraphQL Error: config.defaults.${tableName}.orderBy.${columnName}.priority must be an integer.`
+          );
+        }
+        normalized[columnName] = priority === void 0 ? { direction } : { direction, priority };
+      }
+      defaultOrderByByTable.set(tableName, normalized);
+    }
+  }
+  const defaultOrderBy = defaultOrderByByTable.size ? (tableName) => defaultOrderByByTable.get(tableName) : void 0;
   const scopeConfig = config?.scope;
   const contextValuesConfig = config?.contextValues;
   if (scopeConfig || contextValuesConfig) {
@@ -8814,11 +8882,12 @@ var buildSchema = (db, config) => {
     }
   }
   const onWrite = globalWriteHooks || writeHooks.size ? (tableName) => globalWriteHooks ?? writeHooks.get(tableName) : void 0;
-  const policies = scopeConfig || contextValuesConfig || softDeleteInfos.size || onWrite ? {
+  const policies = scopeConfig || contextValuesConfig || softDeleteInfos.size || onWrite || defaultOrderBy ? {
     scope: scopeConfig ? (tableName) => scopeConfig[tableName] : void 0,
     contextValues: contextValuesConfig ? (tableName) => contextValuesConfig[tableName] : void 0,
     softDelete: softDeleteInfos.size ? (tableName) => softDeleteInfos.get(tableName) : void 0,
-    onWrite
+    onWrite,
+    defaultOrderBy
   } : void 0;
   const exclude = config?.exclude;
   if (exclude) {