Merge pull request #1122 from JupiterOne/readonly-iterate-graph-object

Mark graph object readonly

CHANGELOG.md

@@ -9,6 +9,20 @@ and this project adheres to
 
 # Unreleased
 
+# 13.6.0 - 2024-09-19
+
+- Minor breaking change to JobState methods iterateEntities and
+  iterateRelationships function signatures. The graph object passed to the
+  iteratee is now Readonly. The intention is to prevent modification of the
+  object during iteration. This is not a breaking change since the long-standing
+  understanding is that these objects should never be modified once added to the
+  jobState.
+
+```diff
+- export type GraphObjectIteratee<T> = (obj: T) => void | Promise<void>;
++ export type GraphObjectIteratee<T> = (obj: Readonly<T>) => void | Promise<void>;
+```
+
 # 13.5.2 - 2024-09-17
 
 - Temporary logging that should be removed after investigation.

lerna.json

@@ -4,5 +4,5 @@
     "packages/integration-sdk-*",
     "packages/cli"
   ],
-  "version": "13.5.2"
+  "version": "13.6.0"
 }

packages/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jupiterone/cli",
-  "version": "13.5.2",
+  "version": "13.6.0",
   "description": "The JupiterOne cli",
   "main": "dist/src/index.js",
   "types": "dist/src/index.d.ts",
@@ -24,8 +24,8 @@
     "test": "jest"
   },
   "dependencies": {
-    "@jupiterone/integration-sdk-core": "^13.5.2",
-    "@jupiterone/integration-sdk-runtime": "^13.5.2",
+    "@jupiterone/integration-sdk-core": "^13.6.0",
+    "@jupiterone/integration-sdk-runtime": "^13.6.0",
     "@lifeomic/attempt": "^3.0.3",
     "commander": "^5.0.0",
     "globby": "^11.0.1",

packages/integration-sdk-benchmark/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jupiterone/integration-sdk-benchmark",
-  "version": "13.5.2",
+  "version": "13.6.0",
   "private": true,
   "description": "SDK benchmarking scripts",
   "main": "./src/index.js",
@@ -15,8 +15,8 @@
     "benchmark": "for file in ./src/benchmarks/*; do npm run prebenchmark && node $file; done"
   },
   "dependencies": {
-    "@jupiterone/integration-sdk-core": "^13.5.2",
-    "@jupiterone/integration-sdk-runtime": "^13.5.2",
+    "@jupiterone/integration-sdk-core": "^13.6.0",
+    "@jupiterone/integration-sdk-runtime": "^13.6.0",
     "benchmark": "^2.1.4"
   }
 }

packages/integration-sdk-cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jupiterone/integration-sdk-cli",
-  "version": "13.5.2",
+  "version": "13.6.0",
   "description": "The SDK for developing JupiterOne integrations",
   "main": "dist/src/index.js",
   "types": "dist/src/index.d.ts",
@@ -26,8 +26,8 @@
   },
   "dependencies": {
     "@jupiterone/data-model": "^0.61.11",
-    "@jupiterone/integration-sdk-core": "^13.5.2",
-    "@jupiterone/integration-sdk-runtime": "^13.5.2",
+    "@jupiterone/integration-sdk-core": "^13.6.0",
+    "@jupiterone/integration-sdk-runtime": "^13.6.0",
     "chalk": "^4",
     "commander": "^9.4.0",
     "ejs": "^3.1.9",
@@ -45,7 +45,7 @@
     "url-exists": "^1.0.3"
   },
   "devDependencies": {
-    "@jupiterone/integration-sdk-private-test-utils": "^13.5.2",
+    "@jupiterone/integration-sdk-private-test-utils": "^13.6.0",
     "@pollyjs/adapter-node-http": "^6.0.5",
     "@pollyjs/core": "^6.0.5",
     "@pollyjs/persister-fs": "^6.0.5",

packages/integration-sdk-core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jupiterone/integration-sdk-core",
-  "version": "13.5.2",
+  "version": "13.6.0",
   "description": "The SDK for developing JupiterOne integrations",
   "main": "dist/src/index.js",
   "types": "dist/src/index.d.ts",
@@ -24,7 +24,7 @@
   },
   "dependencies": {
     "@jupiterone/data-model": "^0.61.11",
-    "@jupiterone/integration-sdk-entity-validator": "^13.5.2",
+    "@jupiterone/integration-sdk-entity-validator": "^13.6.0",
     "@sinclair/typebox": "^0.32.30",
     "lodash": "^4.17.21"
   },

packages/integration-sdk-core/src/types/jobState.ts

@@ -4,7 +4,7 @@ export interface GraphObjectFilter {
   _type: string;
 }
 
-export type GraphObjectIteratee<T> = (obj: T) => void | Promise<void>;
+export type GraphObjectIteratee<T> = (obj: Readonly<T>) => void | Promise<void>;
 export type GraphObjectIterateeOptions = {
   concurrency?: number;
 };
@@ -104,6 +104,11 @@ export interface JobState {
    * have run and therefore entities collected by those other steps should not
    * be expected to exist.
    *
+   * The graph object parameter passed to the iteratee is marked as Readonly.
+   * Once created and added to the JobState, graph objects should be considered immutable.
+   * Modifying a graph object during iteration can result in undesirable behavior
+   * since objects are upload to JupiterOne at non-regular intervals.
+   *
    * If concurrency is specified (defaults to 1), the iteratee will be executed
    * concurrently for graph objects that are found in memory and for
    * graph objects found in a given graph file. No specific ordering is guaranteed.
@@ -136,6 +141,11 @@ export interface JobState {
    * may not have run and therefore relationships collected by those other steps
    * should not be expected to exist.
    *
+   * The graph object parameter passed to the iteratee is marked as Readonly.
+   * Once created and added to the JobState, graph objects should be considered immutable.
+   * Modifying a graph object during iteration can result in undesirable behavior
+   * since objects are upload to JupiterOne at non-regular intervals.
+   *
    * If concurrency is specified (defaults to 1), the iteratee will be executed
    * concurrently for graph objects that are found in memory and for
    * graph objects found in a given graph file. No specific ordering is guaranteed.

packages/integration-sdk-dev-tools/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jupiterone/integration-sdk-dev-tools",
-  "version": "13.5.2",
+  "version": "13.6.0",
   "description": "A collection of developer tools that will assist with building integrations.",
   "repository": "[email protected]:JupiterOne/sdk.git",
   "author": "JupiterOne <[email protected]>",
@@ -15,8 +15,8 @@
     "access": "public"
   },
   "dependencies": {
-    "@jupiterone/integration-sdk-cli": "^13.5.2",
-    "@jupiterone/integration-sdk-testing": "^13.5.2",
+    "@jupiterone/integration-sdk-cli": "^13.6.0",
+    "@jupiterone/integration-sdk-testing": "^13.6.0",
     "@types/jest": "^29.5.3",
     "@types/node": "^18",
     "@typescript-eslint/eslint-plugin": "^6.2.1",

packages/integration-sdk-entities/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jupiterone/integration-sdk-entities",
-  "version": "13.5.2",
+  "version": "13.6.0",
   "description": "Generated types for the JupiterOne data-model",
   "main": "dist/src/index.js",
   "types": "dist/src/index.d.ts",

packages/integration-sdk-entity-validator/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jupiterone/integration-sdk-entity-validator",
-  "version": "13.5.2",
+  "version": "13.6.0",
   "description": "Validator for JupiterOne integration entities",
   "main": "dist/src/index.js",
   "types": "dist/src/index.d.ts",

packages/integration-sdk-http-client/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jupiterone/integration-sdk-http-client",
-  "version": "13.5.2",
+  "version": "13.6.0",
   "description": "The HTTP client for use in JupiterOne integrations",
   "main": "dist/src/index.js",
   "types": "dist/src/index.d.ts",
@@ -24,15 +24,15 @@
   },
   "dependencies": {
     "@jupiterone/hierarchical-token-bucket": "^0.3.1",
-    "@jupiterone/integration-sdk-core": "^13.5.2",
+    "@jupiterone/integration-sdk-core": "^13.6.0",
     "@lifeomic/attempt": "^3.0.3",
     "form-data": "^4.0.0",
     "lodash": "^4.17.21",
     "node-fetch": "^2.7.0"
   },
   "devDependencies": {
-    "@jupiterone/integration-sdk-dev-tools": "^13.5.2",
-    "@jupiterone/integration-sdk-private-test-utils": "^13.5.2",
+    "@jupiterone/integration-sdk-dev-tools": "^13.6.0",
+    "@jupiterone/integration-sdk-private-test-utils": "^13.6.0",
     "@types/node-fetch": "^2.6.11"
   },
   "bugs": {