@e22m4u/js-repository 0.0.31

package/src/filter/order-clause-tool.d.ts

@@ -0,0 +1,32 @@
+import {ModelData} from '../types.js';
+import {OrderClause} from './filter.js';
+import {Service} from '@e22m4u/js-service';
+
+/**
+ * Order clause tool.
+ */
+export declare class OrderClauseTool extends Service {
+  /**
+   * Sort.
+   *
+   * @param entities
+   * @param clause
+   */
+  sort(entities: ModelData[], clause: OrderClause | undefined): void;
+
+  /**
+   * Validate order clause.
+   *
+   * @param clause
+   */
+  static validateOrderClause(clause: OrderClause | undefined): void;
+
+  /**
+   * Normalize order clause.
+   *
+   * @param clause
+   */
+  static normalizeOrderClause(
+    clause: OrderClause | undefined,
+  ): string[] | undefined;
+}

package/src/filter/order-clause-tool.js

@@ -0,0 +1,97 @@
+import {Service} from '@e22m4u/js-service';
+import {getValueByPath} from '../utils/index.js';
+import {InvalidArgumentError} from '../errors/index.js';
+
+/**
+ * Order clause tool.
+ */
+export class OrderClauseTool extends Service {
+  /**
+   * Sort.
+   *
+   * @param {object[]} entities
+   * @param {string|string[]|undefined} clause
+   */
+  sort(entities, clause) {
+    if (!clause) return;
+    if (!Array.isArray(clause)) clause = [clause];
+    const mapping = [];
+    clause.forEach((key, index) => {
+      if (typeof key !== 'string')
+        throw new InvalidArgumentError(
+          'The provided option "order" should be a String ' +
+            'or an Array of String, but %v given.',
+          key,
+        );
+      let reverse = 1;
+      const matches = key.match(/\s+(A|DE)SC$/i);
+      if (matches) {
+        key = key.replace(/\s+(A|DE)SC/i, '');
+        if (matches[1].toLowerCase() === 'de') reverse = -1;
+      }
+      mapping[index] = {key: key, reverse};
+    });
+    entities.sort(compareFn.bind(mapping));
+  }
+
+  /**
+   * Validate order clause.
+   *
+   * @param {string|string[]|undefined} clause
+   */
+  static validateOrderClause(clause) {
+    if (!clause) return;
+    const tempClause = Array.isArray(clause) ? clause : [clause];
+    tempClause.forEach(key => {
+      if (!key || typeof key !== 'string')
+        throw new InvalidArgumentError(
+          'The provided option "order" should be a non-empty String ' +
+            'or an Array of String, but %v given.',
+          key,
+        );
+    });
+  }
+
+  /**
+   * Normalize order clause.
+   *
+   * @param {string|string[]|undefined} clause
+   * @returns {string[]|undefined}
+   */
+  static normalizeOrderClause(clause) {
+    if (!clause) return;
+    clause = Array.isArray(clause) ? clause : [clause];
+    clause.forEach(key => {
+      if (!key || typeof key !== 'string')
+        throw new InvalidArgumentError(
+          'The provided option "order" should be a non-empty String ' +
+            'or an Array of String, but %v given.',
+          key,
+        );
+    });
+    return clause;
+  }
+}
+
+/**
+ * Compare fn.
+ *
+ * @param {*} a
+ * @param {*} b
+ * @returns {number}
+ */
+function compareFn(a, b) {
+  let undefinedA, undefinedB;
+  for (let i = 0, l = this.length; i < l; i++) {
+    const aVal = getValueByPath(a, this[i].key);
+    const bVal = getValueByPath(b, this[i].key);
+    undefinedB = bVal === undefined && aVal !== undefined;
+    undefinedA = aVal === undefined && bVal !== undefined;
+    if (undefinedB || aVal > bVal) {
+      return this[i].reverse;
+    } else if (undefinedA || aVal < bVal) {
+      return -1 * this[i].reverse;
+    }
+  }
+  return 0;
+}

package/src/filter/order-clause-tool.spec.js

@@ -0,0 +1,438 @@
+import {expect} from 'chai';
+import {format} from '@e22m4u/js-format';
+import {OrderClauseTool} from './order-clause-tool.js';
+
+const S = new OrderClauseTool();
+
+describe('OrderClauseTool', function () {
+  describe('sort', function () {
+    describe('with number values', function () {
+      it('orders by a single field in ascending by default', function () {
+        const objects = [{foo: 2}, {foo: 3}, {foo: 1}, {foo: 4}];
+        S.sort(objects, 'foo');
+        expect(objects).to.have.length(4);
+        expect(objects[0].foo).to.be.eq(1);
+        expect(objects[1].foo).to.be.eq(2);
+        expect(objects[2].foo).to.be.eq(3);
+        expect(objects[3].foo).to.be.eq(4);
+      });
+
+      it('orders by a single field in descending', function () {
+        const objects = [{foo: 2}, {foo: 3}, {foo: 1}, {foo: 4}];
+        S.sort(objects, 'foo DESC');
+        expect(objects).to.have.length(4);
+        expect(objects[0].foo).to.be.eq(4);
+        expect(objects[1].foo).to.be.eq(3);
+        expect(objects[2].foo).to.be.eq(2);
+        expect(objects[3].foo).to.be.eq(1);
+      });
+
+      it('orders by a single field in ascending', function () {
+        const objects = [{foo: 2}, {foo: 3}, {foo: 1}, {foo: 4}];
+        S.sort(objects, 'foo ASC');
+        expect(objects).to.have.length(4);
+        expect(objects[0].foo).to.be.eq(1);
+        expect(objects[1].foo).to.be.eq(2);
+        expect(objects[2].foo).to.be.eq(3);
+        expect(objects[3].foo).to.be.eq(4);
+      });
+
+      it('orders by multiple fields in ascending by default', function () {
+        const objects = [
+          {foo: 2, bar: 2},
+          {foo: 2, bar: 3},
+          {foo: 2, bar: 1},
+          {foo: 1, bar: 4},
+        ];
+        S.sort(objects, ['foo', 'bar']);
+        expect(objects).to.have.length(4);
+        expect(objects[0].bar).to.be.eq(4);
+        expect(objects[1].bar).to.be.eq(1);
+        expect(objects[2].bar).to.be.eq(2);
+        expect(objects[3].bar).to.be.eq(3);
+      });
+
+      it('orders by multiple fields in descending', function () {
+        const objects = [
+          {foo: 2, bar: 2},
+          {foo: 2, bar: 3},
+          {foo: 2, bar: 1},
+          {foo: 1, bar: 4},
+        ];
+        S.sort(objects, ['foo DESC', 'bar DESC']);
+        expect(objects).to.have.length(4);
+        expect(objects[0].bar).to.be.eq(3);
+        expect(objects[1].bar).to.be.eq(2);
+        expect(objects[2].bar).to.be.eq(1);
+        expect(objects[3].bar).to.be.eq(4);
+      });
+
+      it('orders by multiple fields in ascending', function () {
+        const objects = [
+          {foo: 2, bar: 2},
+          {foo: 2, bar: 3},
+          {foo: 2, bar: 1},
+          {foo: 1, bar: 4},
+        ];
+        S.sort(objects, ['foo ASC', 'bar ASC']);
+        expect(objects).to.have.length(4);
+        expect(objects[0].bar).to.be.eq(4);
+        expect(objects[1].bar).to.be.eq(1);
+        expect(objects[2].bar).to.be.eq(2);
+        expect(objects[3].bar).to.be.eq(3);
+      });
+
+      it('orders by nested fields in ascending by default', function () {
+        const objects = [
+          {foo: {bar: 3}},
+          {foo: {bar: 4}},
+          {foo: {bar: 2}},
+          {foo: {bar: 1}},
+        ];
+        S.sort(objects, 'foo.bar');
+        expect(objects).to.have.length(4);
+        expect(objects[0].foo.bar).to.be.eq(1);
+        expect(objects[1].foo.bar).to.be.eq(2);
+        expect(objects[2].foo.bar).to.be.eq(3);
+        expect(objects[3].foo.bar).to.be.eq(4);
+      });
+
+      it('orders by nested fields in descending', function () {
+        const objects = [
+          {foo: {bar: 3}},
+          {foo: {bar: 4}},
+          {foo: {bar: 2}},
+          {foo: {bar: 1}},
+        ];
+        S.sort(objects, 'foo.bar DESC');
+        expect(objects).to.have.length(4);
+        expect(objects[0].foo.bar).to.be.eq(4);
+        expect(objects[1].foo.bar).to.be.eq(3);
+        expect(objects[2].foo.bar).to.be.eq(2);
+        expect(objects[3].foo.bar).to.be.eq(1);
+      });
+
+      it('orders by nested fields in ascending', function () {
+        const objects = [
+          {foo: {bar: 3}},
+          {foo: {bar: 4}},
+          {foo: {bar: 2}},
+          {foo: {bar: 1}},
+        ];
+        S.sort(objects, 'foo.bar ASC');
+        expect(objects).to.have.length(4);
+        expect(objects[0].foo.bar).to.be.eq(1);
+        expect(objects[1].foo.bar).to.be.eq(2);
+        expect(objects[2].foo.bar).to.be.eq(3);
+        expect(objects[3].foo.bar).to.be.eq(4);
+      });
+
+      it('orders by multiple fields with nested one', function () {
+        const objects = [
+          {foo: {bar: 2}, baz: 2},
+          {foo: {bar: 2}, baz: 3},
+          {foo: {bar: 2}, baz: 4},
+          {foo: {bar: 1}, baz: 1},
+        ];
+        S.sort(objects, ['foo.bar ASC', 'baz DESC']);
+        expect(objects).to.have.length(4);
+        expect(objects[0].baz).to.be.eq(1);
+        expect(objects[1].baz).to.be.eq(4);
+        expect(objects[2].baz).to.be.eq(3);
+        expect(objects[3].baz).to.be.eq(2);
+      });
+    });
+
+    describe('with string values', function () {
+      it('orders by a single field in ascending by default', function () {
+        const objects = [{foo: 'b'}, {foo: 'c'}, {foo: 'a'}, {foo: 'd'}];
+        S.sort(objects, 'foo');
+        expect(objects).to.have.length(4);
+        expect(objects[0].foo).to.be.eq('a');
+        expect(objects[1].foo).to.be.eq('b');
+        expect(objects[2].foo).to.be.eq('c');
+        expect(objects[3].foo).to.be.eq('d');
+      });
+
+      it('orders by a single field in descending', function () {
+        const objects = [{foo: 'b'}, {foo: 'c'}, {foo: 'a'}, {foo: 'd'}];
+        S.sort(objects, 'foo DESC');
+        expect(objects).to.have.length(4);
+        expect(objects[0].foo).to.be.eq('d');
+        expect(objects[1].foo).to.be.eq('c');
+        expect(objects[2].foo).to.be.eq('b');
+        expect(objects[3].foo).to.be.eq('a');
+      });
+
+      it('orders by a single field in ascending', function () {
+        const objects = [{foo: 'b'}, {foo: 'c'}, {foo: 'a'}, {foo: 'd'}];
+        S.sort(objects, 'foo ASC');
+        expect(objects).to.have.length(4);
+        expect(objects[0].foo).to.be.eq('a');
+        expect(objects[1].foo).to.be.eq('b');
+        expect(objects[2].foo).to.be.eq('c');
+        expect(objects[3].foo).to.be.eq('d');
+      });
+
+      it('orders by multiple fields in ascending by default', function () {
+        const objects = [
+          {foo: 'b', bar: 'b'},
+          {foo: 'b', bar: 'c'},
+          {foo: 'b', bar: 'a'},
+          {foo: 'a', bar: 'd'},
+        ];
+        S.sort(objects, ['foo', 'bar']);
+        expect(objects).to.have.length(4);
+        expect(objects[0].bar).to.be.eq('d');
+        expect(objects[1].bar).to.be.eq('a');
+        expect(objects[2].bar).to.be.eq('b');
+        expect(objects[3].bar).to.be.eq('c');
+      });
+
+      it('orders by multiple fields in descending', function () {
+        const objects = [
+          {foo: 'b', bar: 'b'},
+          {foo: 'b', bar: 'c'},
+          {foo: 'b', bar: 'a'},
+          {foo: 'a', bar: 'd'},
+        ];
+        S.sort(objects, ['foo DESC', 'bar DESC']);
+        expect(objects).to.have.length(4);
+        expect(objects[0].bar).to.be.eq('c');
+        expect(objects[1].bar).to.be.eq('b');
+        expect(objects[2].bar).to.be.eq('a');
+        expect(objects[3].bar).to.be.eq('d');
+      });
+
+      it('orders by multiple fields in ascending', function () {
+        const objects = [
+          {foo: 'b', bar: 'b'},
+          {foo: 'b', bar: 'c'},
+          {foo: 'b', bar: 'a'},
+          {foo: 'a', bar: 'd'},
+        ];
+        S.sort(objects, ['foo ASC', 'bar ASC']);
+        expect(objects).to.have.length(4);
+        expect(objects[0].bar).to.be.eq('d');
+        expect(objects[1].bar).to.be.eq('a');
+        expect(objects[2].bar).to.be.eq('b');
+        expect(objects[3].bar).to.be.eq('c');
+      });
+
+      it('orders by nested fields in ascending by default', function () {
+        const objects = [
+          {foo: {bar: 'c'}},
+          {foo: {bar: 'd'}},
+          {foo: {bar: 'b'}},
+          {foo: {bar: 'a'}},
+        ];
+        S.sort(objects, 'foo.bar');
+        expect(objects).to.have.length(4);
+        expect(objects[0].foo.bar).to.be.eq('a');
+        expect(objects[1].foo.bar).to.be.eq('b');
+        expect(objects[2].foo.bar).to.be.eq('c');
+        expect(objects[3].foo.bar).to.be.eq('d');
+      });
+
+      it('orders by nested fields in descending', function () {
+        const objects = [
+          {foo: {bar: 'c'}},
+          {foo: {bar: 'd'}},
+          {foo: {bar: 'b'}},
+          {foo: {bar: 'a'}},
+        ];
+        S.sort(objects, 'foo.bar DESC');
+        expect(objects).to.have.length(4);
+        expect(objects[0].foo.bar).to.be.eq('d');
+        expect(objects[1].foo.bar).to.be.eq('c');
+        expect(objects[2].foo.bar).to.be.eq('b');
+        expect(objects[3].foo.bar).to.be.eq('a');
+      });
+
+      it('orders by nested fields in ascending', function () {
+        const objects = [
+          {foo: {bar: 'c'}},
+          {foo: {bar: 'd'}},
+          {foo: {bar: 'b'}},
+          {foo: {bar: 'a'}},
+        ];
+        S.sort(objects, 'foo.bar ASC');
+        expect(objects).to.have.length(4);
+        expect(objects[0].foo.bar).to.be.eq('a');
+        expect(objects[1].foo.bar).to.be.eq('b');
+        expect(objects[2].foo.bar).to.be.eq('c');
+        expect(objects[3].foo.bar).to.be.eq('d');
+      });
+
+      it('orders by multiple fields with nested one', function () {
+        const objects = [
+          {foo: {bar: 'b'}, baz: 'b'},
+          {foo: {bar: 'b'}, baz: 'c'},
+          {foo: {bar: 'b'}, baz: 'd'},
+          {foo: {bar: 'a'}, baz: 'a'},
+        ];
+        S.sort(objects, ['foo.bar ASC', 'baz DESC']);
+        expect(objects).to.have.length(4);
+        expect(objects[0].baz).to.be.eq('a');
+        expect(objects[1].baz).to.be.eq('d');
+        expect(objects[2].baz).to.be.eq('c');
+        expect(objects[3].baz).to.be.eq('b');
+      });
+    });
+
+    describe('with number and string values', function () {
+      it('orders by number and string values in ascending by default', function () {
+        const objects = [
+          {foo: 2, bar: 'd'},
+          {foo: 2, bar: 'b'},
+          {foo: 2, bar: 'a'},
+          {foo: 1, bar: 'c'},
+        ];
+        S.sort(objects, ['foo', 'bar']);
+        expect(objects).to.have.length(4);
+        expect(objects[0].bar).to.be.eq('c');
+        expect(objects[1].bar).to.be.eq('a');
+        expect(objects[2].bar).to.be.eq('b');
+        expect(objects[3].bar).to.be.eq('d');
+      });
+
+      it('orders by number and string values in descending', function () {
+        const objects = [
+          {foo: 2, bar: 'd'},
+          {foo: 2, bar: 'b'},
+          {foo: 2, bar: 'a'},
+          {foo: 1, bar: 'c'},
+        ];
+        S.sort(objects, ['foo DESC', 'bar DESC']);
+        expect(objects).to.have.length(4);
+        expect(objects[0].bar).to.be.eq('d');
+        expect(objects[1].bar).to.be.eq('b');
+        expect(objects[2].bar).to.be.eq('a');
+        expect(objects[3].bar).to.be.eq('c');
+      });
+
+      it('orders by number and string values in ascending', function () {
+        const objects = [
+          {foo: 2, bar: 'd'},
+          {foo: 2, bar: 'b'},
+          {foo: 2, bar: 'a'},
+          {foo: 1, bar: 'c'},
+        ];
+        S.sort(objects, ['foo ASC', 'bar ASC']);
+        expect(objects).to.have.length(4);
+        expect(objects[0].bar).to.be.eq('c');
+        expect(objects[1].bar).to.be.eq('a');
+        expect(objects[2].bar).to.be.eq('b');
+        expect(objects[3].bar).to.be.eq('d');
+      });
+
+      it('orders by number and string values in mixed directions', function () {
+        const objects = [
+          {foo: 2, bar: 'd'},
+          {foo: 2, bar: 'b'},
+          {foo: 2, bar: 'a'},
+          {foo: 1, bar: 'c'},
+        ];
+        S.sort(objects, ['foo DESC', 'bar ASC']);
+        expect(objects).to.have.length(4);
+        expect(objects[0].bar).to.be.eq('a');
+        expect(objects[1].bar).to.be.eq('b');
+        expect(objects[2].bar).to.be.eq('d');
+        expect(objects[3].bar).to.be.eq('c');
+      });
+    });
+
+    it('does not throw an error if a field does not exist', function () {
+      const objects = [{foo: 1}, {foo: 2}, {foo: 3}, {foo: 4}];
+      S.sort(objects, 'bar');
+      expect(objects).to.have.length(4);
+      expect(objects[0].foo).to.be.eq(1);
+      expect(objects[1].foo).to.be.eq(2);
+      expect(objects[2].foo).to.be.eq(3);
+      expect(objects[3].foo).to.be.eq(4);
+    });
+
+    it('does not throw an error if a nested field does not exist', function () {
+      const objects = [
+        {foo: 1},
+        {foo: 2, bar: undefined},
+        {foo: 3, bar: {baz: undefined}},
+        {foo: 4, bar: {baz: 1}},
+      ];
+      S.sort(objects, 'bar.baz');
+      expect(objects).to.have.length(4);
+      expect(objects[0].foo).to.be.eq(1);
+      expect(objects[1].foo).to.be.eq(2);
+      expect(objects[2].foo).to.be.eq(3);
+      expect(objects[3].foo).to.be.eq(4);
+    });
+
+    it('throws an error if a given property is not a string', function () {
+      const throwable = () => S.sort([], 10);
+      expect(throwable).to.throw(
+        'The provided option "order" should be a String ' +
+          'or an Array of String, but 10 given.',
+      );
+    });
+  });
+
+  describe('validateOrderClause', function () {
+    it('requires a non-empty string or an array of non-empty strings', function () {
+      const validate = v => () => OrderClauseTool.validateOrderClause(v);
+      const error = v =>
+        format(
+          'The provided option "order" should be a non-empty String ' +
+            'or an Array of String, but %s given.',
+          v,
+        );
+      expect(validate(10)).to.throw(error('10'));
+      expect(validate(true)).to.throw(error('true'));
+      expect(validate({})).to.throw(error('Object'));
+      expect(validate([''])).to.throw(error('""'));
+      expect(validate([10])).to.throw(error('10'));
+      expect(validate([true])).to.throw(error('true'));
+      expect(validate([false])).to.throw(error('false'));
+      expect(validate([undefined])).to.throw(error('undefined'));
+      expect(validate([null])).to.throw(error('null'));
+      validate('')();
+      validate(false)();
+      validate(undefined)();
+      validate(null)();
+      validate('foo')();
+      validate(['foo'])();
+    });
+  });
+
+  describe('normalizeOrderClause', function () {
+    it('returns an array of strings', function () {
+      const fn = OrderClauseTool.normalizeOrderClause;
+      expect(fn('foo')).to.be.eql(['foo']);
+      expect(fn(['foo'])).to.be.eql(['foo']);
+    });
+
+    it('requires a non-empty string or an array of non-empty strings', function () {
+      const fn = clause => () => OrderClauseTool.normalizeOrderClause(clause);
+      const error = v =>
+        format(
+          'The provided option "order" should be a non-empty String ' +
+            'or an Array of String, but %s given.',
+          v,
+        );
+      expect(fn(10)).to.throw(error('10'));
+      expect(fn(true)).to.throw(error('true'));
+      expect(fn({})).to.throw(error('Object'));
+      expect(fn([''])).to.throw(error('""'));
+      expect(fn([10])).to.throw(error('10'));
+      expect(fn([true])).to.throw(error('true'));
+      expect(fn([false])).to.throw(error('false'));
+      expect(fn([undefined])).to.throw(error('undefined'));
+      expect(fn([null])).to.throw(error('null'));
+      expect(fn('')()).to.be.undefined;
+      expect(fn(false)()).to.be.undefined;
+      expect(fn(undefined)()).to.be.undefined;
+      expect(fn(null)()).to.be.undefined;
+      expect(fn('foo')()).to.be.eql(['foo']);
+      expect(fn(['foo'])()).to.be.eql(['foo']);
+    });
+  });
+});

package/src/filter/slice-clause-tool.d.ts

@@ -0,0 +1,30 @@
+import {ModelData} from '../types.js';
+import {Service} from '@e22m4u/js-service';
+
+/**
+ * Slice clause tool.
+ */
+export declare class SliceClauseTool extends Service {
+  /**
+   * Slice.
+   *
+   * @param entities
+   * @param skip
+   * @param limit
+   */
+  slice(entities: ModelData[], skip?: number, limit?: number): ModelData[];
+
+  /**
+   * Validate skip clause.
+   *
+   * @param skip
+   */
+  static validateSkipClause(skip: number | undefined): void;
+
+  /**
+   * Validate limit clause.
+   *
+   * @param limit
+   */
+  static validateLimitClause(limit: number | undefined): void;
+}

package/src/filter/slice-clause-tool.js

@@ -0,0 +1,65 @@
+import {Service} from '@e22m4u/js-service';
+import {InvalidArgumentError} from '../errors/index.js';
+
+/**
+ * Slice clause tool.
+ */
+export class SliceClauseTool extends Service {
+  /**
+   * Filter.
+   *
+   * @param {object[]} entities
+   * @param {number|undefined} skip
+   * @param {number|undefined} limit
+   * @returns {object[]}
+   */
+  slice(entities, skip = undefined, limit = undefined) {
+    if (!Array.isArray(entities))
+      throw new InvalidArgumentError(
+        'A first argument of SliceClauseTool.slice ' +
+          'should be an Array, but %v given.',
+        entities,
+      );
+    if (skip && typeof skip !== 'number')
+      throw new InvalidArgumentError(
+        'The provided option "skip" should be a Number, but %v given.',
+        skip,
+      );
+    if (limit && typeof limit !== 'number')
+      throw new InvalidArgumentError(
+        'The provided option "limit" should be a Number, but %v given.',
+        limit,
+      );
+    skip = skip || 0;
+    limit = limit || entities.length;
+    return entities.slice(skip, skip + limit);
+  }
+
+  /**
+   * Validate skip clause.
+   *
+   * @param {number|undefined} skip
+   */
+  static validateSkipClause(skip) {
+    if (!skip) return;
+    if (typeof skip !== 'number')
+      throw new InvalidArgumentError(
+        'The provided option "skip" should be a Number, but %v given.',
+        skip,
+      );
+  }
+
+  /**
+   * Validate limit clause.
+   *
+   * @param {number|undefined} limit
+   */
+  static validateLimitClause(limit) {
+    if (!limit) return;
+    if (typeof limit !== 'number')
+      throw new InvalidArgumentError(
+        'The provided option "limit" should be a Number, but %v given.',
+        limit,
+      );
+  }
+}