event-store-adapter-js 1.0.2-snapshot.0

package/.eslintrc.cjs

@@ -0,0 +1,25 @@
+module.exports = {
+  rules: {
+  },
+  reportUnusedDisableDirectives: true,
+  ignorePatterns: ["dist/*"],
+  env: { browser: true, es2020: true, node: true },
+  parserOptions: { ecmaVersion: "latest", sourceType: "module" },
+  settings: { react: { version: "detect" } },
+  plugins: [],
+  extends: [
+    "eslint:recommended",
+  ],
+  overrides: [
+    {
+      files: ["*.ts", "*.tsx"],
+      parser: "@typescript-eslint/parser",
+      plugins: ["@typescript-eslint"],
+      extends: ["plugin:@typescript-eslint/recommended"],
+      rules: {
+        // TypeScriptに関するカスタムルールをここに追加できます
+        "@typescript-eslint/no-unused-vars": ["error", { "argsIgnorePattern": "^_" }]
+      },
+    },
+  ],
+};

package/.github/CODEONWERS

@@ -0,0 +1 @@
+* @j5ik2o

package/.github/create-release-note-body.py

@@ -0,0 +1,40 @@
+#! /usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+import sys
+import csv
+import re
+
+commit_messages = {'BREAKING CHANGE': [], 'build': [], 'ci': [], 'feat': [], 'fix': [], 'docs': [], 'style': [], 'refactor': [], 'perf': [], 'test': [], 'revert': [], 'chore': []}
+
+titles = {'BREAKING CHANGE': 'Breaking Changes',
+          'build': 'Build Systems',
+          'ci': 'Continuous Integration',
+          'feat': 'Features',
+          'fix': 'Bug Fixes',
+          'docs': 'Documentation',
+          'style': 'Styles',
+          'refactor': 'Code Refactoring',
+          'perf': 'Performance Improvements',
+          'test': 'Tests',
+          'revert': 'Reverts',
+          'chore': 'Chores'}
+
+cin = csv.reader(sys.stdin, delimiter="\t") # 補足: 開く対象がファイルのときは newline='' をパラメータに追加
+
+def match_append(key, row):
+    r = re.match(f"^{key}(.*)?\: (.*)", row[2])
+    if r:
+        commit_messages[key].append((r.group(2), row))
+
+for row in cin:
+    for key in commit_messages.keys():
+        match_append(key, row)
+
+for k,v in titles.items():
+    if commit_messages[k]:
+        print(f"### {v}\n")
+    for messages in commit_messages[k]:
+        print(f"* {messages[0]} ({messages[1][0]})")
+    if commit_messages[k]:
+        print()

package/.github/create-release-note-header.py

@@ -0,0 +1,28 @@
+#! /usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+import sys
+from datetime import datetime, timezone
+
+args = sys.argv
+
+server_url = args[1]
+repo_name = args[2]
+previous_tag = args[3]
+next_tag = args[4]
+
+repo_url = f"{server_url}/{repo_name}"
+compare_url = f"{repo_url}/compare/{previous_tag}...{next_tag}"
+
+next_version = next_tag.replace("v", "")
+
+utc_now = datetime.now(timezone.utc)
+today = utc_now.strftime("%Y-%m-%d")
+
+header=f"""
+### [{next_version}]({compare_url}) ({today})
+
+"""
+
+print(header)
+

package/.github/next-semver.py

@@ -0,0 +1,20 @@
+#! /usr/bin/env python3
+# -*- coding: utf-8 -*-
+import sys
+import semver
+import re
+
+args = sys.argv
+
+for s in sys.stdin:
+    r = re.match('.*v?(\d+\.\d+\.\d+)', s)
+    if r:
+        cur_ver = semver.VersionInfo.parse(r.group(1))
+        next_ver = ""
+        if args[1] == "major":
+            next_ver = str(cur_ver.bump_major())
+        elif args[1] == "minor":
+            next_ver = str(cur_ver.bump_minor())
+        else:
+            next_ver = str(cur_ver.bump_patch())
+        print(next_ver)

package/.github/semver-level.py

@@ -0,0 +1,31 @@
+#! /usr/bin/env python3
+# -*- coding: utf-8 -*-
+import sys
+import csv
+import re
+
+commit_messages = {'BREAKING CHANGE': 0, 'build': 0, 'ci': 0, 'feat': 0, 'fix': 0, 'docs': 0, 'style': 0, 'refactor': 0, 'perf': 0, 'test': 0, 'revert': 0, 'chore': 0}
+
+rules = {'major': ['perf', 'BREAKING CHANGE'], 'minor': ['feat', 'revert'], 'patch': ['build', 'ci', 'fix', 'docs', 'style', 'refactor', 'chore', 'test']}
+
+cin = csv.reader(sys.stdin, delimiter="\t")
+
+def match_append(key, row):
+    r = re.match(f"^{key}(.*)?\: (.*)", row[2])
+    if r:
+        commit_messages[key]+=1
+
+for row in cin:
+    for key in commit_messages.keys():
+        match_append(key, row)
+
+if sum(commit_messages.values()) > 0:
+    for k,v in rules.items():
+        sum = 0
+        for t in v:
+            sum += commit_messages[t]
+        if sum > 0:
+            print(k)
+            break
+else:
+    sys.exit(-1)

package/.github/workflows/bump-version.yml

@@ -0,0 +1,99 @@
+name: Bump-Version
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: "0 0 * * *"
+jobs:
+  bump-version:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          persist-credentials: true
+          token: ${{ secrets.PERSONAL_ACCESS_TOKEN }}
+      - uses: actions/setup-node@v3
+        with:
+          node-version: 20.x
+          cache: 'npm'
+      - uses: actions/setup-python@v4
+        with:
+          python-version: "3.10"
+      - run: pip install semver
+      - id: defines
+        run: |
+          LATEST_TAG=$(git describe --abbrev=0 --tags)
+          echo "LATEST_TAG=$LATEST_TAG"
+          echo "prev_tag=$LATEST_TAG" >> $GITHUB_OUTPUT
+      - name: Calculate changes from the latest tag to HEAD
+        id: changes
+        run: |
+          COUNT=$(git log ${{ steps.defines.outputs.prev_tag }}..HEAD --pretty=format:"%s" \
+            --no-merges -P --grep='^(BREAKING CHANGE|build|ci|feat|fix|docs|style|refactor|perf|test|revert|chore)(\(.*\))?:' | awk 'END{print NR}')
+          echo "COUNT=$COUNT"
+          echo "count=$COUNT" >> $GITHUB_OUTPUT
+      - name: Calculate semver level
+        id: semver_level
+        run: |
+          SEMVER_LEVEL=$(git log ${{ steps.defines.outputs.prev_tag }}..HEAD --pretty=format:"%h%x09%H%x09%s" \
+            --no-merges -P --grep='^(BREAKING CHANGE|build|ci|feat|fix|docs|style|refactor|perf|test|revert|chore)(\(.*\))?:' \
+            | python3 "${GITHUB_WORKSPACE}"/.github/semver-level.py)
+          echo "SEMVER_LEVEL=$SEMVER_LEVEL"
+          echo "semver_level=$SEMVER_LEVEL" >> $GITHUB_OUTPUT
+        if: steps.changes.outputs.count > 0
+      - name: Get the next version
+        id: versions
+        run: |
+          NEXT_VERSION=$(echo ${{ steps.defines.outputs.prev_tag }} | python3 "${GITHUB_WORKSPACE}"/.github/next-semver.py ${{ steps.semver_level.outputs.semver_level }})
+          echo "NEXT_VERSION=$NEXT_VERSION"
+          echo "next_version=$NEXT_VERSION" >> $GITHUB_OUTPUT
+          echo "next_tag=v$NEXT_VERSION" >> $GITHUB_OUTPUT
+        if: steps.changes.outputs.count > 0
+      - name: set the next version
+        run: |
+      - name: git commit & push
+        id: git_commit_push
+        run: |
+          git config --global user.email "j5ik2o@gmail.com"
+          git config --global user.name "Junichi Kato"
+          npm version ${{ steps.versions.outputs.next_version }} --no-git-tag-version
+          git add .
+          git commit -m "version up to ${{ steps.versions.outputs.next_tag }}"
+          git push origin main
+          COMMIT_SHA=$(git rev-parse HEAD)
+          echo "commit_sha=$COMMIT_SHA" >> $GITHUB_OUTPUT
+        if: steps.changes.outputs.count > 0
+      - name: tagging and push tag
+        id: tag_version
+        run: |
+          git tag -a "${{ steps.versions.outputs.next_tag }}" ${{ steps.git_commit_push.outputs.commit_sha }} -m "${{ steps.versions.outputs.next_tag }}"
+          git push origin ${{ steps.versions.outputs.next_tag }}
+          python3 "${GITHUB_WORKSPACE}"/.github/create-release-note-header.py \
+            ${{ github.server_url }} \
+            ${{ github.repository }} \
+            ${{ steps.defines.outputs.prev_tag }} \
+            ${{ steps.versions.outputs.next_tag }} \
+            > changelog.txt
+          git log ${{ steps.defines.outputs.prev_tag }}..${{ steps.versions.outputs.next_tag }} --pretty=format:"%h%x09%H%x09%s" \
+            -P --grep='^(BREAKING CHANGE|build|ci|feat|fix|docs|style|refactor|perf|test|revert|chore)(.*)?:.*$' \
+            --no-merges --full-history | \
+            python3 "${GITHUB_WORKSPACE}"/.github/create-release-note-body.py >> changelog.txt
+        if: steps.changes.outputs.count > 0
+      - name: Create a GitHub release
+        uses: actions/create-release@v1
+        env:
+          GITHUB_TOKEN: ${{ secrets.PERSONAL_ACCESS_TOKEN }}
+        with:
+          tag_name: ${{ steps.versions.outputs.next_tag }}
+          release_name: Release ${{ steps.versions.outputs.next_tag }}
+          body_path: changelog.txt
+        if: steps.changes.outputs.count > 0
+      - name: Switch to Snapshot version
+        run: |
+          rm changelog.txt
+          npm version prerelease --preid=snapshot --no-git-tag-version
+          SNAPSHOT_VERSION=$(npm version --json | jq -r '.["event-store-adapter-js"]')
+          git add .
+          git commit -m "version up to ${SNAPSHOT_VERSION}"
+          git push origin main
+        if: steps.changes.outputs.count > 0

package/.github/workflows/ci.yml

@@ -0,0 +1,37 @@
+name: CI
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+    branches: [ "main" ]
+  schedule:
+    - cron: '0 * * * *'
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    name: "Run lint"
+    steps:
+    - uses: actions/checkout@v4
+    - uses: actions/setup-node@v3
+      with:
+        node-version: 20.x
+        cache: 'npm'
+    - run: npm install
+    - run: npm run lint
+  test:
+    runs-on: ubuntu-latest
+    needs: lint
+    env:
+      TEST_TIME_FACTOR: 10.0
+    strategy:
+      matrix:
+        node-version: [20.x]
+    steps:
+    - uses: actions/checkout@v4
+    - name: Use Node.js ${{ matrix.node-version }}
+      uses: actions/setup-node@v3
+      with:
+        node-version: ${{ matrix.node-version }}
+        cache: 'npm'
+    - run: npm install
+    - run: npm run test

package/.github/workflows/snapshot.yml

@@ -0,0 +1,26 @@
+name: Snapshot
+on:
+  workflow_run:
+    workflows:
+      - CI
+    types:
+      - completed
+jobs:
+  snapshot:
+    runs-on: ubuntu-latest
+    if: ${{ github.event.workflow_run.conclusion == 'success' }}
+    name: "Publish Snapshot"
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.workflow_run.head_branch }}
+          fetch-depth: 0
+      - uses: actions/setup-node@v3
+        with:
+          node-version: 20.x
+          registry-url: 'https://registry.npmjs.org'
+          cache: 'npm'
+      - run: npm install
+      - run: npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/.prettierignore

@@ -0,0 +1,2 @@
+dist/
+node_modules/

package/.prettierrc.yml

@@ -0,0 +1,3 @@
+tabWidth: 2
+semi: true
+singleQuote: false

package/.vscode/settings.json

@@ -0,0 +1,11 @@
+{
+  "[ts]": {
+    "editor.codeActionsOnSave": {
+      "source.organizeImports": true,
+      "source.fixAll.eslint": true
+    },
+    "editor.formatOnSave": true,
+    "typescript.tsdk": "node_modules/typescript/lib",
+    "eslint.validate": ["javascript", "json"]
+  }
+}

package/README.md

@@ -0,0 +1,18 @@
+# event-store-adapter-js
+
+This library is designed to turn DynamoDB into an Event Store for Event Sourcing.
+
+Status: WIP
+
+## License.
+
+MIT License. See [LICENSE](LICENSE) for details.
+
+## Other language implementations
+
+- [for Java](https://github.com/j5ik2o/event-store-adapter-java)
+- [for Scala](https://github.com/j5ik2o/event-store-adapter-scala)
+- [for Kotlin](https://github.com/j5ik2o/event-store-adapter-kotlin)
+- [for Rust](https://github.com/j5ik2o/event-store-adapter-rs)
+- [for Go](https://github.com/j5ik2o/event-store-adapter-go)
+- [for JavaScript/TypeScript](https://github.com/j5ik2o/event-store-adapter-js)

package/docs/DATABASE_SCHEMA.ja.md

@@ -0,0 +1,49 @@
+## EventStoreが利用するDynamoDBのテーブル構成
+
+- Journal
+- Snapshot
+
+いずれのテーブルも、キー設計の前提としては、論理シャード内で最大限に書き込みが分散させることを想定しています。
+
+### Journalテーブル
+
+集約で起きたイベントを保存するためのテーブル。原則的に、このイベントを使って集約状態を再生(リプレイ)します。
+
+| キー名         | 説明                                    | 具体的な値                                                                                                                                                                                                                                                                                                                                                                                                                                                              | 備考 |
+|:------------|:--------------------------------------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:---|
+| pkey        | パーションキー(集約種別名-hash(集約ID) % 論理シャードサイズ) | user-account-1                                                                                                                                                                                                                                                                                                                                                                                                                                                       |    |
+| skey        | ソートキー(集約種別名-集約IDの値部分-シーケンス番号)         | user-account-01H42K4ABWQ5V2XQEP3A48VE0Z-12345                                                                                                                                                                                                                                                                                                                                                                                                                        |    |
+| aid         | 集約ID                                  | user-account-01H42K4ABWQ5V2XQEP3A48VE0Z                                                                                                                                                                                                                                                                                                                                                                                                                              |    |
+| ser_nr      | シーケンス番号(開始番号は1)                       | 12345                                                                                                                                                                                                                                                                                                                                                                                                                                                              |    |
+| payload     | イベント内容                                | {"type":"Created","id":"01H42KBHCW1BZG504J4ZXKA2F2","aggregate_id":{"value":"01890535-c59c-72d5-08a8-dcea316374c8"},"seq_nr":1,"name":"test","members":{"members_ids_by_user_account_id":{"01H42KBHCWBDTZYQ7P78T8BTWX":"01H42KBHCWA8NE32M49YH544H1"},"members":{"01H42KBHCWA8NE32M49YH544H1":{"id":"01H42KBHCWA8NE32M49YH544H1","user_account_id":{"value":"01890535-c59c-5b75-ff5c-f63a3485eb9d"},"role":"Admin"}}},"occurred_at":"2023-06-29T03:32:37.404481Z"} |    |
+| occurred_at | 発生日時                                  | 2023-06-29T03:32:37.404481Z                                                                                                                                                                                                                                                                                                                                                                                                                                        |    |
+
+aidとseq_nrはGSIが適用されており、リプレイ時はこのインデックスを利用されます。
+
+### Snapshotテーブル
+
+集約の状態を保存するためのテーブルであり、集約のリプレイを高速化するためのテーブルです。スナップショット保存後にもイベントは保存されるため、最新の集約状態を表さない場合あります。
+
+| キー名     | 説明                                                               | 具体的な値                                                                                                                                                                                                                                                                                                                                                                                      | 備考 |
+|:--------|:-----------------------------------------------------------------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:---|
+| pkey    | パーションキー(集約種別名-hash(集約ID) % 論理シャードサイズ)                            | user-account-1                                                                                                                                                                                                                                                                                                                                                                               |    |
+| skey    | ソートキー(集約種別名-集約IDの値部分-シーケンス番号), 最新のスナップショットはシーケンス番号=0として読み書きされます。 | user-account-01H42K4ABWQ5V2XQEP3A48VE0Z-12345                                                                                                                                                                                                                                                                                                                                                |    |
+| payload | 集約の状態                                                            | {"id":{"value":"0189053a-d0b4-8f9b-4fb6-db91f72ccf16"},"name":"test","members":{"members_ids_by_user_account_id":{"01H42KNM5MBVRBZTADAZ9ETSPZ":"01H42KNM5M2QEW700VCW4J2KYE"},"members":{"01H42KNM5M2QEW700VCW4J2KYE":{"id":"01H42KNM5M2QEW700VCW4J2KYE","user_account_id":{"value":"0189053a-d0b4-5ef0-bfe9-4d57d2ed66df"},"role":"Admin"}}},"messages":[],"seq_nr_counter":1,"version":1} |    |
+| aid     | 集約ID                                                             | user-account-01H42K4ABWQ5V2XQEP3A48VE0Z                                                                                                                                                                                                                                                                                                                                                      |    |
+| ser_nr  | シーケンス番号(開始番号は1)                                                  | 12345                                                                                                                                                                                                                                                                                                                                                                                      |    |
+| ttl     | 削除のためのTTL(秒)                                                     | 1624980000                                                                                                                                                                                                                                                                                                                                                                                 |    |
+| version | バージョン(楽観的ロック用)(開始番号は1)                                           | 1                                                                                                                                                                                                                                                                                                                                                                                          |    |
+
+- スナップショット冗長化機能が無効な場合はskey=0にスナップショットが保存されるだけですが、有効にした場合はスナップショットはskey=0以外にskey=aggregate.seq_nr()の2件保存されます。スナップショットを保存するたびにskey=aggregate.seq_nr()のスナップショットが増えますが、あなたはスナップショットは上限を指定できます(デフォルトは1)。上限を超えた場合は古いスナップショットから削除されます。デフォルトでは、クライアント主導で削除されます。TTLを使ってDynamoDB自身に削除させることもできます。
+- aidとseq_nrはGSIが適用されており、リプレイ時はこのインデックスを利用されます。
+
+### イベント及びスナップショットの書き込み
+
+1. 集約にてコマンドが受理されると、最新のseq_nrが付与されたイベントが生成されます。
+2. 生成されたイベントはjournalテーブルに書き込まれます。ただし、この書き込みは必ずsnapshotテーブルと同じトランザクションで行われ、versionが一致する条件下で実施されます。初回のイベント以外は、snapshotのpayloadを更新することはオプションです。
+
+### イベント及びスナップショットを使って集約をリプレイする
+
+1. 集約のIDを指定して、スナップショットを取得します。
+2. 取得した集約のIDとスナップショットのシーケンス番号以降のイベントをjournalテーブルから読み込みます。
+3. 読み込んだイベントをスナップショットに適用することで、最新の集約状態を取得します。

package/docs/DATABASE_SCHEMA.md

@@ -0,0 +1,49 @@
+## DynamoDB table schema used by EventStore
+
+- Journal
+- Snapshot
+
+The key design assumption for both tables is that writes are distributed to the greatest extent possible within the logical shard.
+
+### Journal table
+
+The table used to store events that have occurred in an aggregate. In principle, this event is used to replay (replay) the aggregate state.
+
+| key name    | description                                                          | example                                                                                                                                                                                                                                                                                                                                                                                                                                                            | remarks |
+|:------------|:---------------------------------------------------------------------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:--------|
+| pkey        | Partition key(${aggregate-type-name}-hash($aid) % logical-shard-size) | user-account-1                                                                                                                                                                                                                                                                                                                                                                                                                                                       |         |
+| skey        | Sort Key(${aggregate type name}-${aid.value}-${seq_nr})              | user-account-01H42K4ABWQ5V2XQEP3A48VE0Z-12345                                                                                                                                                                                                                                                                                                                                                                                                                        |         |
+| aid         | Aggregate ID                                                         | user-account-01H42K4ABWQ5V2XQEP3A48VE0Z                                                                                                                                                                                                                                                                                                                                                                                                                              |         |
+| ser_nr      | Sequence Number(origin=1)                                                      | 12345                                                                                                                                                                                                                                                                                                                                                                                                                                                              |         |
+| payload     | Event Payload                                                        | {"type":"Created","id":"01H42KBHCW1BZG504J4ZXKA2F2","aggregate_id":{"value":"01890535-c59c-72d5-08a8-dcea316374c8"},"seq_nr":1,"name":"test","members":{"members_ids_by_user_account_id":{"01H42KBHCWBDTZYQ7P78T8BTWX":"01H42KBHCWA8NE32M49YH544H1"},"members":{"01H42KBHCWA8NE32M49YH544H1":{"id":"01H42KBHCWA8NE32M49YH544H1","user_account_id":{"value":"01890535-c59c-5b75-ff5c-f63a3485eb9d"},"role":"Admin"}}},"occurred_at":"2023-06-29T03:32:37.404481Z"} |         |
+| occurred_at | Occurred DateTime of the Event                                       | 2023-06-29T03:32:37.404481Z                                                                                                                                                                                                                                                                                                                                                                                                                                        |         |
+
+GSI is applied to aid and seq_nr, and this index is used during replay.
+
+### Snapshot table
+
+This table is used to store aggregate state and to speed up replay of aggregates. It may not represent the latest aggregation state because events are saved even after the snapshot is saved.
+
+| column name | description                                                                                               | example                                                                                                                                                                                                                                                                                                                                                                                    | remarks |
+|:------------|:----------------------------------------------------------------------------------------------------------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:--------|
+| pkey        | Partition key(${aggregate-type-name}hash($aid) % logical-shard-size)                                      | user-account-1                                                                                                                                                                                                                                                                                                                                                                               |         |
+| skey        | Sort Key(${aggregate type name}-${aid.value}-${seq_nr}), The latest snapshot is read/written as seq_nr=0. | user-account-01H42K4ABWQ5V2XQEP3A48VE0Z-12345                                                                                                                                                                                                                                                                                                                                                |         |
+| payload     | State of Aggregate                                                                                        | {"id":{"value":"0189053a-d0b4-8f9b-4fb6-db91f72ccf16"},"name":"test","members":{"members_ids_by_user_account_id":{"01H42KNM5MBVRBZTADAZ9ETSPZ":"01H42KNM5M2QEW700VCW4J2KYE"},"members":{"01H42KNM5M2QEW700VCW4J2KYE":{"id":"01H42KNM5M2QEW700VCW4J2KYE","user_account_id":{"value":"0189053a-d0b4-5ef0-bfe9-4d57d2ed66df"},"role":"Admin"}}},"messages":[],"seq_nr_counter":1,"version":1} |         |
+| aid         | Aggregate ID                                                                                              | user-account-01H42K4ABWQ5V2XQEP3A48VE0Z                                                                                                                                                                                                                                                                                                                                                      |         |
+| ser_nr      | Sequence Number(origin=1)                                                                                 | 12345                                                                                                                                                                                                                                                                                                                                                                                      |         |
+| ttl         | TTL for deletion(seconds)                                                                                 | 1624980000                                                                                                                                                                                                                                                                                                                                                                                 |         |
+| version     | Version for optimistic lock(origin=1)                                                                     | 1                                                                                                                                                                                                                                                                                                                                                                                          |         |
+
+- When the snapshot redundancy feature is disabled, only a snapshot is stored at skey=0. When enabled, two snapshots are stored at skey=aggregate.seq_nr() in addition to skey=0. Each time a snapshot is saved, skey=aggregate.seq_nr() snapshot will be increased, but you can specify an upper limit for the snapshot (default is 1). If the upper limit is exceeded, the older snapshots will be deleted first. By default, the deletion is client-initiated; you can also use TTL to let DynamoDB itself do the deletion.
+- GSI is applied to aid and seq_nr, and this index is used during replay.
+
+### Writing events and snapshots
+
+1. When the command is accepted by aggregate, an event with the latest seq_nr is generated. 
+2. The generated events are written to the journal table. However, this write is always done in the same transaction as the snapshot table and under version matching conditions. Except for the first event, updating the payload of snapshot is optional.
+
+### Replaying an aggregate with events and snapshots
+
+1. Specify the ID of the aggregate and take a snapshot.
+2. Read the events from the journal table after the ID of the retrieved aggregate and the sequence number of the snapshot.
+3. Apply the read events to the snapshot to obtain the latest aggregate state.

package/jest.config.ts

@@ -0,0 +1,5 @@
+/** @type {import("ts-jest/dist/types").InitialOptionsTsJest} */
+module.exports = {
+  preset: "ts-jest",
+  testEnvironment: "node",
+};

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "event-store-adapter-js",
+  "version": "1.0.2-snapshot.0",
+  "description": "This library is designed to turn DynamoDB into an Event Store for Event Sourcing.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "test": "jest --no-cache",
+    "fix": "npm run fix:prettier && npm run fix:eslint",
+    "fix:eslint": "eslint --fix .",
+    "fix:prettier": "prettier --write \"**/*.{js,ts,jsx,tsx,json}\"",
+    "lint": "npm run lint:prettier && npm run lint:eslint",
+    "lint:eslint": "eslint .",
+    "lint:prettier": "prettier --check \"**/*.{js,ts,jsx,tsx,json}\"",
+    "clean": "rimraf ./dist"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/j5ik2o/event-store-adapter-js.git"
+  },
+  "keywords": [
+    "ddd",
+    "cqrs",
+    "evnet-sourcing",
+    "dynamodb"
+  ],
+  "author": "Junichi Kato <j5ik2o@gmail.com>",
+  "license": "MIT",
+  "devDependencies": {
+    "@types/jest": "^29.5.5",
+    "@types/node": "^20.6.0",
+    "@types/winston": "^2.4.4",
+    "@typescript-eslint/eslint-plugin": "^6.3.0",
+    "@typescript-eslint/parser": "^6.3.0",
+    "eslint": "^8.47.0",
+    "jest": "^29.7.0",
+    "prettier": "3.0.3",
+    "rimraf": "^5.0.1",
+    "testcontainers": "^10.2.1",
+    "ts-jest": "^29.1.1",
+    "ts-node": "^10.9.1",
+    "typescript": "^5.2.2"
+  },
+  "dependencies": {
+    "@aws-sdk/client-dynamodb": "^3.413.0",
+    "aws-sdk": "^2.1459.0",
+    "moment": "^2.29.4",
+    "ulid": "^2.3.0",
+    "winston": "^3.10.0"
+  }
+}

package/renovate.json

@@ -0,0 +1,4 @@
+{
+  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
+  "extends": ["config:base"]
+}

package/src/event-store-options.ts

@@ -0,0 +1,28 @@
+import {
+  Aggregate,
+  AggregateId,
+  Event,
+  EventSerializer,
+  KeyResolver,
+  SnapshotSerializer,
+} from "./types";
+import * as moment from "moment";
+
+interface EventStoreOptions<
+  This extends EventStoreOptions<This, AID, A, E>,
+  AID extends AggregateId,
+  A extends Aggregate<A, AID>,
+  E extends Event<AID>,
+> {
+  withKeepSnapshotCount(keepSnapshotCount: number): This;
+
+  withDeleteTtl(deleteTtl: moment.Duration): This;
+
+  withKeyResolver(keyResolver: KeyResolver<AID>): This;
+
+  withEventSerializer(eventSerializer: EventSerializer<AID, E>): This;
+
+  withSnapshotSerializer(snapshotSerializer: SnapshotSerializer<AID, A>): This;
+}
+
+export { EventStoreOptions };

package/src/event-store.ts

@@ -0,0 +1,22 @@
+import { Aggregate, AggregateId, Event } from "./types";
+import { EventStoreOptions } from "./event-store-options";
+
+interface EventStore<
+  AID extends AggregateId,
+  A extends Aggregate<A, AID>,
+  E extends Event<AID>,
+> extends EventStoreOptions<EventStore<AID, A, E>, AID, A, E> {
+  persistEvent(event: E, version: number): Promise<void>;
+  persistEventAndSnapshot(event: E, aggregate: A): Promise<void>;
+  getEventsByIdSinceSequenceNumber(
+    id: AID,
+    sequenceNumber: number,
+    converter: (json: string) => E,
+  ): Promise<E[]>;
+  getLatestSnapshotById(
+    id: AID,
+    converter: (json: string) => A,
+  ): Promise<A | undefined>;
+}
+
+export { EventStore };

package/src/index.ts

@@ -0,0 +1,2 @@
+export * from "./types";
+export * from "./event-store";

package/src/internal/default-key-resolver.ts

@@ -0,0 +1,34 @@
+import { AggregateId, KeyResolver } from "../types";
+import { LoggerFactory } from "./logger-factory";
+
+class DefaultKeyResolver<AID extends AggregateId> implements KeyResolver<AID> {
+  private logger = LoggerFactory.createLogger();
+  private hashString(str: string): number {
+    if (str === undefined || str === null) {
+      throw new Error(`str is undefined or null: ${str}`);
+    }
+    // this.logger.debug("hashString = ", str);
+    let hash = 0;
+    for (let i = 0; i < str.length; i++) {
+      const char = str.charCodeAt(i);
+      hash = (hash << 5) - hash + char;
+      hash = hash & hash; // Convert to 32bit integer
+    }
+    return hash >>> 0; // Convert to unsigned 32bit integer
+  }
+
+  resolvePartitionKey(aggregateId: AID, shardCount: number): string {
+    if (aggregateId === undefined || aggregateId === null) {
+      throw new Error(`aggregateId is undefined or null: ${aggregateId}`);
+    }
+    const hash = this.hashString(aggregateId.asString);
+    const remainder = hash % shardCount;
+    return `${aggregateId.typeName}-${remainder}`;
+  }
+
+  resolveSortKey(aggregateId: AID, sequenceNumber: number): string {
+    return `${aggregateId.typeName}-${aggregateId.value}-${sequenceNumber}`;
+  }
+}
+
+export { DefaultKeyResolver };