Skip to content

hesselbom/y-dynamodb

Folders and files

NameName
Last commit message
Last commit date
Feb 26, 2021
Feb 26, 2021
Dec 16, 2020
Dec 18, 2020
Dec 16, 2020
Feb 26, 2021
Dec 16, 2020
Dec 16, 2020
Dec 16, 2020

Repository files navigation

DynamoDB database adapter for Yjs

Rewritten from y-leveldb to use AWS DynamoDB.

WIP.

docker-compose -f docker-compose-dynamodb-local.yml up

node ./testrun

aws dynamodb list-tables --endpoint-url http://localhost:8000 --region us-west-2
aws dynamodb scan --table-name test-y-dynamodb --endpoint-url http://localhost:8000 --region us-west-2

Use it

npm install y-dynamodb --save
const DynamoDbPersistence = require('./src/y-dynamodb')
const Y = require('yjs')

const config = {
  aws: {
    region: 'us-west-2',
    accessKeyId: 'accessKeyId',
    secretAccessKey: 'secretAccessKey',
    endpoint: 'http://localhost:8000'
  },
  skipCreateTable: true, // skips creating table, assumes it already exists
  tableName: 'test-y-dynamodb'
}
const persistence = DynamoDbPersistence(config)

const ydoc = new Y.Doc()
ydoc.getArray('arr').insert(0, [1, 2, 3])
console.log(ydoc.getArray('arr').toArray()) // => [1, 2, 3]

// store document updates retrieved from other clients
persistence.storeUpdate('my-doc', Y.encodeStateAsUpdate(ydoc))

// when you want to sync, or store data to a database,
// retrieve the temporary Y.Doc to consume data
persistence.getYDoc('my-doc')
  .then(doc => console.log('Got my-doc', doc.getArray('arr').toArray())) // [1, 2, 3]

API

persistence = DynamoDbPersistence(config)

Create a y-dynamodb persistence instance.

persistence.getYDoc(docName: string): Promise<Y.Doc>

Create a Y.Doc instance with the data persisted in DynamoDB. Use this to temporarily create a Yjs document to sync changes or extract data.

persistence.storeUpdate(docName: string, update: Uint8Array): Promise

Store a single document update to the database.

persistence.getStateVector(docName: string): Promise<Uint8Array>

The state vector (describing the state of the persisted document - see Yjs docs) is maintained in a separate field and constantly updated.

This allows you to sync changes without actually creating a Yjs document.

persistence.getDiff(docName: string, stateVector: Uint8Array): Promise<Uint8Array>

Get the differences directly from the database. The same as Y.encodeStateAsUpdate(ydoc, stateVector).

persistence.clearDocument(docName: string): Promise

Delete a document, and all associated data from the database.

persistence.setMeta(docName: string, metaKey: string, value: any): Promise

Persist some meta information in the database and associate it with a document. It is up to you what you store here. You could, for example, store credentials here.

persistence.getMeta(docName: string, metaKey: string): Promise<any|undefined>

Retrieve a store meta value from the database. Returns undefined if the metaKey doesn't exist.

persistence.getMetas(docName: string): Promise<Map<string, any>>

Retries all meta keys and values from the database for a document.

persistence.delMeta(docName: string, metaKey: string): Promise

Delete a store meta value.

persistence.flushDocument(docName: string): Promise (dev only)

Internally y-dynamodb stores incremental updates. You can merge all document updates to a single entry. You probably never have to use this.

AWS CDK

Here's an example stack if you're using AWS CDK:

class AwsCdkStack extends cdk.Stack {
  constructor (scope, id, props) {
    super(scope, id, props)

    const docsTable = new dynamodb.Table(this, 'test-y-dynamodb', {
      partitionKey: { name: 'ydocname', type: dynamodb.AttributeType.STRING },
      sortKey: { name: 'ykeysort', type: dynamodb.AttributeType.BINARY },
      tableName: 'test-y-dynamodb'
    })

    const user = new iam.User(this, 'YDatabaseUser', { userName: 'YDatabaseUser' })
    const accessKey = new iam.CfnAccessKey(this, 'myAccessKey', { userName: user.userName })

    new cdk.CfnOutput(this, 'accessKeyId', { value: accessKey.ref })
    new cdk.CfnOutput(this, 'secretAccessKey', { value: accessKey.attrSecretAccessKey })

    docsTable.grantFullAccess(user)
  }
}

License

y-dynamodb is licensed under the MIT License.

viktor@hesselbom.net

About

No description, website, or topics provided.

Resources

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published