@andrew_l/mongo-pagination 0.0.2

package/dist/shared/mongo-pagination.YG1DNE27.mjs

@@ -0,0 +1,654 @@
+import { crc32, isObject, isEmpty, intersection, isFunction, isNumber, deepClone, cleanEmpty, toError, pick } from '@andrew_l/toolkit';
+import Kareem from 'kareem';
+import { ObjectId, MongoInvalidArgumentError } from 'mongodb';
+import { createExtension, BinaryWriter, BinaryReader } from '@andrew_l/tl-pack';
+import d from 'debug';
+import { Transform } from 'node:stream';
+
+const SCHEMA_VERSION = 1;
+const OBJECT_ID_TOKEN = 100;
+const extensions = [
+  createExtension(OBJECT_ID_TOKEN, {
+    encode(value) {
+      if (value?._bsontype?.toLowerCase() === "objectid") {
+        this.writeBytes(value.id);
+      }
+    },
+    decode() {
+      const bytes = this.readBytes();
+      return new ObjectId(bytes);
+    }
+  })
+];
+class Token {
+  /**
+   * The schema version of the token.
+   */
+  schemaVersion = SCHEMA_VERSION;
+  /**
+   * The CRC of the model name, used for verify the model.
+   */
+  modelNameCRC = 0;
+  /**
+   * The sorting direction used for pagination building pagination query.
+   */
+  sortDirection = {};
+  /**
+   * The sorting values associated with the pagination.
+   */
+  sortValues = {};
+  /**
+   * The payload of the token, which can contain any associated metadata or data (may be `null`).
+   */
+  payload = null;
+  constructor(options) {
+    if (options) {
+      Object.assign(this, { ...options, modelName: void 0 });
+      if (options.modelName) {
+        this.modelNameCRC = crc32(options.modelName);
+      }
+    }
+  }
+  /**
+   * Retrieves the string representation of token.
+   */
+  stringify() {
+    return this.buffer().toString("base64url");
+  }
+  /**
+   * Retrieves binary buffer representation of token.
+   */
+  buffer() {
+    const writer = new BinaryWriter({
+      extensions
+    });
+    writer.writeInt8(this.schemaVersion, false);
+    writer.writeObject(this.modelNameCRC);
+    writer.writeMap(this.sortDirection || {});
+    writer.writeMap(this.sortValues || {});
+    writer.writeObject(this.payload || null);
+    return Buffer.from(writer.getBuffer());
+  }
+  /**
+   * Encode token from provided value
+   */
+  static from(value) {
+    const buffer = Buffer.isBuffer(value) ? value : Buffer.from(value, "base64url");
+    const reader = new BinaryReader(buffer, { extensions });
+    const schemaVersion = reader.readInt8(false);
+    if (schemaVersion !== SCHEMA_VERSION) {
+      throw new TypeError(`Unexpected schema version: ${schemaVersion}`);
+    }
+    const token = new Token();
+    token.modelNameCRC = reader.readObject();
+    token.sortDirection = reader.readMap(false);
+    token.sortValues = reader.readMap(false);
+    token.payload = reader.readObject();
+    return token;
+  }
+}
+function createToken(options) {
+  return new Token(options);
+}
+
+const debug = {
+  init: d("mongo-pagination:init"),
+  tweak: d("mongo-pagination:tweak"),
+  exec: d("mongo-pagination:exec"),
+  stream: d("mongo-pagination:query:stream")
+};
+
+function isEmptyObject(obj) {
+  return !isObject(obj) || isEmpty(obj);
+}
+function sameKeys(...args) {
+  return intersection(...args.map((v) => Object.keys(v)));
+}
+function defineGetter(obj, key, getterFn) {
+  delete obj[key];
+  Object.defineProperty(obj, key, {
+    get: getterFn,
+    enumerable: true,
+    configurable: true
+  });
+}
+function isLastKeys(value, keys, strictOrder) {
+  const objKeys = isObject(value) ? Object.keys(value) : [];
+  const lastKeys = objKeys.slice(-keys.length);
+  if (lastKeys.length !== keys.length) {
+    return false;
+  }
+  for (let idx = 0; idx < keys.length; idx++) {
+    {
+      if (!lastKeys.includes(keys[idx])) {
+        return false;
+      }
+    }
+  }
+  return true;
+}
+function toObject(value) {
+  return isFunction(value?.toObject) ? value?.toObject() : value;
+}
+
+function prepareDirection(direction = 1) {
+  const value = `${direction}`.toLowerCase();
+  if (isMeta(direction)) return direction;
+  switch (value) {
+    case "ascending":
+    case "asc":
+    case "1":
+      return 1;
+    case "descending":
+    case "desc":
+    case "-1":
+      return -1;
+    default:
+      throw new MongoInvalidArgumentError(
+        `Invalid sort direction: ${JSON.stringify(direction)}`
+      );
+  }
+}
+function isMeta(t) {
+  return typeof t === "object" && t != null && "$meta" in t && typeof t.$meta === "string";
+}
+function isPair(t) {
+  if (Array.isArray(t) && t.length === 2) {
+    try {
+      prepareDirection(t[1]);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  return false;
+}
+function isDeep(t) {
+  return Array.isArray(t) && Array.isArray(t[0]);
+}
+function isMap(t) {
+  return t instanceof Map && t.size > 0;
+}
+function pairToMap(v) {
+  return /* @__PURE__ */ new Map([[`${v[0]}`, prepareDirection([v[1]])]]);
+}
+function deepToMap(t) {
+  const sortEntries = t.map(([k, v]) => [
+    `${k}`,
+    prepareDirection(v)
+  ]);
+  return new Map(sortEntries);
+}
+function stringsToMap(t) {
+  const sortEntries = t.map((key) => [`${key}`, 1]);
+  return new Map(sortEntries);
+}
+function objectToMap(t) {
+  const sortEntries = Object.entries(t).map(([k, v]) => [
+    `${k}`,
+    prepareDirection(v)
+  ]);
+  return new Map(sortEntries);
+}
+function mapToMap(t) {
+  const sortEntries = Array.from(t).map(([k, v]) => [
+    `${k}`,
+    prepareDirection(v)
+  ]);
+  return new Map(sortEntries);
+}
+function formatSort(sort, direction) {
+  if (sort == null) return void 0;
+  if (typeof sort === "string")
+    return /* @__PURE__ */ new Map([[sort, prepareDirection(direction)]]);
+  if (typeof sort !== "object") {
+    throw new MongoInvalidArgumentError(
+      `Invalid sort format: ${JSON.stringify(sort)} Sort must be a valid object`
+    );
+  }
+  if (!Array.isArray(sort)) {
+    return isMap(sort) ? mapToMap(sort) : Object.keys(sort).length ? objectToMap(sort) : void 0;
+  }
+  if (!sort.length) return void 0;
+  if (isDeep(sort)) return deepToMap(sort);
+  if (isPair(sort)) return pairToMap(sort);
+  return stringsToMap(sort);
+}
+
+const DEF_LIMIT = 10;
+function createRangeFilter(sortDirection, sortValues) {
+  const sortCmd = formatSort(sortDirection) ?? {};
+  const keys = [];
+  for (const [sortKey, sortValue] of sortCmd.entries()) {
+    if (sortValues[sortKey] === void 0) continue;
+    if (!isNumber(sortValue)) continue;
+    keys.push(sortKey);
+  }
+  const op = (sortKey) => {
+    const direction = sortCmd.get(sortKey);
+    return direction === 1 ? "$gt" : "$lt";
+  };
+  const val = (sortKey) => sortValues[sortKey];
+  if (keys.length === 0) {
+    return {};
+  } else if (keys.length === 1) {
+    const sortKey = keys[0];
+    return {
+      [sortKey]: {
+        [op(sortKey)]: val(sortKey)
+      }
+    };
+  }
+  const $or = [];
+  const keysAmount = keys.length;
+  for (let i = 0; i < keysAmount; i++) {
+    const sortKey = keys[i];
+    if (i === 0) {
+      $or.push({
+        [sortKey]: { [op(sortKey)]: val(sortKey) }
+      });
+    } else {
+      const filter = {};
+      keys.slice(0, i).map((sortKey3) => {
+        filter[sortKey3] = { $eq: val(sortKey3) };
+      });
+      const sortKey2 = keys[i];
+      filter[sortKey2] = {
+        [op(sortKey2)]: val(sortKey2)
+      };
+      $or.push(filter);
+    }
+  }
+  if ($or.length === 1) return $or[0];
+  return { $or };
+}
+function mergeFilters(first, second) {
+  switch (true) {
+    // Just return second
+    case isEmptyObject(first):
+      return deepClone(second);
+    // Just return first
+    case isEmptyObject(second):
+      return deepClone(first);
+    // Just assign when no conflicts
+    case sameKeys(first, second).length === 0:
+      return Object.assign(deepClone(first), deepClone(second));
+    // Merge with $and way
+    case Array.isArray(first.$and):
+      first = deepClone(first);
+      second = deepClone(second);
+      if (Object.keys(second).length === 1 && second.$and) {
+        first.$and.push(...second.$and);
+      } else {
+        first.$and.push(second);
+      }
+      return first;
+    // Regular merge via $and wrapping
+    default:
+      return {
+        $and: [deepClone(first), deepClone(second)]
+      };
+  }
+}
+function tweakQuery({
+  paginationFields,
+  token,
+  query
+}) {
+  let queryOptions = deepClone(query.getOptions());
+  let queryFilter = deepClone(query.getFilter());
+  paginationFields = deepClone(paginationFields);
+  if (queryOptions.sort) {
+    const sortMap = formatSort(queryOptions.sort);
+    if (sortMap) {
+      queryOptions.sort = Object.fromEntries(sortMap.entries());
+    }
+  }
+  if (token) {
+    if (!isEmptyObject(token.sortDirection)) {
+      debug.tweak(
+        "set from token [queryOptions.sort] = %o",
+        token.sortDirection
+      );
+      queryOptions.sort = token.sortDirection;
+    }
+    if (!isEmptyObject(token.sortValues)) {
+      const rangeFilter = createRangeFilter(
+        queryOptions.sort,
+        token.sortValues
+      );
+      debug.tweak(
+        "range conditions:\n	sortDirection = %o\n	sortValues = %o\n	result = %o",
+        queryOptions.sort,
+        token.sortValues,
+        rangeFilter
+      );
+      queryFilter = mergeFilters(queryFilter, rangeFilter);
+    }
+  }
+  if (isEmptyObject(queryOptions.sort)) {
+    queryOptions.sort = { _id: -1 };
+    debug.tweak("set default [queryOptions.sort] = %o", queryOptions.sort);
+  }
+  if (!Array.isArray(paginationFields) || !paginationFields.length) {
+    paginationFields = Object.keys(queryOptions.sort);
+    debug.tweak("set default [paginationFields] = %o", paginationFields);
+  }
+  if (!isLastKeys(queryOptions.sort, paginationFields)) {
+    const expectedKeys = paginationFields.join(", ");
+    throw new MongoInvalidArgumentError(
+      `The query sort keys must ends with "${expectedKeys}".`
+    );
+  }
+  if (!queryOptions.limit) {
+    queryOptions.limit = DEF_LIMIT + 1;
+    debug.tweak("set default [queryOptions.limit] = %d", queryOptions.limit);
+  } else {
+    queryOptions.limit = Math.max(queryOptions.limit || DEF_LIMIT, 1) + 1;
+  }
+  query.setOptions(queryOptions);
+  query.setFilter(queryFilter);
+  return paginationFields;
+}
+
+class QueryAdapterMongoose {
+  constructor(query) {
+    this.query = query;
+  }
+  getModelName() {
+    return this.query.model.modelName;
+  }
+  getOptions() {
+    const options = this.query.getOptions();
+    return {
+      limit: options.limit,
+      sort: options.sort
+    };
+  }
+  getFilter() {
+    return this.query.getFilter();
+  }
+  setOptions({ limit, sort }) {
+    this.query.setOptions(cleanEmpty({ limit, sort }));
+  }
+  setFilter(filter) {
+    this.query.setQuery(filter);
+  }
+  toArray() {
+    return this.query.exec();
+  }
+  stream() {
+    return this.query.cursor();
+  }
+}
+
+class Filter extends Transform {
+  constructor(has, options) {
+    super({
+      autoDestroy: true,
+      objectMode: true,
+      ...options,
+      readableObjectMode: true,
+      writableObjectMode: true,
+      highWaterMark: 16
+    });
+    this.has = has;
+    this._count = -1;
+  }
+  _count = 0;
+  _transform(chunk, encoding, next) {
+    const result = this.has(chunk, ++this._count);
+    if (typeof result === "boolean") {
+      if (result) {
+        return next(null, chunk);
+      } else {
+        return next();
+      }
+    }
+    if ("then" in result) {
+      return void result.then((r) => {
+        if (r) next(null, chunk);
+      }).catch(next);
+    }
+    next();
+  }
+}
+function streamFilter(fn, options) {
+  return new Filter(fn, options);
+}
+
+class QueryPaginator {
+  constructor(query, {
+    paginationFields = [],
+    postQuery,
+    preQuery,
+    next: previousToken,
+    debugQuery = false
+  } = {}) {
+    this.query = query;
+    this.paginationFields = paginationFields;
+    this.debugQuery = debugQuery;
+    this.next = createToken({
+      modelName: query.getModelName(),
+      sortDirection: {},
+      sortValues: {},
+      payload: {}
+    });
+    if (previousToken) {
+      try {
+        this.previous = Token.from(previousToken);
+        this.paginationFields = Object.keys(this.previous.sortValues);
+        debug.init("parse previous = %o", this.previous);
+        debug.init(
+          "set from previous [paginationFields] = %o",
+          this.paginationFields
+        );
+      } catch (orignErr) {
+        const err = new MongoInvalidArgumentError(
+          "Failed to parse next pagination cursor.",
+          { cause: toError(orignErr) }
+        );
+        throw err;
+      }
+      const modelNameCRC = crc32(query.getModelName());
+      debug.init(
+        "compare model name: previous = %d, query = %d",
+        this.previous.modelNameCRC,
+        modelNameCRC
+      );
+      if (modelNameCRC !== this.previous.modelNameCRC) {
+        throw new MongoInvalidArgumentError(
+          "The model name of next cursor token is not equal with query model name. Expected: " + this.query.getModelName()
+        );
+      }
+    }
+    if (preQuery) this.pre("query", preQuery);
+    if (postQuery) this.post("query", postQuery);
+    defineGetter(this.next, "sortDirection", () => {
+      const sortMap = formatSort(this.query.getOptions().sort);
+      return sortMap ? Object.fromEntries(sortMap.entries()) : {};
+    });
+    defineGetter(this.next, "sortValues", () => {
+      if (!this.resLastItem) {
+        return {};
+      }
+      return pick(this.resLastItem, this.paginationFields);
+    });
+    debug.init("with options = %o", arguments[1]);
+  }
+  hooks = new Kareem();
+  next;
+  previous;
+  resHasNext = false;
+  resLastItem = null;
+  paginationFields;
+  tweaked = false;
+  debugQuery = false;
+  getMetadata = () => this.metadata;
+  /**
+   * Retrieves metadata about the current state of pagination.
+   */
+  get metadata() {
+    return {
+      hasNext: this.hasNext,
+      next: this.nextTokenString
+    };
+  }
+  /**
+   * Indicates whether there is a next page available.
+   */
+  get hasNext() {
+    return this.resHasNext;
+  }
+  /**
+   * Retrieves the token for the next page.
+   */
+  get nextToken() {
+    return this.next;
+  }
+  /**
+   * Retrieves the string representation of the next page token.
+   * If there is no next page, returns `null`.
+   */
+  get nextTokenString() {
+    if (!this.resHasNext) {
+      return null;
+    }
+    return this.next.stringify();
+  }
+  /**
+   * Retrieves the token for the previous page.
+   */
+  get prevToken() {
+    return this.previous || null;
+  }
+  /**
+   * Retrieves the string representation of the previous page token.
+   */
+  get prevTokenString() {
+    return this.previous ? this.previous.stringify() : null;
+  }
+  getQuery() {
+    return this.query;
+  }
+  pre(hookName, fn) {
+    this.hooks.pre(hookName, fn);
+    return this;
+  }
+  post(hookName, fn) {
+    this.hooks.post(hookName, fn);
+    return this;
+  }
+  stream() {
+    return new Promise((resolve, reject) => {
+      this.hooks.execPre("query", this, [], (error) => {
+        if (error) return reject(error);
+        try {
+          this.maybeTweak();
+        } catch (err) {
+          return reject(err);
+        }
+        const limit = this.query.getOptions().limit;
+        const filter = streamFilter((item, index) => {
+          if (index + 1 === limit) {
+            this.resHasNext = true;
+            debug.stream(
+              "has next:\n	cutoff_idx = %d\n	next = %j",
+              index,
+              this.next
+            );
+            return false;
+          } else {
+            this.resLastItem = toObject(item);
+          }
+          return true;
+        });
+        const stream = this.query.stream().pipe(filter);
+        resolve(stream);
+      });
+    });
+  }
+  /** @internal */
+  maybeTweak() {
+    if (!this.tweaked) {
+      this.tweak();
+    }
+    return this;
+  }
+  /** @internal */
+  tweak() {
+    this.paginationFields = tweakQuery({
+      query: this.query,
+      paginationFields: this.paginationFields,
+      token: this.previous
+    });
+    this.tweaked = true;
+    return this;
+  }
+  /** @internal */
+  _handleResult(items) {
+    const limit = this.query.getOptions().limit;
+    if (items.length === limit) {
+      items.pop();
+      this.resHasNext = true;
+    }
+    this.resLastItem = toObject(items.at(-1));
+    if (this.resHasNext) {
+      debug.exec(
+        "has next:\n	cutoff_idx = %d\n	next = %j",
+        limit - 1,
+        this.next
+      );
+    }
+    const metadata = this.getMetadata();
+    return { metadata, items };
+  }
+  /**
+   * Executes the query and returns the results along with pagination metadata.
+   */
+  exec() {
+    return new Promise((resolve, reject) => {
+      this.hooks.execPre("query", this, [], (preHookErr) => {
+        if (preHookErr) {
+          return reject(preHookErr);
+        }
+        if (this.debugQuery) {
+          console.info("pre tweak", {
+            queryFilter: this.query.getFilter(),
+            getOptions: this.query.getOptions(),
+            prevToken: this.prevToken
+          });
+        }
+        this.maybeTweak();
+        if (this.debugQuery) {
+          console.info("post tweak", {
+            queryFilter: this.query.getFilter(),
+            getOptions: this.query.getOptions(),
+            prevToken: this.prevToken
+          });
+        }
+        this.query.toArray().then((items) => {
+          const result = this._handleResult(items);
+          this.hooks.execPost("query", this, [], (postHookErr) => {
+            if (postHookErr) {
+              return reject(postHookErr);
+            }
+            return resolve(result);
+          });
+        }).catch(reject);
+      });
+    });
+  }
+  then = (onfulfilled, onrejected) => this.exec().then(onfulfilled, onrejected);
+  cath = (onrejected) => this.exec().catch(onrejected);
+  finally = (onfinally) => this.exec().finally(onfinally);
+}
+
+function withMongoosePagination(query, options) {
+  const adapter = new QueryAdapterMongoose(query);
+  const pagin = new QueryPaginator(adapter, options);
+  return pagin;
+}
+
+export { QueryPaginator as Q, createRangeFilter as a, createToken as c, mergeFilters as m, tweakQuery as t, withMongoosePagination as w };
+//# sourceMappingURL=mongo-pagination.YG1DNE27.mjs.map