@radiantearth/stac-migrate 1.2.0 → 1.4.0

package/README.md

@@ -2,23 +2,38 @@
 
 A library to update STAC files to the latest version (**1.0.0** at the moment of writing). Supports updating **STAC versions 0.6.0 and later**.
 
-Version of this library: **1.2.0**
+Version of this library: **1.4.0**
 
 ## Usage
 
+### JavaScript / Node
+
 Add to your project with `npm install @radiantearth/stac-migrate --save`
 
 Import the library: `const Migrate = require('@radiantearth/stac-migrate');`
 
-* Migrate (auto-detection): `Migrate.stac(stac: object) => object`<br />
+* Migrate (auto-detection): `Migrate.stac(stac: object, updateVersionNumber: boolean = true) => object`<br />
   *This method does not migrate the Commons extension - use `Migrate.item` if you have used the Commons extension.*
-* Migrate a STAC Collection: `Migrate.collection(collection: object) => object`
-* Migrate a STAC Catalog: `Migrate.catalog(catalog: object) => object`
-* Migrate a STAC Item: `Migrate.item(item: object, collection: object = null) => object`<br />
+* Migrate a STAC Collection: `Migrate.collection(collection: object, updateVersionNumber: boolean = true) => object`
+* Migrate a STAC Catalog: `Migrate.catalog(catalog: object, updateVersionNumber: boolean = true) => object`
+* Migrate a STAC Item: `Migrate.item(item: object, collection: object = null, updateVersionNumber: boolean = true) => object`<br />
   *The `collection` parameter is only required to migrate the Commons extension. Otherwise, you don't need to pass this paramater.*
+* Migrate a STAC ItemCollection: `Migrate.itemCollection(catalog: object, updateVersionNumber: boolean = true) => object`
 
 **Note:** All changes will be applied in-place! If you don't want the input object to change, make a deep clone before. If you don't have a library which supports this (e.g. [lodash](https://lodash.com/docs/4.17.15#cloneDeep)) you can simply use `var clone = JSON.parse(JSON.stringify(object));`.
 
+### CLI
+
+You can also use the CLI to migrate a single file.
+The commands follow the different methods above and has the same "restrictions" as above.
+
+* Migrate (auto-detection, override): `npx stac-migrate <source_path>`
+* Migrate (auto-detection, save to a different file with 4 spaces indentation): `npx stac-migrate <source_path> --dest <dest_path> --indent 4`
+* Migrate a STAC Collection: `npx stac-migrate <source_path> <dest_path> --collection`
+* Migrate a STAC Catalog: `npx stac-migrate <source_path> <dest_path> --catalog`
+* Migrate a STAC Item: `npx stac-migrate <source_path> <dest_path> --item --collection_path <collection_path>`
+* Migrate a STAC Item Collection: `npx stac-migrate <source_path> <dest_path> --item_collection`
+
 ##  Supported Extensions
 
 * Checksum (legacy, use `Migrate.enableMultihash(require('multihashes'))` to enable conversion from pre-0.9 checksums - disabled by default to keep the bundle size low)

package/bin/cli.js

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+const fs = require('fs');
+const yargs = require('yargs/yargs')
+const { hideBin } = require('yargs/helpers')
+const Migrate = require('../migrate');
+const package = require("../package.json");
+
+const args = yargs(hideBin(process.argv))
+  .option('_', {
+    type: 'string',
+    describe: 'File to load the STAC data from'
+  })
+  .option('dest', {
+    type: 'string',
+    description: 'File to save the result to',
+    alias: 'd'
+  })
+  .option('collection', {
+    type: 'boolean',
+    description: 'Enforce the collection migration',
+    conflicts: ['catalog', 'item', 'item_collection'],
+
+  })
+  .option('catalog', {
+    type: 'boolean',
+    description: 'Enforce the catalog migration',
+    conflicts: ['collection', 'item', 'item_collection']
+  })
+  .option('item', {
+    type: 'boolean',
+    description: 'Enforce the item migration',
+    conflicts: ['catalog', 'collection', 'item_collection']
+  })
+  .option('item_collection', {
+    type: 'boolean',
+    description: 'Enforce the item collection migration',
+    conflicts: ['catalog', 'collection', 'item']
+  })
+  .option('collection_path', {
+    type: 'string',
+    description: 'Pass the path to a collection to the item, only possible if --item has been specified.',
+    conflicts: ['catalog', 'collection', 'item_collection']
+  })
+  .option('indent', {
+    type: 'number',
+    description: 'Number of spaces to use for JSON indentation',
+    default: 2
+  })
+  .help()
+  .parse()
+
+run(args);
+
+function run(args) {
+  console.log("STAC Migrate v" + package.version);
+  let fn = ['collection', 'catalog', 'item', 'item_collection'].find(type => Boolean(args[type])) || 'stac';
+  if (fn === 'item_collection') {
+    fn = 'itemCollection';
+  }
+  if (args._.length !== 1) {
+    throw new Error("Please provide exactly one source file.");
+  }
+  let src = args._[0];
+  let dest = args.dest || src;
+
+  let dataStr = fs.readFileSync(src);
+  let dataObj = JSON.parse(dataStr);
+  let options = [dataObj];
+  if (fn === 'item') {
+    let collestionStr = fs.readFileSync(args.collection_path);
+    let collestionObj = JSON.parse(collestionStr);
+    options.push(collestionObj);
+  }
+  Migrate[fn](...options)
+  dataStr = JSON.stringify(dataObj, null, args.indent);
+  fs.writeFileSync(dest, dataStr);
+  console.log("Migrated successfully: " + dest);
+}

package/migrate.js

@@ -402,6 +402,8 @@ var Catalog = {
 		_.runAll(Catalog, catalog, catalog);
 
 		V.before('0.8.0') && _.populateExtensions(catalog, 'catalog') && DONE;
+
+		return catalog;
 	},
 
 	openeo(obj) {
@@ -442,6 +444,8 @@ var Collection = {
 
 		V.before('0.8.0') && _.populateExtensions(collection, 'collection') && DONE;
 		V.before('1.0.0-beta.1') && _.mapValues(collection, 'stac_extensions', ['assets'], ['item-assets']) && DONE;
+
+		return collection;
 	},
 
 	extent(collection) {
@@ -652,10 +656,28 @@ var Item = {
 
 		// Also populate extensions if commons has been implemented
 		(V.before('0.8.0') || commons) && _.populateExtensions(item, 'item') && DONE;
+
+		return item;
 	}
 
 };
 
+var ItemCollection = {
+
+	migrate(itemCollection, updateVersionNumber = true) {
+		_.ensure(itemCollection, 'type', 'FeatureCollection') && DONE;
+		_.ensure(itemCollection, 'features', []) && DONE;
+		_.ensure(itemCollection, 'links', []) && DONE;
+
+		_.runAll(ItemCollection, itemCollection, itemCollection);
+
+		itemCollection.features = itemCollection.features.map(feature => Item.migrate(feature, null, updateVersionNumber));
+
+		return itemCollection;
+	},
+
+};
+
 var Asset = {
 
 	migrateAll(context, field = 'assets') {
@@ -666,7 +688,10 @@ var Asset = {
 
 	migrate(asset, context) {
 		_.runAll(Asset, asset, context);
+
 		Fields.migrate(asset, context);
+
+		return asset;
 	},
 
 	mediaTypes(asset) {
@@ -699,6 +724,8 @@ var Fields = {
 
 	migrate(obj, context, summaries = false) {
 		_.runAll(Fields, obj, context, summaries);
+
+		return obj;
 	},
 
 	_commonMetadata(obj) {
@@ -892,24 +919,28 @@ var Fields = {
 var Migrate = {
 
 	item(item, collection = null, updateVersionNumber = true) {
-		Item.migrate(item, collection, updateVersionNumber);
-		return item;
+		return Item.migrate(item, collection, updateVersionNumber);
 	},
 	
 	catalog(catalog, updateVersionNumber = true) {
-		Catalog.migrate(catalog, updateVersionNumber);
-		return catalog;
+		return Catalog.migrate(catalog, updateVersionNumber);
 	},
 	
 	collection(collection, updateVersionNumber = true) {
-		Collection.migrate(collection, updateVersionNumber);
-		return collection;
+		return Collection.migrate(collection, updateVersionNumber);
+	},
+
+	itemCollection(itemCollection, updateVersionNumber = true) {
+		return ItemCollection.migrate(itemCollection, updateVersionNumber);
 	},
 	
 	stac(object, updateVersionNumber = true) {
 		if (object.type === 'Feature') {
 			return Migrate.item(object, null, updateVersionNumber);
 		}
+		else if (object.type === 'FeatureCollection') {
+			return Migrate.itemCollection(object, updateVersionNumber);
+		}
 		else if (object.type === 'Collection' || _.isDefined(object.extent) || _.isDefined(object.license)) {
 			return Migrate.collection(object, updateVersionNumber);
 		}

package/package.json

@@ -1,8 +1,11 @@
 {
 	"name": "@radiantearth/stac-migrate",
-	"version": "1.2.0",
+	"version": "1.4.0",
 	"description": "A library to update STAC files to the latest version.",
 	"main": "migrate.js",
+	"bin": {
+		"stac-migrate": "./bin/cli.js"
+	},
 	"bugs": {
 		"url": "https://github.com/stac-utils/stac-migrate/issues"
 	},
@@ -19,13 +22,15 @@
 	"license": "Apache-2.0",
 	"dependencies": {
 		"compare-versions": "^3.6.0",
-		"multihashes": "^3.1.2"
+		"multihashes": "^3.1.2",
+		"yargs": "^17.6.2"
 	},
 	"devDependencies": {
 		"jest": "^29.0.0",
 		"jest-html-reporter": "^3.3.0"
 	},
 	"files": [
+		"bin/cli.js",
 		"migrate.js"
 	],
 	"scripts": {