@itwin/workspace-editor 3.0.0-dev.176 → 3.0.0-dev.177

package/package.json

@@ -3,7 +3,7 @@
   "private": false,
   "license": "MIT",
   "main": "lib/WorkspaceEditor.js",
-  "version": "3.0.0-dev.176",
+  "version": "3.0.0-dev.177",
   "bin": {
     "WorkspaceEditor": "./lib/WorkspaceEditor.js"
   },
@@ -12,15 +12,15 @@
     "url": "https://github.com/iTwin/itwinjs-core/tree/master/utils/workspace-editor"
   },
   "dependencies": {
-    "@itwin/core-bentley": "3.0.0-dev.176",
-    "@itwin/core-common": "3.0.0-dev.176",
-    "@itwin/core-backend": "3.0.0-dev.176",
+    "@itwin/core-bentley": "3.0.0-dev.177",
+    "@itwin/core-common": "3.0.0-dev.177",
+    "@itwin/core-backend": "3.0.0-dev.177",
     "glob": "^7.1.2",
     "yargs": "^16.0.0"
   },
   "devDependencies": {
-    "@itwin/build-tools": "3.0.0-dev.176",
-    "@itwin/eslint-plugin": "3.0.0-dev.176",
+    "@itwin/build-tools": "3.0.0-dev.177",
+    "@itwin/eslint-plugin": "3.0.0-dev.177",
     "@types/chai": "^4.1.4",
     "@types/mocha": "^8.2.2",
     "@types/yargs": "^12.0.5",
@@ -45,5 +45,6 @@
     "lint": "eslint --max-warnings 0 \"./src/**/*.ts\" 1>&2",
     "start": "node ./lib/Main.js",
     "test": ""
-  }
+  },
+  "readme": "# WorkspaceEditor\r\n\r\n**WorkspaceEditor** is a command line utility for creating and editing `WorkspaceResources` in iTwin `WorkspaceDb`s, and for uploading and downloading `WorkspaceDb`s to cloud `WorkspaceContainer`s.\r\n\r\nAn iTwin `WorkspaceDb` may hold many `WorkSpaceResources`, each with a `WorkspaceResourceName` and `WorkspaceResourceType`. `WorkspaceEditor` adds, updates, deletes, and extracts *local files* into/from a `WorkspaceDb`.\r\n\r\n## Workspace Resource Types\r\n\r\nThere are 3 `WorkspaceResourceType`s that may be accessed by `@itwin-backend` applications at runtime via the `WorkspaceContainer` api:\r\n\r\n 1. `string` accessed via the `getString` method\r\n 2. `blob`  binary data accessed via the `getBlob` method\r\n 3. `file`  extracted to a local file via the `getFile` method\r\n\r\nSeveral `WorkspaceEditor` commands require a `--type` argument to specify which `WorkspaceResourceType` to use.\r\n\r\n## The WorkspaceContainer Directory\r\n\r\n`WorkspaceDb`s are located by iTwin.js inside a `WorkspaceContainer` subdirectory within the `WorkspaceContainerDir` directory. `WorkspaceContainerDir` is specified as a directory name in the `workspace.containerDir` member on the `configuration` argument of  `IModelHost.startup`. The default value is `%localappdata%/iTwin/Workspace`. WorkspaceEditor will normally create and edit `WorkspaceDb`s in the default directory, but if you wish to use a different directory, supply the `--directory` option to specify a different `WorkspaceContainerDir` location.\r\n\r\n## Workspace dbName\r\n\r\nThe WorkspaceEditor commands all take a `dbName` option to specify the `WorkspaceDb` on which to operate. The WorkspaceDb is located inside the `WorkspaceContainerId` specified with the --containerId argument. `WorkspaceDbName`s must be less than 255 characters, may not have leading or trailing whitespace, and may not use any reserved path specification characters (see documentation for `WorkspaceDbName` for details.) The `WorkspaceDb` filename is formed via: `${WorkspaceContainerDir}/${WorkspaceContainerId}/${WorkspaceDbName}.itwin-workspace`.\r\n\r\n## WorkspaceEditor Config file\r\n\r\n`WorkspaceEditor` accepts the `--config` option to specify the name of a JSON file that holds values for `WorkspaceEditor` options. By default, `WorkspaceEditor` looks in the current directory for a file named `workspaceEditor.json`.\r\n\r\nExample:\r\n\r\n```sh\r\n> WorkspaceEdit --config myConfig.json list db1\r\n...\r\n```\r\n\r\n```json\r\n> cat myConfig.json\r\n{\r\n  \"directory\": \"d:/projData/112/\",\r\n  \"containerId\": \"proj112\",\r\n  \"accountName\": \"smsblob1\",\r\n  \"sasToken\": \"<valid token here>\"\r\n}\r\n```\r\n\r\n> Note: config files **must** have a `.json` extension.\r\n\r\n## WorkspaceEditor Commands\r\n\r\nThe following WorkspaceEditor commands are available:\r\n\r\n### Create\r\n\r\nCreate a new empty `WorkspaceDb`.\r\n\r\nExample:\r\n\r\n```sh\r\n> WorkspaceEdit create proj\r\ncreated WorkspaceDb C:\\Users\\User.Name\\AppData\\Local\\iTwin\\Workspace\\proj112\\proj.itwin-workspace\r\n```\r\n\r\n### Add\r\n\r\nAdd one or more local files as resources into a `WorkspaceDb`.\r\n\r\n`--type` specifies the type of resource(s) to add. Required\r\n`--name` specifies the name of the resource. Defaults to the name of the local file.\r\n`--root` specifies a root directory when adding multiple files. The parts of the path after the root are saved in the resource name (see example below.)\r\n`--update` indicates that an existing resource should be updated (i.e. replaced.)\r\n\r\n> Note: `--name`  is only applicable when adding a single file.\r\n\r\nExamples:\r\n\r\n```sh\r\n> WorkspaceEditor add proj -n equipment-data D:\\data\\equip.dat\r\nWorkspaceDb [C:\\Users\\User.Name\\AppData\\Local\\iTwin\\Workspace\\proj112\\proj.itwin-workspace]\r\n added \"D:\\data\\equip.dat\" as file resource [equipment-data]\r\n```\r\n\r\n```sh\r\n> WorkspaceEditor add proj -string *.json\r\nWorkspaceDb [C:\\Users\\User.Name\\AppData\\Local\\iTwin\\Workspace\\proj112\\proj.itwin-workspace]\r\n added \"specs.json\" as string resource [specs.json]\r\n added \"vendor.json\" as string resource [vendor.json]\r\n ```\r\n\r\n```sh\r\n > WorkspaceEditor add proj -t blob -r d:\\projData\\112\\ **\\*.dict\r\nWorkspaceDb [C:\\Users\\User.Name\\AppData\\Local\\iTwin\\Workspace\\proj112\\proj.itwin-workspace]\r\n added \"d:\\projData\\112\\TernKit\\KDEO5814.dict\" as blob resource [TernKit/KDEO5814.dict]\r\n added \"d:\\projData\\112\\TernKit\\KDEO5815.dict\" as blob resource [TernKit/KDEO5815.dict]\r\n added \"d:\\projData\\112\\UniSpace\\KDEO5814.dict\" as blob resource [UniSpace/KDEO5814.dict]\r\n added \"d:\\projData\\112\\UniSpace\\KDEO5815.dict\" as blob resource [UniSpace/KDEO5815.dict]\r\n added \"d:\\projData\\112\\Sparks\\KDEO5814.dict\" as blob resource [Sparks/KDEO5814.dict]\r\n added \"d:\\projData\\112\\Sparks\\KDEO5815.dict\" as blob resource [Sparks/KDEO5815.dict]\r\n added \"d:\\projData\\112\\Sparks\\KDEO5816.dict\" as blob resource [Sparks/KDEO5816.dict]\r\n ```\r\n\r\n### List\r\n\r\nList the contents of a `WorkspaceDb`. By default it will show all 3 resource types. To limit the output to specific types, supply the `--strings`, `--blobs`, or `--files` options.\r\n\r\nExamples:\r\n\r\n```sh\r\n> WorkspaceEditor list proj\r\nWorkspaceDb [C:\\Users\\User.Name\\AppData\\Local\\iTwin\\Workspace\\proj112\\proj.itwin-workspace]\r\n strings:\r\n  name=[specs.json], size=12050\r\n  name=[vendor.json], size=31335\r\n blobs:\r\n  name=[TernKit/KDEO5814.dict], size=144221\r\n  name=[TernKit/KDEO5815.dict], size=89600\r\n  name=[UniSpace/KDEO5814.dict], size=144384\r\n  name=[UniSpace/KDEO5815.dict], size=89600\r\n  name=[Sparks/KDEO5814.dict], size=144384\r\n  name=[Sparks/KDEO5815.dict], size=109056\r\n  name=[Sparks/KDEO5816.dict], size=70144\r\n files:\r\n  name=[equipment-data], size=14484, ext=\"dat\", date=Thu Mar 12 2015 13:52:51 GMT-0400\r\n```\r\n\r\n```sh\r\n> WorkspaceEditor list proj --strings\r\nWorkspaceDb [C:\\Users\\User.Name\\AppData\\Local\\iTwin\\Workspace\\proj112\\proj.itwin-workspace]\r\n strings:\r\n  name=[specs.json], size=12050\r\n  name=[vendor.json], size=31335\r\n```\r\n\r\n### Extract\r\n\r\nExtract a `WorkspaceResource` from a `WorkspaceDb` into a local file.\r\n\r\nExample:\r\n```sh\r\n> WorkspaceEditor extract proj -t blob UniSpace/KDEO5815.dict d:\\temp\\kd.dict\r\nWorkspaceDb [C:\\Users\\User.Name\\AppData\\Local\\iTwin\\Workspace\\proj112\\proj.itwin-workspace]\r\n blob resource [UniSpace/KDEO5815.dict] extracted to \"d:\\temp\\kd.dict\"\r\n```\r\n\r\n### Delete\r\n\r\nDelete an existing `WorkspaceResource` from a `WorkspaceDb`.\r\n\r\nExample:\r\n```sh\r\n> WorkspaceEditor delete proj -t blob UniSpace/KDEO5815.dict\r\nWorkspaceDb [C:\\Users\\User.Name\\AppData\\Local\\iTwin\\Workspace\\proj112\\proj.itwin-workspace]\r\n deleted blob resource [UniSpace/KDEO5815.dict]\r\n```\r\n\r\n### Vacuum\r\n\r\n[Vacuum](https://www.sqlite.org/lang_vacuum.html) a `WorkspaceDb`. This can make a `WorkspaceDb` smaller and more efficient to access.\r\n\r\nExample:\r\n```sh\r\n> WorkspaceEditor vacuum proj\r\nWorkspaceDb [C:\\Users\\User.Name\\AppData\\Local\\iTwin\\Workspace\\proj112\\proj.itwin-workspace] vacuumed\r\n```\r\n"
 }