@graphcms/migration - npm Package Compare versions

Comparing version 0.0.10 to 0.0.11

package.json

 {
   "name": "@graphcms/migration",
-  "version": "0.0.10",
+  "version": "0.0.11",
   "description": "SDK for GraphCMS migrations",
@@ -5,0 +5,0 @@ "main": "lib/index.js",

README.md

@@ -5,11 +5,11 @@ # migration
 
-### Usage
+## Usage
 
 ```js
 // import migration library
-const { newMigration, FieldType } = require("@graphcms/migration")
+const { newMigration, FieldType } = require("@graphcms/migration");
 
 // create a new migration for an environment
 // using auth token and environment endpoint url.
-const migration = newMigration({authToken, endpoint})
+const migration = newMigration({ authToken, endpoint });
 
@@ -20,4 +20,4 @@ // create model
   apiIdPlural: "Authors",
-  displayName: "Author"
-})
+  displayName: "Author",
+});
 
@@ -28,18 +28,415 @@ // add fields
   displayName: "First Name",
-  type: FieldType.String
-})
+  type: FieldType.String,
+});
 author.addSimpleField({
   apiId: "lastName",
   displayName: "Last Name",
-  type: FieldType.String
+  type: FieldType.String,
 });
 
 // run migration
-migration.run()
+migration.run();
 ```
 
-### Docs
+## Table of Contents
 
+- [Migration](#migration)
+  - [New Migration](#newMigration)
+  - [Running a Migration](#runMigration)
+  - [DryRun a Migration](#dryRunMigration)
+- [Updating an Entity](#updatingEntity)
+- [Locale](#locale)
+  - [Creating a Locale](#createLocale)
+  - [Updating a Locale](#updateLocale)
+  - [Deleting a Locale](#deleteLocale)
+- [Stage](#stage)
+  - [Creating a Stage](#createStage)
+  - [Updating a Stage](#updateStage)
+  - [Deleting a Stage](#deleteStage)
+- [Enumerations](#enumerations)
+  - [Creating Enumeration](#createEnumeration)
+  - [Updating Enumeration](#updateEnumeration)
+  - [Deleting Enumeration](#deleteEnumeration)
+- [Models](#models)
+  - [Creating a Model](#createModel)
+  - [Updating a Model](#editModel)
+  - [Deleting a Model](#deleteModel)
+  - [Fields](#fields)
+    - [Creating a Field](#createField)
+    - [Updating a Field](#updateField)
+    - [Deleting a Field](#deleteField)
+
+<a name="migration"></a>
+
+## Migration
+
+<a name="newMigration"></a>
+
+### New Migration
+
+A migration is scoped to an environment. To create a migration, the following parameters are required.
+
+- Authentication Token `authToken`.
+
+  Can be retrieved from `Settings > API Access` on https://app.graphcms.com
+
+- Environment URL `endpoint`.
+
+  Can be retrieved from `Settings > Environments` on https://app.graphcms.com
+
+- Migration Name `name` [optional].
+
+  Every migration has a unique name. If unspecified, a name would be generated and will be part of the response of a successful migration.
+
+  Subsequent migrations with same name will fail.
+
+```js
+const { newMigration } = require("@graphcms/migration");
+const migration = newMigration({
+  authToken,
+  endpoint,
+  name, // optional
+});
+```
+
+<a name="runMigration"></a>
+
+### Running a Migration
+
+The `run` method runs the migration.
+
+By default, migrations run in the background. Passing an optional boolean argument configures the migration to run in the foreground.
+
+```js
+const foreground = true;
+const result = migration.run(foreground);
+if (result.errors) {
+  console.log(result.errors);
+} else {
+  console.log(result.name);
+}
+```
+
+<a name="dryRunMigration"></a>
+
+### Dry Run a Migration
+
+A migration can be dry run to preview what changes would be applied.
+
+```js
+const changes = migration.dryRun();
+console.log(changes);
+```
+
+<a name="updatingEntity"></a>
+
+## Updating an Entity
+
+To update properties, specify the properties to be updated. All ommitted properties remain unmodified.
+
+As a special case, `apiId` is a requirement because all entities are uniquely indentified by `apiId`.
+
+To update the `apiId`, specify `newApiId`.
+
+<a name="locale"></a>
+
+## Locale
+
+<a name="createLocale"></a>
+
+### Creating a Locale
+
+To create a locale
+
+```js
+migration.createLocate({
+  apiId,
+  displayName,
+  description,
+});
+```
+
+<a name="updateLocale"></a>
+
+### Updating a Locale
+
+To update a locale
+
+```js
+migration.updateLocate({
+  apiId,
+  ... // properties to update
+});
+```
+
+<a name="deleteLocale"></a>
+
+### Deleting a Locale
+
+To delete a locale
+
+```js
+migration.deleteLocatle(apiId);
+```
+
+## Stage
+
+<a name="createStage"></a>
+
+### Creating a Stage
+
+To create a stage
+
+```js
+migration.createStage({
+  apiId,
+  displayName,
+  description,
+  isDefault,
+  allowQueries,
+  color,
+});
+```
+
+<a name="updateStage"></a>
+
+### Updating a Stage
+
+To update a stage
+
+```js
+migration.updateStage({
+  apiId,
+  ... // properties to update
+});
+```
+
+<a name="deleteStage"></a>
+
+### Deleting a Stage
+
+To delete a Stage
+
+```js
+migration.deleteStage(apiId);
+```
+
+<a name="enumerations"></a>
+
+## Enumerations
+
+<a name="createEnumeration"></a>
+
+### Creating an Enumeration
+
+Create an enumeration with values.
+
+```js
+const colors = migration.createEnumeration({
+  apiId,
+  displayName,
+  description,
+});
+// add values
+colors.addValue("Red");
+colors.addValue("Green");
+// or add multiple values at a time.
+colors.addValue("Blue", "Yellow");
+```
+
+<a name="updateEnumeration"></a>
+
+### Updating an Enumeration
+
+Updating an enumeration and it's values.
+
+```js
+const colors = migration.updateEnumeration({
+  apiId,
+  ... // properties to update.
+});
+colors.addValue("Black"); // add a new value
+colors.updateValue("Red", "Dark Red"); // update existing value
+colors.deleteValue("Blue"); // delete value
+```
+
+<a name="deleteEnumeration"></a>
+
+### Deleting Enumeration
+
+To delete an enumeration and it's values
+
+```js
+migration.deleteEnumeration(apiId);
+```
+
+<a name="models"></a>
+
+## Models
+
+<a name="createModel"></a>
+
+### Creating a Model
+
+A model can be created by passing in the required parameters.
+
+```js
+const modelName = migration.createModel({
+  apiId, // must start with upper case letter
+  apiIdPlural, // must start with upper case letter
+  displayName,
+  description,
+});
+```
+
+<a name="updateModel"></a>
+
+### Updating a Model
+
+To update a model
+
+```js
+migration.updateModel({
+  apiId, // required
+  ... // properties to update
+});
+```
+
+<a name="deleteModel"></a>
+
+### Deleting a Model
+
+To delete a model
+
+```js
+migration.deleteModel(apiId);
+```
+
+<a name="fields"></a>
+
+### Fields
+
+<a name="createField"></a>
+
+#### Create Field
+
+To create a simple field.
+
+```js
+const { FieldType } = require("@graphcms/migration");
+model.addSimpleField({
+  apiId,
+  displayName,
+  type: FieldType.String,
+});
+```
+
+To create an enumerable field.
+
+```js
+model.addEnumerableField({
+  apiId,
+  displayName,
+  enumerationApiId, // previously created enumeration.
+});
+```
+
+To create a relational field.
+
+```js
+const { RelationType } = require("@graphcms/migration");
+model.addRelationalField({
+  apiId,
+  displayName,
+  relationType: RelationType.OneToOne,
+  model, // the related model
+
+  // optional but can be specified to customize the details.
+  reverseField: {
+    apiId,
+    displayName,
+  },
+});
+```
+
+To create a union field.
+
+```js
+const { RelationType } = require("@graphcms/migration");
+model.addUnionField({
+  apiId,
+  displayName,
+  relationType: RelationType.OneToOne,
+  models, // list of related models
+
+  // optional but can be specified to customize the details.
+  reverseField: {
+    apiId,
+    displayName,
+  },
+});
+```
+
+<a name="updateField"></a>
+
+#### Update Field
+
+To update a field, firstly retrieve the model.
+
+```js
+const model = migration.updateModel({...}) // to update the model
+const model = migration.model(apiId) // to only retrieve the model
+```
+
+Updating simple field
+
+```js
+model.updateSimpleField({
+  apiId,
+  ... // properties to update
+})
+```
+
+Updating enumerable field
+
+```js
+model.updateEnumerableField({
+  apiId,
+  ... // properties to update
+})
+```
+
+Updating relational field
+
+```js
+model.updateRelationalField({
+  apiId,
+  ... // properties to update
+})
+```
+
+Updating union field
+
+```js
+model.updateRelationalField({
+  apiId,
+  models, // list of related models
+  ... // properties to update
+})
+```
+
+<a name="deleteField"></a>
+
+#### Deleting a Field
+
+To delete a field
+
+```js
+model.deleteField(apiId);
+```
+
+## API Docs
+
 SDK docs is available at [https://grapchms.com/docs/sdk](https://grapchms.com/docs/sdk).
 
 The SDK is fully typed with Typescript and IDE intellisense is expected to work as desired.

No alert changes

Improved metrics

Total package byte prevSize

386509

2.11%

Lines of code

4429

0.39%

Number of lines in readme file

440

923.26%

No dependency changes