@simtlix/simfinity-core 3.2.0

package/src/auth/rules.js

@@ -0,0 +1,300 @@
+import { UnauthenticatedError, ForbiddenError } from './errors.js';
+import { normalizeObjectId } from './object-id.js';
+
+/**
+ * Resolves a value from an object using a dotted path string or function.
+ * @param {Object} obj - The object to resolve from
+ * @param {string|Function} pathOrFn - Dotted path (e.g., 'user.profile.id') or function to extract value
+ * @returns {*} The resolved value or undefined if not found
+ * @example
+ * resolvePath({ user: { id: '123' } }, 'user.id') // returns '123'
+ * resolvePath({ user: { id: '123' } }, (obj) => obj.user.id) // returns '123'
+ */
+export const resolvePath = (obj, pathOrFn) => {
+  if (typeof pathOrFn === 'function') {
+    return pathOrFn(obj);
+  }
+  if (typeof pathOrFn === 'string') {
+    const parts = pathOrFn.split('.');
+    let value = obj;
+    for (const part of parts) {
+      if (value == null) return undefined;
+      value = value[part];
+    }
+    return value;
+  }
+  return undefined;
+};
+
+/**
+ * Rule that requires the user to be authenticated
+ * Checks for user existence at the specified path in context
+ * @param {string|Function} [userPath='user'] - Path to user in context (e.g., 'user', 'auth.user', 'session.user')
+ * @returns {Function} Rule function (parent, args, ctx, info) => boolean | throws
+ * @example
+ * requireAuth()                    // checks ctx.user
+ * requireAuth('auth.user')         // checks ctx.auth.user
+ * requireAuth('session.currentUser') // checks ctx.session.currentUser
+ */
+export const requireAuth = (userPath = 'user') => {
+  return (_parent, _args, ctx) => {
+    if (!ctx) {
+      throw new UnauthenticatedError('You must be logged in to access this resource');
+    }
+    const user = resolvePath(ctx, userPath);
+    if (!user) {
+      throw new UnauthenticatedError('You must be logged in to access this resource');
+    }
+    return true;
+  };
+};
+
+/**
+ * Rule that requires the user to have a specific role
+ * @param {string|string[]} role - Required role or array of roles (any match)
+ * @param {Object} [options] - Configuration options
+ * @param {string|Function} [options.userPath='user'] - Path to user in context
+ * @param {string|Function} [options.rolePath='role'] - Path to role field in user object
+ * @returns {Function} Rule function (parent, args, ctx, info) => boolean | throws
+ * @example
+ * requireRole('ADMIN')
+ * requireRole(['ADMIN', 'EDITOR'])
+ * requireRole('ADMIN', { userPath: 'auth.user', rolePath: 'roles.primary' })
+ */
+export const requireRole = (role, options = {}) => {
+  const roles = Array.isArray(role) ? role : [role];
+  if (roles.length === 0 || Array.from(roles).some(value => typeof value !== 'string' || value.length === 0)) {
+    throw new TypeError('Required roles must be a nonempty string or array of nonempty strings');
+  }
+  const { userPath = 'user', rolePath = 'role' } = options;
+
+  return (_parent, _args, ctx) => {
+    if (!ctx) {
+      throw new UnauthenticatedError('You must be logged in to access this resource');
+    }
+    const user = resolvePath(ctx, userPath);
+    if (!user) {
+      throw new UnauthenticatedError('You must be logged in to access this resource');
+    }
+
+    const userRole = resolvePath(user, rolePath);
+
+    if (!roles.includes(userRole)) {
+      throw new ForbiddenError(`Requires role: ${roles.join(' or ')}`);
+    }
+
+    return true;
+  };
+};
+
+/**
+ * Rule that requires the user to have a specific permission
+ * @param {string|string[]} permission - Required permission(s) (all must match if array)
+ * @param {Object} [options] - Configuration options
+ * @param {string|Function} [options.userPath='user'] - Path to user in context
+ * @param {string|Function} [options.permissionsPath='permissions'] - Path to permissions array in user object
+ * @returns {Function} Rule function (parent, args, ctx, info) => boolean | throws
+ * @example
+ * requirePermission('posts:read')
+ * requirePermission(['posts:read', 'posts:write'])
+ * requirePermission('posts:read', { userPath: 'auth.user', permissionsPath: 'grants' })
+ */
+export const requirePermission = (permission, options = {}) => {
+  const requiredPermissions = Array.isArray(permission) ? permission : [permission];
+  if (requiredPermissions.length === 0
+    || Array.from(requiredPermissions).some(perm => typeof perm !== 'string' || perm.length === 0)) {
+    throw new TypeError('Required permissions must be a nonempty string or array of nonempty strings');
+  }
+  const { userPath = 'user', permissionsPath = 'permissions' } = options;
+
+  return (_parent, _args, ctx) => {
+    if (!ctx) {
+      throw new UnauthenticatedError('You must be logged in to access this resource');
+    }
+    const user = resolvePath(ctx, userPath);
+    if (!user) {
+      throw new UnauthenticatedError('You must be logged in to access this resource');
+    }
+
+    const userPermissions = resolvePath(user, permissionsPath);
+    if (!Array.isArray(userPermissions)
+      || Array.from(userPermissions).some(perm => typeof perm !== 'string' || perm.length === 0)) {
+      throw new ForbiddenError('User permissions must be an array of nonempty strings');
+    }
+
+    // Check if user has wildcard permission
+    if (userPermissions.includes('*')) {
+      return true;
+    }
+
+    // All required permissions must be present
+    for (const perm of requiredPermissions) {
+      if (!userPermissions.includes(perm)) {
+        throw new ForbiddenError(`Missing permission: ${perm}`);
+      }
+    }
+
+    return true;
+  };
+};
+
+/**
+ * Composes multiple rules - all must pass (logical AND)
+ * @param  {...Function} rules - Rule functions to compose
+ * @returns {Function} Composed rule function
+ */
+export const composeRules = (...rules) => {
+  if (rules.some(rule => typeof rule !== 'function')) {
+    throw new TypeError('composeRules requires rule functions');
+  }
+  return async (parent, args, ctx, info) => {
+    for (const rule of rules) {
+      const result = await rule(parent, args, ctx, info);
+      // Only true or void grants access, consistently with direct rules.
+      if (result !== true && result !== undefined) {
+        return false;
+      }
+      // If rule throws, it will propagate
+    }
+    return true;
+  };
+};
+
+/**
+ * Creates a rule that allows access if ANY of the provided rules pass (logical OR)
+ * @param  {...Function} rules - Rule functions to check
+ * @returns {Function} Combined rule function
+ */
+export const anyRule = (...rules) => {
+  if (rules.some(rule => typeof rule !== 'function')) {
+    throw new TypeError('anyRule requires rule functions');
+  }
+  return async (parent, args, ctx, info) => {
+    let lastError = null;
+
+    for (const rule of rules) {
+      try {
+        const result = await rule(parent, args, ctx, info);
+        if (result === true || result === undefined) {
+          return true; // At least one rule passed
+        }
+      } catch (error) {
+        lastError = error;
+        // Continue to next rule
+      }
+    }
+
+    // No rule passed - throw the last error or return false
+    if (lastError) {
+      throw lastError;
+    }
+    return false;
+  };
+};
+
+const normalizeOwnerId = (value) => {
+  if (typeof value === 'string' && value.length > 0) return value;
+  if (typeof value === 'number' && Number.isFinite(value)) return String(value);
+  return normalizeObjectId(value);
+};
+
+/**
+ * Creates a rule that checks if the authenticated user owns the resource
+ * @param {string|Function} [ownerField='userId'] - Path to owner ID in parent, or function to extract it
+ * @param {string|Function} [userIdField='id'] - Path to user ID in user object, or function to extract it
+ * @param {Object} [options] - Configuration options
+ * @param {string|Function} [options.userPath='user'] - Path to user in context
+ * @returns {Function} Rule function
+ * @example
+ * isOwner()                                    // compares parent.userId with ctx.user.id
+ * isOwner('authorId')                          // compares parent.authorId with ctx.user.id
+ * isOwner('author.id', 'profile.id')           // compares parent.author.id with ctx.user.profile.id
+ * isOwner('authorId', 'id', { userPath: 'auth.user' }) // uses ctx.auth.user instead of ctx.user
+ */
+export const isOwner = (ownerField = 'userId', userIdField = 'id', options = {}) => {
+  const { userPath = 'user' } = options;
+
+  return (parent, _args, ctx) => {
+    if (!ctx) {
+      throw new UnauthenticatedError('You must be logged in to access this resource');
+    }
+    const user = resolvePath(ctx, userPath);
+    if (!user) {
+      throw new UnauthenticatedError('You must be logged in to access this resource');
+    }
+
+    // Get ownerId from parent (using path or function)
+    const ownerId = normalizeOwnerId(resolvePath(parent, ownerField));
+
+    // Get userId from user object (using path or function)
+    const userId = normalizeOwnerId(resolvePath(user, userIdField));
+
+    if (ownerId === undefined || userId === undefined) {
+      return false;
+    }
+
+    return ownerId === userId;
+  };
+};
+
+/**
+ * Creates a custom rule from a predicate function
+ * @param {Function} predicate - Function returning true/void to allow, or throwing to deny
+ * @param {string} errorMessage - Error message if rule fails
+ * @param {string} errorCode - Error code (FORBIDDEN or UNAUTHENTICATED)
+ * @returns {Function} Rule function
+ */
+export const createRule = (predicate, errorMessage = 'Access denied', errorCode = 'FORBIDDEN') => {
+  if (typeof predicate !== 'function') {
+    throw new TypeError('createRule requires a predicate function');
+  }
+  return async (parent, args, ctx, info) => {
+    const result = await predicate(parent, args, ctx, info);
+
+    if (result !== true && result !== undefined) {
+      if (errorCode === 'UNAUTHENTICATED') {
+        throw new UnauthenticatedError(errorMessage);
+      }
+      throw new ForbiddenError(errorMessage);
+    }
+
+    return true;
+  };
+};
+
+/**
+ * Rule that always allows access (useful for public fields)
+ * @returns {Function} Rule function that always returns true
+ */
+export const allow = () => {
+  return () => true;
+};
+
+/**
+ * Rule that always denies access
+ * @param {string} message - Optional denial message
+ * @returns {Function} Rule function that always throws ForbiddenError
+ */
+export const deny = (message = 'Access denied') => {
+  return () => {
+    throw new ForbiddenError(message);
+  };
+};
+
+// Export all rules as an object for convenience
+const rules = {
+  // Utility
+  resolvePath,
+  // Rule helpers
+  requireAuth,
+  requireRole,
+  requirePermission,
+  composeRules,
+  anyRule,
+  isOwner,
+  createRule,
+  allow,
+  deny,
+};
+
+export default rules;

package/src/const/QLOperator.js

@@ -0,0 +1,19 @@
+import { GraphQLEnumType } from 'graphql';
+
+const QLOperator = new GraphQLEnumType({
+  name: 'QLOperator',
+  values: {
+    EQ: { value: 'EQ' },
+    LT: { value: 'LT' },
+    GT: { value: 'GT' },
+    LTE: { value: 'LTE' },
+    GTE: { value: 'GTE' },
+    BTW: { value: 'BTW' },
+    NE: { value: 'NE' },
+    IN: { value: 'IN' },
+    NIN: { value: 'NIN' },
+    LIKE: { value: 'LIKE' },
+  },
+});
+
+export default QLOperator;

package/src/const/QLSort.js

@@ -0,0 +1,24 @@
+import {
+  GraphQLInputObjectType,
+  GraphQLNonNull,
+  GraphQLEnumType,
+  GraphQLString,
+} from 'graphql';
+
+const QLSortOrder = new GraphQLEnumType({
+  name: 'QLSortOrder',
+  values: {
+    DESC: { value: 'DESC' },
+    ASC: { value: 'ASC' },
+  },
+});
+
+const QLSort = new GraphQLInputObjectType({
+  name: 'QLSort',
+  fields: () => ({
+    field: { type: new GraphQLNonNull(GraphQLString) },
+    order: { type: new GraphQLNonNull(QLSortOrder) },
+  }),
+});
+
+export default QLSort;

package/src/const/QLValue.js

@@ -0,0 +1,32 @@
+import { GraphQLScalarType, Kind } from 'graphql';
+import SimfinityError from '../errors/simfinity.error.js';
+
+const parseQLValue = (value) => value;
+
+const parseLiteral = (ast) => {
+  switch (ast.kind) {
+    case Kind.INT: return parseInt(ast.value, 10);
+    case Kind.FLOAT: return parseFloat(ast.value);
+    case Kind.BOOLEAN: return ast.value === true || ast.value === 'true';
+    case Kind.STRING: return ast.value;
+    case Kind.NULL: return null;
+    case Kind.LIST:
+      return ast.values.map((item) => {
+        if (item.kind === Kind.LIST) {
+          throw new SimfinityError('Nested filter value lists are not supported', 'INVALID_FILTER_VALUE', 400);
+        }
+        return parseLiteral(item);
+      });
+    default:
+      throw new SimfinityError('Filter values must be scalars or flat scalar lists', 'INVALID_FILTER_VALUE', 400);
+  }
+};
+
+const QLValue = new GraphQLScalarType({
+  name: 'QLValue',
+  serialize: parseQLValue,
+  parseValue: parseQLValue,
+  parseLiteral,
+});
+
+export default QLValue;

package/src/errors/internal-server.error.js

@@ -0,0 +1,11 @@
+import SimfinityError from './simfinity.error.js';
+
+class InternalServerError extends SimfinityError {
+  constructor(message, cause) {
+    super(message, 'INTERNAL_SERVER_ERROR');
+    this.cause = cause;
+    this.getCause = () => this.cause;
+  }
+}
+
+export default InternalServerError;

package/src/errors/simfinity.error.js

@@ -0,0 +1,15 @@
+class SimfinityError extends Error {
+  constructor(message, code, status) {
+    super(message);
+    this.extensions = {
+      code,
+      status,
+      timestamp: new Date().toUTCString(),
+    };
+    this.getCode = () => this.extensions.code;
+    this.getStatus = () => this.extensions.status;
+    this.getTimestamp = () => this.extensions.timestamp;
+  }
+}
+
+export default SimfinityError;

package/src/index.js

@@ -0,0 +1,17 @@
+export { describeModels } from './metadata.js';
+export { default as SimfinityError } from './errors/simfinity.error.js';
+export { createValidatedScalar } from './scalars/factory.js';
+export {
+  createRuntime,
+  buildErrorFormatter,
+  InternalServerError,
+} from './runtime.js';
+export { createQueryPlan, resolveModelPath } from './query-plan.js';
+export { default as QLOperator } from './const/QLOperator.js';
+export { default as QLSort } from './const/QLSort.js';
+export { default as QLValue } from './const/QLValue.js';
+export { configureQueryLimits, paginationStages } from './query-limits.js';
+export { default as auth } from './auth/index.js';
+export { default as plugins } from './plugins.js';
+export { default as scalars } from './scalars.js';
+export { default as validators } from './validators.js';

package/src/introspection.js

@@ -0,0 +1,37 @@
+import {
+  GraphQLBoolean,
+  GraphQLObjectType,
+  GraphQLString,
+  __Field,
+} from 'graphql';
+
+// getFields() supports both lazy and already materialized introspection fields.
+// Reuse the shared field on repeated module evaluation to preserve type identity.
+const introspectionFields = __Field.getFields();
+if (!introspectionFields.extensions) {
+  const RelationType = new GraphQLObjectType({
+    name: 'RelationType',
+    fields: () => ({
+      embedded: { type: GraphQLBoolean },
+      connectionField: { type: GraphQLString },
+      displayField: { type: GraphQLString },
+    }),
+  });
+
+  const FieldExtensionsType = new GraphQLObjectType({
+    name: 'FieldExtensionsType',
+    fields: () => ({
+      relation: { type: RelationType },
+      stateMachine: { type: GraphQLBoolean },
+      readOnly: { type: GraphQLBoolean },
+    }),
+  });
+
+  introspectionFields.extensions = {
+    type: FieldExtensionsType,
+    name: 'extensions',
+    resolve: (obj) => obj.extensions,
+    args: [],
+    isDeprecated: false,
+  };
+}

package/src/metadata.js

@@ -0,0 +1,140 @@
+import {
+  isObjectType, isScalarType, isEnumType, isNonNullType, isListType,
+} from 'graphql';
+import SimfinityError from './errors/simfinity.error.js';
+
+const invalid = (message) => {
+  throw new SimfinityError(message, 'INVALID_MODEL', 400);
+};
+
+const unwrap = (type) => {
+  const required = isNonNullType(type);
+  const outer = required ? type.ofType : type;
+  const list = isListType(outer);
+  const item = list ? outer.ofType : outer;
+  const itemRequired = list && isNonNullType(item);
+  const named = isNonNullType(item) ? item.ofType : item;
+  if (isListType(named)) invalid('Nested scalar/object lists are not supported');
+  return { named, required, list, itemRequired };
+};
+
+const scalarDescription = (type) => {
+  if (isEnumType(type)) {
+    const storedValues = new Map();
+    for (const entry of type.getValues()) {
+      const stored = String(entry.value);
+      if (storedValues.has(stored) && !Object.is(storedValues.get(stored), entry.value)) invalid(`Enum storage collision in ${type.name}: distinct internal values serialize to ${stored}`);
+      storedValues.set(stored, entry.value);
+    }
+    return { scalar: 'Enum', values: [...storedValues.keys()], enumValues: type.getValues().map(({ name, value }) => ({ name, value })) };
+  }
+  let base = type;
+  const visited = new Set();
+  while (base.baseScalarType) {
+    if (visited.has(base)) invalid(`Cyclic base scalar ${type.name}`);
+    visited.add(base);
+    base = base.baseScalarType;
+  }
+  const scalar = ['DateTime', 'Date', 'Time'].includes(base.name) ? 'DateTime' : base.name;
+  if (!['String', 'ID', 'Int', 'Float', 'Boolean', 'DateTime'].includes(scalar)) {
+    invalid(`Unsupported scalar ${type.name}: declare a supported baseScalarType`);
+  }
+  return { scalar };
+};
+
+/** Describe persistent entities without importing a database driver or mutating GraphQL types. */
+export const describeModels = (registrations) => {
+  if (!Array.isArray(registrations)) invalid('registrations must be an array');
+  const knownTypes = new Map();
+  const entities = new Map();
+  const queue = [];
+  const registerType = (type) => {
+    if (!isObjectType(type)) invalid('Each registration must contain a GraphQLObjectType in gqltype');
+    if (knownTypes.has(type.name) && knownTypes.get(type.name) !== type) invalid(`Conflicting GraphQL types named ${type.name}`);
+    knownTypes.set(type.name, type);
+  };
+  const addEntity = (type) => {
+    registerType(type);
+    if (!entities.has(type.name)) {
+      entities.set(type.name, { name: type.name, gqltype: type, fields: [], indexes: [] });
+      queue.push(type);
+    }
+  };
+  for (const registration of registrations) registerType(registration.gqltype);
+  for (const registration of registrations) if (registration.endpoint !== false) addEntity(registration.gqltype);
+
+  const fieldsOf = (type, ancestors, path, embedded = false) => {
+    if (ancestors.includes(type)) invalid(`Embedded cycle at ${path}`);
+    registerType(type);
+    const fields = Object.values(type.getFields()).map((field) => {
+      const { named, ...wrappers } = unwrap(field.type);
+      const extensions = field.extensions || {};
+      const descriptor = {
+        name: field.name, storageName: field.name, ...wrappers,
+        unique: extensions.unique === true, readOnly: extensions.readOnly === true,
+      };
+      if (isScalarType(named) || isEnumType(named)) {
+        return { ...descriptor, kind: 'scalar', ...scalarDescription(named) };
+      }
+      if (!isObjectType(named)) invalid(`Unsupported field type at ${path}.${field.name}`);
+      const relation = extensions.relation;
+      if (!relation) invalid(`${path}.${field.name} requires extensions.relation`);
+      if (relation.embedded) {
+        return {
+          ...descriptor, kind: 'embedded',
+          fields: fieldsOf(named, [...ancestors, type], `${path}.${field.name}`, true),
+        };
+      }
+      addEntity(named);
+      if (wrappers.list) {
+        if (!relation.connectionField) invalid(`${path}.${field.name} requires a child connectionField`);
+        if (embedded) invalid(`Non-embedded collections inside embedded objects are not supported: ${path}.${field.name}`);
+        return { ...descriptor, kind: 'collection', target: named.name, connectionField: relation.connectionField };
+      }
+      return { ...descriptor, kind: 'reference', target: named.name, storageName: relation.connectionField || field.name };
+    });
+    const storage = new Set();
+    for (const field of fields.filter((item) => item.kind !== 'collection')) {
+      if (storage.has(field.storageName)) invalid(`Storage collision at ${path}.${field.storageName}`);
+      storage.add(field.storageName);
+    }
+    return fields;
+  };
+
+  for (let position = 0; position < queue.length; position += 1) {
+    const type = queue[position];
+    const entity = entities.get(type.name);
+    entity.fields = fieldsOf(type, [], type.name);
+    entity.indexes = (type.extensions?.indexes || []).map((index) => {
+      if (!Array.isArray(index.fields) || !index.fields.length || new Set(index.fields).size !== index.fields.length) {
+        invalid(`Invalid index on ${type.name}: fields must be a nonempty list of distinct field names`);
+      }
+      return { fields: [...index.fields], unique: index.unique === true };
+    });
+  }
+  for (const entity of entities.values()) {
+    for (const field of entity.fields.filter((item) => item.kind === 'collection')) {
+      const child = entities.get(field.target);
+      if (child.fields.some((item) => item.name === field.connectionField && item.kind === 'collection')) {
+        invalid(`Implicit many-to-many relation at ${entity.name}.${field.name}: use an explicit link entity`);
+      }
+      const named = child.fields.find((item) => item.name === field.connectionField && item.kind !== 'collection');
+      const stored = child.fields.find((item) => item.storageName === field.connectionField && item.kind !== 'collection');
+      if (named && stored && named !== stored) invalid(`Conflicting connectionField ${child.name}.${field.connectionField}`);
+      const inverse = named || stored;
+      if (inverse) {
+        if (inverse.kind === 'scalar' && inverse.scalar === 'ID' && !inverse.list) {
+          Object.assign(inverse, { kind: 'reference', target: entity.name, inferred: true });
+        }
+        if (inverse.kind !== 'reference' || inverse.target !== entity.name) invalid(`Conflicting inverse relation at ${child.name}.${field.connectionField}`);
+        field.connectionField = inverse.storageName;
+      } else {
+        child.fields.push({
+          name: field.connectionField, storageName: field.connectionField, kind: 'reference', target: entity.name,
+          required: false, list: false, itemRequired: false, unique: false, readOnly: false, private: true,
+        });
+      }
+    }
+  }
+  return { entities: [...entities.values()].sort((a, b) => a.name.localeCompare(b.name)) };
+};

package/src/plugins.js

@@ -0,0 +1,53 @@
+import { createAuthPlugin } from './auth/index.js';
+
+export { createAuthPlugin } from './auth/index.js';
+
+/**
+ * Shared Apollo Server plugin to add count to GraphQL response extensions
+ * @returns {Object} Apollo Server plugin
+ */
+export const apolloCountPlugin = () => {
+  return {
+    async requestDidStart() {
+      return {
+        async willSendResponse({ contextValue, response }) {
+          if (response.body.kind === 'single' && contextValue?.count) {
+            response.body.singleResult.extensions = {
+              ...(response.body.singleResult.extensions || {}),
+              count: contextValue.count,
+            };
+          }
+        },
+      };
+    },
+  };
+};
+
+/**
+ * Envelop plugin to add count to GraphQL response extensions
+ * @returns {Object} Envelop plugin
+ */
+export const envelopCountPlugin = () => {
+  return {
+    onExecute() {
+      return {
+        onExecuteDone({ result, args }) {
+          if (args.contextValue?.count) {
+            result.extensions = {
+              ...result.extensions,
+              count: args.contextValue.count,
+            };
+          }
+        },
+      };
+    },
+  };
+};
+
+const plugins = {
+  createAuthPlugin,
+  apolloCountPlugin,
+  envelopCountPlugin,
+};
+
+export default plugins;

package/src/query-limits.js

@@ -0,0 +1,26 @@
+import SimfinityError from './errors/simfinity.error.js';
+
+let queryMaxPageSize = 1000;
+
+export const configureQueryLimits = (options = {}) => {
+  if (!options || typeof options !== 'object' || Array.isArray(options)
+    || ![Object.prototype, null].includes(Object.getPrototypeOf(options))) {
+    throw new SimfinityError('Query limit options must be a plain object', 'INVALID_QUERY_LIMITS', 400);
+  }
+  const { maxPageSize = 1000 } = options;
+  if (!Number.isSafeInteger(maxPageSize) || maxPageSize < 1) {
+    throw new SimfinityError('maxPageSize must be a positive safe integer', 'INVALID_QUERY_LIMITS', 400);
+  }
+  queryMaxPageSize = maxPageSize;
+};
+
+export const paginationStages = (pagination, withDefault) => {
+  if (pagination == null) return withDefault ? [{ $skip: 0 }, { $limit: Math.min(100, queryMaxPageSize) }] : [];
+  const { page, size } = pagination;
+  const skip = size * (page - 1);
+  if (!Number.isSafeInteger(page) || page < 1 || !Number.isSafeInteger(size) || size < 1
+    || size > queryMaxPageSize || !Number.isSafeInteger(skip)) {
+    throw new SimfinityError(`Pagination requires positive safe integers and size <= ${queryMaxPageSize}`, 'INVALID_PAGINATION', 400);
+  }
+  return [{ $skip: skip }, { $limit: size }];
+};