with-iota

Getting started

1. Run npm install @1mill/with-iota

2. Configure your AWS Lambda handler

   import { CREATE, DELETE, INCREMENT, SET, withIota } from '@1mill/with-iota'
   
   const func = async ({ cloudevent, ctx, data, mutation, rapids }) => {
     const { companyId, name } = data
   
     if (!companyId) { throw new Error('companyId is required') }
     if (!name) { throw new Error('name is required') }
   
     // * Create some record
     const { id } = mutation.stage({
       action: CREATE,
       props: { companyId, name, comment: 'Hello world!' },
       type: 'myRecords',
     })
   
     // * Enqueue cloudevent that will be emitted after all staged mutations
     // * are comitted.
     rapids.stage({
       data: { id },
       type: 'fct.my-record-created.v0',
     })
   
     // * Increment some value on a different record
     mutation.stage({
       action: INCREMENT,
       id: companyId,
       props: { recordsCount: 1 },
       type: 'companies',
     })
   
     // * Set a value on the record we just created
     mutation.stage({
       action: SET,
       id,
       props: { comment: 'Update this comment!' },
       type: 'myRecords'
     })
   
     // * Selete the record we just created
     mutation.stage({
       action: DELETE,
       id,
       type: 'myRecords',
     })
   
     // * Enqueue another cloudevent that will be emitted after all
     // * staged mutations are committed.
     rapids.stage({
       data: { id },
       type: 'fct.my-record-deleted.v0',
     })
   
     // * Return some value for calls with InvocationType set to RequestResponse.
     return cloudevent.id
   }
   
   export const handler = async (event, ctx) => await withIota(event, ctx, { func })

Usage

Setup

If you ever change any of the values below once they are set, be sure to migrate any saved journal entries to the new settings. If you do not do this, then already processed cloudevents may run again.

| Environment | Required | Types | Default | Description | |-----------------------------------|----------|--------|----------------------|--------------------------------------------------------| | MILL_IOTA_AWS_ACCESS_KEY_ID | yes | string | | AWS Access Key with permissions to AWS EventBridge. | | MILL_IOTA_AWS_ENDPOINT | | string | Set by AWS | | | MILL_IOTA_AWS_REGION | yes | string | | Valid AWS Region. | | MILL_IOTA_AWS_SECRET_ACCESS_KEY | yes | string | | AWS Secret Key with permissions to AWS EventBridge. | | MILL_IOTA_AWS_SESSION_TOKEN | | string | Set by AWS | AWS Session Token with permissions to AWS EventBridge. | | MILL_IOTA_EVENTBUS_NAME | | string | default | Name of the AWS EventBridge. | | MILL_IOTA_JOURNAL_NAME | | string | iotaJournalEntries | Name of the MongoDB collection. | | MILL_IOTA_MONGO_DB | yes | string | | Name of the MongoDB Database. | | MILL_IOTA_MONGO_URI | yes | string | | URI of the MongoDB Cluster. | | MILL_IOTA_SERVICE_ID | yes | string | | Unique name of the service / application itself. |

During the AWS Lambda runtime, AWS automatically provides all the MILL_IOTA_AWS_ credentials.

Func

| Property | Type |Description | |----------------|-----------|------------| | cloudevent | object | The cloudevent payload from event. | | countDocuments(name, args) | function | Alias for db.collection(name).countDocuments(args) using mongo. | | ctx | object | AWS Lambda context. | | data | any | The cloudevent.data. If cloudevent.datacontenttype is application/json, then the JSON parsed data will be returned. | | distinct(name, args) | function | Alias for db.collection(name).distinct(args) using mongo. | | event | object | The event that invoked the AWS Lambda function. | | find(name, args) | function | Alias for db.collection(name).find(args) using mongo. | | findOne(name, args) | function | Alias for db.collection(name).findOne(args) using mongo. | | mutation.stage(args) | function | Stage a mutation to be committed after return. | | rapids.stage(args) | function | Stage a cloudevent to be sent to rapids after mutations are applied. |

Lifecycle

Despite the straggered nature of staged mutations and staged rapids cloudevents, all mutations are applied first in order. Then, all rapids cloudevents are emitted in order.

| Lifecycle | Commit order | | --- | --- | | | |

Development

1. Run npm install
2. Create .env file with with MILL_IOTA_AWS_ACCESS_KEY_ID, MILL_IOTA_AWS_REGION, and MILL_IOTA_AWS_SECRET_ACCESS_KEY.
3. Run docker compose up -d mongo mongo-admin
4. Run docker compose up test

Deploy

1. Run npm version (major|minor|patch)
2. Run git push
3. Run npm run deploy