@karmaniverous/entity-manager 5.0.8 → 6.0.0

package/package.json

@@ -1,87 +1,136 @@
 {
-  "name": "@karmaniverous/entity-manager",
-  "version": "5.0.8",
-  "publishConfig": {
-    "access": "public"
-  },
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/karmaniverous/entity-manager"
-  },
-  "author": "Jason G. Williscroft",
+  "author": "Jason Williscroft",
   "bugs": {
     "url": "https://github.com/karmaniverous/entity-manager/issues"
   },
-  "description": "Configurably decorate entity objects with sharded index keys.",
-  "homepage": "https://github.com/karmaniverous/entity-manager#readme",
-  "keywords": [
-    "dynamo-db",
-    "sharding"
-  ],
-  "license": "BSD-3-Clause",
   "dependencies": {
-    "inspect-parameters-declaration": "^0.1.0",
+    "@karmaniverous/entity-tools": "^0.2.3",
+    "@karmaniverous/string-utilities": "^0.2.1",
     "jsonschema": "^1.4.1",
-    "lodash": "^4.17.21",
-    "string-hash": "^1.1.3"
+    "lz-string": "^1.5.0",
+    "radash": "^12.1.0",
+    "string-hash": "^1.1.3",
+    "zod": "^3.23.8"
   },
+  "description": "Configurably decorate entity objects with sharded index keys.",
   "devDependencies": {
-    "@babel/cli": "^7.24.8",
-    "@babel/core": "^7.25.2",
-    "@babel/eslint-parser": "^7.25.1",
-    "@babel/plugin-syntax-import-assertions": "^7.24.7",
-    "@babel/preset-env": "^7.25.2",
-    "@babel/register": "^7.24.6",
-    "@karmaniverous/edge-logger": "^1.3.12",
-    "@karmaniverous/tagged-templates": "^0.1.2",
-    "@types/node": "^20.14.13",
-    "babel-plugin-lodash": "^3.3.4",
+    "@dotenvx/dotenvx": "^1.14.1",
+    "@eslint/js": "^9.10.0",
+    "@faker-js/faker": "^9.0.1",
+    "@karmaniverous/mock-db": "^0.3.1",
+    "@rollup/plugin-alias": "^5.1.0",
+    "@rollup/plugin-commonjs": "^26.0.1",
+    "@rollup/plugin-json": "^6.1.0",
+    "@rollup/plugin-node-resolve": "^15.2.3",
+    "@rollup/plugin-strip": "^3.0.4",
+    "@rollup/plugin-typescript": "^11.1.6",
+    "@types/chai": "^4.3.19",
+    "@types/eslint__js": "^8.42.3",
+    "@types/eslint-config-prettier": "^6.11.3",
+    "@types/eslint-plugin-mocha": "^10.4.0",
+    "@types/mocha": "^10.0.8",
+    "@types/node": "^22.5.5",
+    "@types/string-hash": "^1.1.3",
+    "auto-changelog": "^2.5.0",
     "chai": "^5.1.1",
-    "concat-md": "^0.5.1",
-    "eslint": "=8",
-    "eslint-plugin-jsdoc": "^48.9.3",
+    "cross-env": "^7.0.3",
+    "eslint": "^9.10.0",
+    "eslint-config-prettier": "^9.1.0",
     "eslint-plugin-mocha": "^10.5.0",
-    "eslint-plugin-promise": "^6.6.0",
-    "jsdoc-to-markdown": "^8.0.3",
-    "knip": "^5.27.0",
-    "mocha": "^10.7.0",
-    "release-it": "^17.6.0"
+    "eslint-plugin-simple-import-sort": "^12.1.1",
+    "eslint-plugin-tsdoc": "^0.3.0",
+    "jsdom-global": "^3.0.2",
+    "knip": "^5.30.2",
+    "lefthook": "^1.7.15",
+    "mocha": "^10.7.3",
+    "nyc": "^17.0.0",
+    "prettier": "^3.3.3",
+    "release-it": "^17.6.0",
+    "rimraf": "^6.0.1",
+    "rollup": "^4.21.3",
+    "rollup-plugin-dts": "^6.1.1",
+    "source-map-support": "^0.5.21",
+    "ts-node": "^10.9.2",
+    "tslib": "^2.7.0",
+    "typedoc": "^0.26.7",
+    "typedoc-plugin-mdn-links": "^3.2.12",
+    "typedoc-plugin-replace-text": "^4.0.0",
+    "typedoc-plugin-zod": "^1.2.1",
+    "typescript": "^5.6.2",
+    "typescript-eslint": "^8.6.0"
   },
   "exports": {
     ".": {
-      "import": "./lib/index.js",
-      "require": "./dist/default/lib/index.js"
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/mjs/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/cjs/index.js"
+      }
     }
   },
-  "main": "./lib/index.js",
-  "mocha": {
-    "exclude": [
-      "./dist/**",
-      "./node_modules/**",
-      "./**/*.json"
-    ],
-    "require": [
-      "@babel/register"
-    ],
-    "spec": "./**/*.test.!(*.*)",
-    "timeout": 60000
+  "files": [
+    "dist"
+  ],
+  "homepage": "https://github.com/karmaniverous/entity-manager#readme",
+  "keywords": [
+    "dynamo-db",
+    "sharding"
+  ],
+  "license": "BSD-3-Clause",
+  "main": "dist/cjs/index.js",
+  "module": "dist/mjs/index.js",
+  "name": "@karmaniverous/entity-manager",
+  "publishConfig": {
+    "access": "public"
   },
   "release-it": {
+    "git": {
+      "changelog": "npx auto-changelog --stdout --commit-limit false --unreleased --template https://raw.githubusercontent.com/release-it/release-it/main/templates/changelog-compact.hbs",
+      "commitMessage": "chore: release v${version}",
+      "requireBranch": "main"
+    },
     "github": {
       "release": true
     },
+    "hooks": {
+      "after:init": [
+        "npm run lint",
+        "npm run test",
+        "npm run build"
+      ],
+      "before:npm:release": [
+        "npx auto-changelog -p",
+        "npm run docs",
+        "git add -A"
+      ],
+      "after:release": [
+        "git switch -c release/${version}",
+        "git push -u origin release/${version}",
+        "git switch ${branchName}"
+      ]
+    },
     "npm": {
       "publish": true
     }
   },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/karmaniverous/entity-manager.git"
+  },
   "scripts": {
-    "lint": "eslint lib/**",
-    "test": "mocha",
-    "build": "babel lib -d dist/default/lib --delete-dir-on-start --config-file ./dist/default/.babelrc",
-    "doc": "jsdoc2md -c doc/jsdoc.config.json -f lib/**/*.* -t doc/api-template.hbs > doc/2-api.jsdoc2.md && concat-md doc --hide-anchor-links > README.md",
+    "build": "rimraf dist && rollup --config rollup.config.ts --configPlugin @rollup/plugin-typescript",
+    "docs": "typedoc",
     "knip": "knip",
-    "prerelease": "npm run lint && npm run test && npm run build && npm run doc",
-    "release": "release-it"
+    "lint": "eslint src/** && prettier -c src",
+    "lint:fix": "eslint --fix src/** && prettier --write src",
+    "release": "dotenvx run -f .env.local -- release-it",
+    "release:pre": "dotenvx run -f .env.local -- release-it --no-git.requireBranch --github.prerelease --preRelease",
+    "test": "dotenvx run --quiet --log-level=LOG_LEVEL=debug -- nyc mocha"
   },
-  "type": "module"
+  "type": "module",
+  "types": "dist/index.d.ts",
+  "version": "6.0.0"
 }

package/.env

@@ -1 +0,0 @@
-# Load with getdotenv: https://github.com/karmaniverous/get-dotenv

package/dist/default/lib/EntityManager/EntityManager.js

@@ -1,423 +0,0 @@
-"use strict";
-
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
-exports.EntityManager = void 0;
-var _zipObject2 = _interopRequireDefault(require("lodash/zipObject"));
-var _map2 = _interopRequireDefault(require("lodash/map"));
-var _isEmpty2 = _interopRequireDefault(require("lodash/isEmpty"));
-var _fromPairs2 = _interopRequireDefault(require("lodash/fromPairs"));
-var _isPlainObject2 = _interopRequireDefault(require("lodash/isPlainObject"));
-var _isInteger2 = _interopRequireDefault(require("lodash/isInteger"));
-var _isUndefined2 = _interopRequireDefault(require("lodash/isUndefined"));
-var _sortedUniq2 = _interopRequireDefault(require("lodash/sortedUniq"));
-var _has2 = _interopRequireDefault(require("lodash/has"));
-var _entries2 = _interopRequireDefault(require("lodash/entries"));
-var _sortBy2 = _interopRequireDefault(require("lodash/sortBy"));
-var _sortedUniqBy2 = _interopRequireDefault(require("lodash/sortedUniqBy"));
-var _isFunction2 = _interopRequireDefault(require("lodash/isFunction"));
-var _isArray2 = _interopRequireDefault(require("lodash/isArray"));
-var _forEach2 = _interopRequireDefault(require("lodash/forEach"));
-var _isNil2 = _interopRequireDefault(require("lodash/isNil"));
-var _cloneDeep2 = _interopRequireDefault(require("lodash/cloneDeep"));
-var _inspectParametersDeclaration = require("inspect-parameters-declaration");
-var _PrivateEntityManager = require("./PrivateEntityManager.js");
-function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
-/**
- * @module entity-manager
- */
-
-/**
- * Manage DynamoDb entities.
- *
- * @class
- */
-class EntityManager {
-  #entityManager;
-
-  /**
-   * Create an EntityManager instance.
-   *
-   * @param {object} options - Options object.
-   * @param {object} [options.config] - EntityManager configuration object (see {@link https://github.com/karmaniverous/entity-manager#configuration README} for a breakdown).
-   * @param {object} [options.logger] - Logger instance (defaults to console, must support error & debug methods).
-   * @returns {EntityManager} EntityManager instance.
-   * @throws {Error} If config is invalid.
-   * @throws {Error} If logger is invalid.
-   */
-  constructor(_ref) {
-    let {
-      config,
-      logger
-    } = _ref;
-    this.#entityManager = new _PrivateEntityManager.PrivateEntityManager({
-      config,
-      logger
-    });
-  }
-
-  /**
-   * Add sharded keys to an entity item. Does not mutate original item.
-   *
-   * @param {string} entityToken - Entity token.
-   * @param {object} item - Entity item.
-   * @param {boolean} [overwrite] - Overwrite existing properties.
-   * @returns {object} Decorated entity item.
-   * @throws {Error} If entityToken is invalid.
-   * @throws {Error} If item is invalid.
-   */
-  addKeys(entityToken, item) {
-    let overwrite = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : false;
-    this.#entityManager.logger.debug(`adding sharded index keys to ${entityToken}${overwrite ? ' with overwrite' : ''}...`, {
-      item
-    });
-
-    // Validate item.
-    this.#entityManager.validateItem(item);
-
-    // Clone item.
-    const newItem = (0, _cloneDeep2.default)(item);
-
-    // Get entity config.
-    const {
-      shardKeyToken
-    } = this.#entityManager;
-    const {
-      keys
-    } = this.#entityManager.getEntityConfig(entityToken);
-
-    // Add shardKey.
-    if (overwrite || (0, _isNil2.default)(newItem[shardKeyToken])) {
-      newItem[shardKeyToken] = this.calcShardKey(entityToken, newItem);
-    }
-
-    // Add keys.
-    (0, _forEach2.default)(keys, (_ref2, key) => {
-      let {
-        encode
-      } = _ref2;
-      if (overwrite || (0, _isNil2.default)(newItem[key])) newItem[key] = encode(newItem);
-    });
-    this.#entityManager.logger.debug('done', {
-      newItem
-    });
-
-    // Remove undefined shardKey.
-    if ((0, _isNil2.default)(newItem[shardKeyToken])) delete newItem[shardKeyToken];
-    return newItem;
-  }
-
-  /**
-   * Calculated the shard key for an entity item.
-   *
-   * @param {string} entityToken - Entity token.
-   * @param {object} item - Entity item.
-   * @returns {string} Shard key.
-   */
-  calcShardKey(entityToken, item) {
-    const {
-      sharding
-    } = this.#entityManager.getEntityConfig(entityToken);
-    const entityKey = sharding.entityKey(item);
-    const timestamp = sharding.timestamp(item);
-    return this.#entityManager.getShardKey(entityToken, entityKey, timestamp);
-  }
-
-  /**
-   * Condense an index object into a delimited string.
-   *
-   * @param {string} entityToken - Entity token.
-   * @param {string|string[]} indexToken - Index token or array of key tokens.
-   * @param {object} index - Index object.
-   * @param {string} [delimiter] - Delimiter.
-   * @returns {string} Dehydrated index.
-   * @throws {Error} If entityToken is invalid.
-   * @throws {Error} If indexToken is invalid.
-   * @throws {Error} If item is invalid.
-   */
-  dehydrateIndex(entityToken, indexToken, index) {
-    let delimiter = arguments.length > 3 && arguments[3] !== undefined ? arguments[3] : '~';
-    // Validate item.
-    this.#entityManager.validateItem(index);
-    const indexComponents = (0, _isArray2.default)(indexToken) ? indexToken : this.#entityManager.getIndexComponents(entityToken, indexToken);
-    const indexProperties = indexComponents.reduce((properties, component) => {
-      const {
-        decode
-      } = this.getKey(entityToken, component);
-      if (!(0, _isFunction2.default)(decode)) throw new Error(`no decode function defined on ${entityToken} entity key '${component}'`);
-      return {
-        ...properties,
-        ...(decode(index[component] ?? '') ?? {})
-      };
-    }, {});
-    return (0, _sortedUniqBy2.default)((0, _sortBy2.default)((0, _entries2.default)(indexProperties), _ref3 => {
-      let [key] = _ref3;
-      return key;
-    }), _ref4 => {
-      let [key] = _ref4;
-      return key;
-    }).map(_ref5 => {
-      let [, value] = _ref5;
-      return value;
-    }).join(delimiter);
-  }
-
-  /**
-   * Return the config for a given entity key token.
-   *
-   * @param {string} entityToken - Entity token.
-   * @param {string} keyToken - Key token.
-   * @returns {object} Entity key config.
-   */
-  getKey(entityToken, keyToken) {
-    const {
-      keys
-    } = this.#entityManager.getEntityConfig(entityToken);
-    if (!(0, _has2.default)(keys, keyToken)) throw new Error(`Key '${keyToken}' does not exist for entity '${entityToken}'.`);
-    return keys[keyToken];
-  }
-
-  /**
-   * Return an array of sharded keys valid for a given entity token & timestamp.
-   *
-   * @param {string} entityToken - Entity token.
-   * @param {string} keyToken - Key token.
-   * @param {object} item - Entity item sufficiently populated to generate property keyToken.
-   * @param {number} timestamp - Timestamp.
-   * @returns {string[]} Array of keys.
-   * @throws {Error} If entityToken is invalid.
-   * @throws {Error} If item is invalid.
-   * @throws {Error} If keyToken is invalid.
-   * @throws {Error} If timestamp is invalid.
-   */
-  getKeySpace(entityToken, keyToken, item) {
-    let timestamp = arguments.length > 3 && arguments[3] !== undefined ? arguments[3] : Date.now();
-    this.#entityManager.logger.debug(`getting shard key space for ${entityToken} on key '${keyToken}' at timestamp ${timestamp}...`, {
-      item
-    });
-    const shardKeySpace = this.#entityManager.getShardKeySpace(entityToken, timestamp);
-    const result = (0, _sortedUniq2.default)(shardKeySpace.map(shardKey => this.getKey(entityToken, keyToken).encode({
-      ...item,
-      [this.#entityManager.shardKeyToken]: shardKey
-    })));
-    this.#entityManager.logger.debug('done', {
-      result
-    });
-    return result;
-  }
-
-  /**
-   * @typedef {object} ShardQueryResult
-   * @property {any[]} items - Query result array.
-   * @property {*} pageKey - Shard page key.
-   */
-
-  /**
-   * Shard query function
-   *
-   * @callback ShardQueryFunction
-   * @param {string} shardedKey - Sharded key.
-   * @param {*} [pageKey] - Page key.
-   * @param {number} [limit] - Request limit.
-   * @returns {Promise<ShardQueryResult>} Sharded query result.
-   */
-
-  /**
-   * @typedef {object} ShardedQueryResult
-   * @property {any[]} items - Query result array.
-   * @property {object} pageKeys - Shard page keys.
-   */
-
-  /**
-   * Query an entity across shards.
-   *
-   * @param {object} options - Query options.
-   * @param {string} options.entityToken - Entity token.
-   * @param {string} [options.keyToken] - Key token.
-   * @param {object} [options.item] - Entity item sufficiently populated to generate property keyToken.
-   * @param {ShardQueryFunction} options.shardQuery - Sharded query function.
-   * @param {number} [options.limit] - Request limit.
-   * @param {object} [options.pageKeys] - Map of shard page keys.
-   * @param {number} [options.pageSize] - Request page size.
-   * @returns {Promise<ShardedQueryResult>} Sharded query result.
-   */
-  async query() {
-    let {
-      entityToken,
-      keyToken = 'entityPK',
-      item = {},
-      shardQuery,
-      limit,
-      pageKeys,
-      pageSize
-    } = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {};
-    // Validate params.
-    this.#entityManager.validateKeyToken(entityToken, keyToken);
-    this.#entityManager.validateItem(item);
-    if (!(0, _isFunction2.default)(shardQuery)) throw new Error('shardQuery must be a function');
-    if (!(0, _isUndefined2.default)(limit) && !(limit === Infinity || (0, _isInteger2.default)(limit) && limit >= 1)) throw new Error('limit must be a positive integer or Infinity.');
-    if (!(0, _isUndefined2.default)(pageKeys) && !(0, _isPlainObject2.default)(pageKeys)) throw new Error('pageKeys must be an object');
-    if (!(0, _isUndefined2.default)(pageSize) && !((0, _isInteger2.default)(pageSize) && pageSize >= 1)) throw new Error('pageSize must be a positive integer');
-
-    // Apply default limit.
-    limit ??= this.#entityManager.getEntityConfig(entityToken).defaultLimit;
-
-    // Apply default pageSize.
-    pageSize ??= this.#entityManager.getEntityConfig(entityToken).defaultPageSize;
-
-    // Generate default pageKeys if not provided
-    pageKeys ??= (0, _fromPairs2.default)(this.getKeySpace(entityToken, keyToken, item).map(shardedKey => [shardedKey, undefined]));
-    this.#entityManager.logger.debug('EntityManager.query parsed params', {
-      entityToken,
-      keyToken,
-      item,
-      shardQuery,
-      limit,
-      pageKeys,
-      pageSize
-    });
-
-    // Return empty result if no pageKeys.
-    if ((0, _isEmpty2.default)(pageKeys)) return {
-      count: 0,
-      items: [],
-      pageKeys: {}
-    };
-
-    // Iterate search over pages.
-    let page = 0;
-    const result = {
-      count: 0,
-      items: [],
-      pageKeys
-    };
-    do {
-      // TODO: This loop will blow up as shards scale, since at a minimum it will return shardCount x pageSize
-      // items, which may be >> limit. Probably the way to fix this is to limit the number of shards queried per
-      // iteration in order to keep shardsQueried * pageSize > (limit - items.length) but only just.
-
-      // Query every shard in pageKeys.
-      const shardQueryResults = await Promise.all((0, _map2.default)(result.pageKeys, (pageKey, shardedKey) => new Promise(resolve => shardQuery(shardedKey, pageKey, pageSize).then(_ref6 => {
-        let {
-          count,
-          items,
-          pageKey
-        } = _ref6;
-        return resolve({
-          count,
-          items,
-          pageKey,
-          shardedKey
-        });
-      }))));
-
-      // Reduce shardQueryResults into a single result.
-      const pageResult = shardQueryResults.reduce((shardedQueryResult, _ref7) => {
-        let {
-          count,
-          items,
-          pageKey,
-          shardedKey
-        } = _ref7;
-        return {
-          count: shardedQueryResult.count + count,
-          items: [...shardedQueryResult.items, ...items],
-          pageKeys: {
-            ...shardedQueryResult.pageKeys,
-            ...((0, _isUndefined2.default)(pageKey) ? {} : {
-              [shardedKey]: pageKey
-            })
-          }
-        };
-      }, {
-        count: 0,
-        items: [],
-        pageKeys: {}
-      });
-      this.#entityManager.logger.debug(`EntityManager.query page ${page} result`, {
-        pageResult
-      });
-      result.count += pageResult.count;
-      result.items = [...result.items, ...pageResult.items];
-      result.pageKeys = pageResult.pageKeys;
-      page++;
-    } while (result.items.length < limit && !(0, _isEmpty2.default)(result.pageKeys));
-    return result;
-  }
-
-  /**
-   * Convert a delimited string into a named index key.
-   *
-   * @param {string} entityToken - Entity token.
-   * @param {string|string[]} indexToken - Index token or array of key tokens.
-   * @param {string} value - Dehydrated index value.
-   * @param {string} [delimiter] - Delimiter.
-   * @returns {object} Rehydrated index key.
-   * @throws {Error} If entityToken is invalid.
-   * @throws {Error} If indexToken is invalid.
-   */
-  rehydrateIndex(entityToken, indexToken) {
-    let value = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : '';
-    let delimiter = arguments.length > 3 && arguments[3] !== undefined ? arguments[3] : '~';
-    const indexComponents = (0, _isArray2.default)(indexToken) ? indexToken : this.#entityManager.getIndexComponents(entityToken, indexToken);
-    const indexKeys = (0, _sortBy2.default)(indexComponents.reduce((keys, component) => {
-      const {
-        encode
-      } = this.getKey(entityToken, component);
-      return [...new Set([...keys, ...(0, _inspectParametersDeclaration.getParametersNames)(encode)]).values()];
-    }, []));
-    const indexProperties = (0, _zipObject2.default)(indexKeys, value.split(delimiter));
-    return indexComponents.reduce((index, component) => {
-      const {
-        encode
-      } = this.getKey(entityToken, component);
-      return {
-        ...index,
-        [component]: encode(indexProperties)
-      };
-    }, {});
-  }
-
-  /**
-   * Remove sharded keys from an entity item. Does not mutate original item.
-   *
-   * @param {string} entityToken - Entity token.
-   * @param {object} item - Entity item.
-   * @returns {object} Stripped entity item.
-   * @throws {Error} If entityToken is invalid.
-   * @throws {Error} If item is invalid.
-   */
-  removeKeys(entityToken, item) {
-    this.#entityManager.logger.debug(`removing sharded index keys from ${entityToken}...`, {
-      item
-    });
-
-    // Validate item.
-    this.#entityManager.validateItem(item);
-
-    // Clone item.
-    const newItem = (0, _cloneDeep2.default)(item);
-
-    // Get entity config.
-    const {
-      shardKeyToken
-    } = this.#entityManager;
-    const {
-      keys
-    } = this.#entityManager.getEntityConfig(entityToken);
-
-    // Remove shardKey.
-    delete newItem[shardKeyToken];
-
-    // Remove keys.
-    (0, _forEach2.default)(keys, (value, key) => {
-      if (!value.retain) delete newItem[key];
-    });
-    this.#entityManager.logger.debug('done', {
-      newItem
-    });
-    return newItem;
-  }
-}
-exports.EntityManager = EntityManager;