betterauth-dynamodb-adapter 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 rokku-x
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,233 @@
+# betterauth-dynamodb-adapter
+
+[![npm version](https://img.shields.io/npm/v/betterauth-dynamodb-adapter.svg)](https://www.npmjs.com/package/betterauth-dynamodb-adapter)
+[![license](https://img.shields.io/npm/l/betterauth-dynamodb-adapter.svg)](LICENSE)
+![TS](https://img.shields.io/badge/TypeScript-%E2%9C%93-blue)
+
+A DynamoDB adapter for [Better Auth](https://www.better-auth.com/). Uses a single-table design with composite keys and a GSI for model-based queries.
+
+## Features
+
+- Single-table design — all Better Auth models stored in one DynamoDB table
+- Composite primary keys (`_pk` / `_sk`) for direct item access
+- GSI-based queries via a `_table` attribute for model-level scans
+- Full filter expression support (`eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `not_in`, `contains`, `starts_with`, `ends_with`)
+- Fast path `GetItem` for single-ID lookups
+- In-memory sorting and pagination for `findMany`
+- Dual CJS/ESM build with full TypeScript declarations
+
+## Installation
+
+```bash
+npm install betterauth-dynamodb-adapter
+# or
+bun add betterauth-dynamodb-adapter
+```
+
+### Peer dependencies
+
+You also need these installed in your project:
+
+```bash
+npm install better-auth @aws-sdk/client-dynamodb @aws-sdk/lib-dynamodb
+```
+
+## DynamoDB Table Setup
+
+Create a DynamoDB table with the following schema:
+
+| Attribute | Type   | Role          |
+|-----------|--------|---------------|
+| `_pk`     | String | Partition key |
+| `_sk`     | String | Sort key      |
+
+Then create a Global Secondary Index:
+
+| Index Name     | Partition Key | Type   |
+|----------------|---------------|--------|
+| `_table-index` | `_table`      | String |
+
+
+### AWS CLI
+
+```bash
+aws dynamodb create-table \
+  --table-name my-auth-table \
+  --attribute-definitions \
+    AttributeName=_pk,AttributeType=S \
+    AttributeName=_sk,AttributeType=S \
+    AttributeName=_table,AttributeType=S \
+  --key-schema \
+    AttributeName=_pk,KeyType=HASH \
+    AttributeName=_sk,KeyType=RANGE \
+  --global-secondary-indexes \
+    '[{
+      "IndexName": "_table-index",
+      "KeySchema": [{"AttributeName": "_table", "KeyType": "HASH"}],
+      "Projection": {"ProjectionType": "ALL"}
+    }]' \
+  --billing-mode PAY_PER_REQUEST
+```
+
+### CDK
+
+```ts
+import { Table, AttributeType, BillingMode, ProjectionType } from "aws-cdk-lib/aws-dynamodb";
+
+const table = new Table(this, "AuthTable", {
+  tableName: "my-auth-table",
+  partitionKey: { name: "_pk", type: AttributeType.STRING },
+  sortKey: { name: "_sk", type: AttributeType.STRING },
+  billingMode: BillingMode.PAY_PER_REQUEST,
+});
+
+table.addGlobalSecondaryIndex({
+  indexName: "_table-index",
+  partitionKey: { name: "_table", type: AttributeType.STRING },
+  projectionType: ProjectionType.ALL,
+});
+```
+
+## Usage
+
+> Your DynamoDB table must already exist before using this adapter. See [DynamoDB Table Setup](#dynamodb-table-setup) above.
+
+### Basic setup
+
+```ts
+// auth.ts
+import { betterAuth } from "better-auth";
+import dynamoDBAdapter from "betterauth-dynamodb-adapter";
+
+export const auth = betterAuth({
+  database: dynamoDBAdapter({
+    tableName: "my-auth-table",
+    region: "us-east-1",
+  }),
+  emailAndPassword: {
+    enabled: true,
+  },
+});
+```
+
+### With social providers
+
+```ts
+// auth.ts
+import { betterAuth } from "better-auth";
+import dynamoDBAdapter from "betterauth-dynamodb-adapter";
+
+export const auth = betterAuth({
+  database: dynamoDBAdapter({
+    tableName: "my-auth-table",
+    region: "us-east-1",
+  }),
+  emailAndPassword: {
+    enabled: true,
+  },
+  socialProviders: {
+    google: {
+      clientId: process.env.GOOGLE_CLIENT_ID!,
+      clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
+    },
+    github: {
+      clientId: process.env.GITHUB_CLIENT_ID!,
+      clientSecret: process.env.GITHUB_CLIENT_SECRET!,
+    },
+  },
+});
+```
+
+### With Next.js
+
+```ts
+// app/api/auth/[...all]/route.ts
+import { auth } from "@/auth";
+import { toNextJsHandler } from "better-auth/next-js";
+
+export const { GET, POST } = toNextJsHandler(auth);
+```
+
+### Client-side
+
+```ts
+// lib/auth-client.ts
+import { createAuthClient } from "better-auth/client";
+
+export const authClient = createAuthClient();
+
+// Sign up
+await authClient.signUp.email({
+  email: "[email]",
+  password: "[password]",
+  name: "[name]",
+});
+
+// Sign in
+await authClient.signIn.email({
+  email: "[email]",
+  password: "[password]",
+});
+```
+
+## How It Works
+
+### Single-table design
+
+All Better Auth models (users, sessions, accounts, etc.) are stored in a single DynamoDB table. Each item has three internal attributes managed by the adapter:
+
+| Attribute | Format         | Purpose                         |
+|-----------|----------------|---------------------------------|
+| `_pk`     | `{model}#{id}` | Partition key for direct access |
+| `_sk`     | `{model}#{id}` | Sort key (same as `_pk`)        |
+| `_table`  | `{model}`      | GSI partition key for queries   |
+
+These internal attributes are automatically stripped from results returned to Better Auth.
+
+### Query strategy
+
+- **Single ID lookup** → `GetItem` (fastest, single read unit)
+- **Filtered queries** → GSI query on `_table-index` with DynamoDB `FilterExpression`
+- **Sorting & pagination** → performed in-memory after query results are returned
+
+### Supported filter operators
+
+| Operator      | DynamoDB expression         |
+|---------------|-----------------------------|
+| `eq`          | `field = value`             |
+| `ne`          | `field <> value`            |
+| `gt`          | `field > value`             |
+| `gte`         | `field >= value`            |
+| `lt`          | `field < value`             |
+| `lte`         | `field <= value`            |
+| `in`          | `field IN (values)`         |
+| `not_in`      | `NOT field IN (values)`     |
+| `contains`    | `contains(field, value)`    |
+| `starts_with` | `begins_with(field, value)` |
+| `ends_with`   | `contains(field, value)` *  |
+
+> \* DynamoDB does not natively support `ends_with`, so it falls back to `contains`.
+
+## Configuration
+
+```ts
+dynamoDBAdapter({
+  tableName: string;  // DynamoDB table name
+  region: string;     // AWS region (e.g. "us-east-1")
+})
+```
+
+## Adapter Capabilities
+
+| Capability      | Supported |
+|-----------------|-----------|
+| JSON fields     | No        |
+| Date fields     | No        |
+| Boolean fields  | No        |
+| Numeric IDs     | No        |
+
+All values are stored as DynamoDB strings/numbers. Dates should be stored as ISO strings or Unix timestamps by Better Auth before reaching the adapter.
+
+## License
+
+[MIT](LICENSE)

package/dist/index.cjs

@@ -0,0 +1 @@
+var e=(e,t)=>()=>(t||e((t={exports:{}}).exports,t),t.exports);let t=require(`better-auth/adapters`),n=require(`@aws-sdk/client-dynamodb`);var r=e((e=>{var t=class e{value;constructor(e){typeof e==`object`&&`N`in e?this.value=String(e.N):this.value=String(e);let t=typeof e.valueOf()==`number`?e.valueOf():0;if(t>2**53-1||t<-(2**53-1)||Math.abs(t)===1/0||Number.isNaN(t))throw Error(`NumberValue should not be initialized with an imprecise number=${t}. Use a string instead.`)}static from(t){return new e(t)}toAttributeValue(){return{N:this.toString()}}toBigInt(){let e=this.toString();return BigInt(e)}toString(){return String(this.value)}valueOf(){return this.toString()}};let n=(e,n)=>{if(e===void 0)throw Error(`Pass options.removeUndefinedValues=true to remove undefined values from map/array/set.`);if(e===null&&typeof e==`object`)return s();if(Array.isArray(e))return r(e,n);if(e?.constructor?.name===`Set`)return i(e,n);if(e?.constructor?.name===`Map`)return a(e,n);if(e?.constructor?.name===`Object`||!e.constructor&&typeof e==`object`)return o(e,n);if(p(e))return e.length===0&&n?.convertEmptyValues?s():c(e);if(typeof e==`boolean`||e?.constructor?.name===`Boolean`)return{BOOL:e.valueOf()};if(typeof e==`number`||e?.constructor?.name===`Number`)return f(e,n);if(e instanceof t)return e.toAttributeValue();if(typeof e==`bigint`)return u(e);if(typeof e==`string`||e?.constructor?.name===`String`)return e.length===0&&n?.convertEmptyValues?s():l(e);if(n?.convertClassInstanceToMap&&typeof e==`object`)return o(e,n);throw Error(`Unsupported type passed: ${e}. Pass options.convertClassInstanceToMap=true to marshall typeof object as map attribute.`)},r=(e,t)=>({L:e.filter(e=>typeof e!=`function`&&(!t?.removeUndefinedValues||t?.removeUndefinedValues&&e!==void 0)).map(e=>n(e,t))}),i=(e,n)=>{let r=n?.removeUndefinedValues?new Set([...e].filter(e=>e!==void 0)):e;if(!n?.removeUndefinedValues&&r.has(void 0))throw Error(`Pass options.removeUndefinedValues=true to remove undefined values from map/array/set.`);if(r.size===0){if(n?.convertEmptyValues)return s();throw Error(`Pass a non-empty set, or options.convertEmptyValues=true.`)}let i=r.values().next().value;if(i instanceof t)return{NS:Array.from(r).map(e=>e.toString())};if(typeof i==`number`)return{NS:Array.from(r).map(e=>f(e,n)).map(e=>e.N)};if(typeof i==`bigint`)return{NS:Array.from(r).map(u).map(e=>e.N)};if(typeof i==`string`)return{SS:Array.from(r).map(l).map(e=>e.S)};if(p(i))return{BS:Array.from(r).map(c).map(e=>e.B)};throw Error(`Only Number Set (NS), Binary Set (BS) or String Set (SS) are allowed.`)},a=(e,t)=>({M:(e=>{let r={};for(let[i,a]of e)typeof a!=`function`&&(a!==void 0||!t?.removeUndefinedValues)&&(r[i]=n(a,t));return r})(e)}),o=(e,t)=>({M:(e=>{let r={};for(let i in e){let a=e[i];typeof a!=`function`&&(a!==void 0||!t?.removeUndefinedValues)&&(r[i]=n(a,t))}return r})(e)}),s=()=>({NULL:!0}),c=e=>({B:e}),l=e=>({S:e.toString()}),u=e=>({N:e.toString()}),d=e=>{throw Error(`${e} Use NumberValue from @aws-sdk/lib-dynamodb.`)},f=(e,t)=>{if([NaN,1/0,-1/0].map(e=>e.toString()).includes(e.toString()))throw Error(`Special numeric value ${e.toString()} is not allowed`);return t?.allowImpreciseNumbers||(Number(e)>2**53-1?d(`Number ${e.toString()} is greater than Number.MAX_SAFE_INTEGER.`):Number(e)<-(2**53-1)&&d(`Number ${e.toString()} is lesser than Number.MIN_SAFE_INTEGER.`)),{N:e.toString()}},p=e=>e?.constructor?[`ArrayBuffer`,`Blob`,`Buffer`,`DataView`,`File`,`Int8Array`,`Uint8Array`,`Uint8ClampedArray`,`Int16Array`,`Uint16Array`,`Int32Array`,`Uint32Array`,`Float32Array`,`Float64Array`,`BigInt64Array`,`BigUint64Array`].includes(e.constructor.name):!1,m=(e,t)=>{for(let[n,r]of Object.entries(e))if(r!==void 0)switch(n){case`NULL`:return null;case`BOOL`:return!!r;case`N`:return h(r,t);case`B`:return _(r);case`S`:return g(r);case`L`:return v(r,t);case`M`:return y(r,t);case`NS`:return new Set(r.map(e=>h(e,t)));case`BS`:return new Set(r.map(_));case`SS`:return new Set(r.map(g));default:throw Error(`Unsupported type passed: ${n}`)}throw Error(`No value defined: ${JSON.stringify(e)}`)},h=(e,n)=>{if(typeof n?.wrapNumbers==`function`)return n?.wrapNumbers(e);if(n?.wrapNumbers)return t.from(e);let r=Number(e);if((r>2**53-1||r<-(2**53-1))&&![1/0,-1/0].includes(r))if(typeof BigInt==`function`)try{return BigInt(e)}catch{throw Error(`${e} can't be converted to BigInt. Set options.wrapNumbers to get string value.`)}else throw Error(`${e} is outside SAFE_INTEGER bounds. Set options.wrapNumbers to get string value.`);return r},g=e=>e,_=e=>e,v=(e,t)=>e.map(e=>m(e,t)),y=(e,t)=>Object.entries(e).reduce((e,[n,r])=>(e[n]=m(r,t),e),{});function b(e,t){let r=n(e,t),[i,a]=Object.entries(r)[0];switch(i){case`M`:case`L`:return t?.convertTopLevelContainer?r:a;default:return r}}e.marshall=b,e.unmarshall=(e,t)=>t?.convertWithoutMapWrapper?m(e,t):m({M:e},t)}))();const i=e=>{let{tableName:i,region:a}=e,o=new n.DynamoDBClient({region:a});function s(e){let{_pk:t,_sk:n,_table:r,...i}=e;return i}function c(e){let t=[],n={},r={};return e.forEach((e,i)=>{let a=`#w${i}`,o=`:w${i}`;r[a]=e.field;let s;switch(e.operator){case`ne`:n[o]=e.value,s=`${a} <> ${o}`;break;case`gt`:n[o]=e.value,s=`${a} > ${o}`;break;case`gte`:n[o]=e.value,s=`${a} >= ${o}`;break;case`lt`:n[o]=e.value,s=`${a} < ${o}`;break;case`lte`:n[o]=e.value,s=`${a} <= ${o}`;break;case`in`:case`not_in`:{let t=e.value,r=t.map((e,t)=>`:w${i}_${t}`);t.forEach((e,t)=>{n[`:w${i}_${t}`]=e});let o=`${a} IN (${r.join(`,`)})`;s=e.operator===`not_in`?`NOT ${o}`:o;break}case`contains`:n[o]=e.value,s=`contains(${a}, ${o})`;break;case`starts_with`:n[o]=e.value,s=`begins_with(${a}, ${o})`;break;case`ends_with`:n[o]=e.value,s=`contains(${a}, ${o})`;break;default:n[o]=e.value,s=`${a} = ${o}`;break}i>0&&t.push(e.connector===`OR`?`OR`:`AND`),t.push(s)}),{expression:t.join(` `),vals:n,names:r}}async function l(e,t){let a={"#_table":`_table`},l={":_table":e},u,d=a,f=l;if(t&&t.length>0){let e=c(t);u=e.expression,d={...a,...e.names},f={...l,...e.vals}}return((await o.send(new n.QueryCommand({TableName:i,IndexName:`_table-index`,KeyConditionExpression:`#_table = :_table`,FilterExpression:u,ExpressionAttributeNames:d,ExpressionAttributeValues:(0,r.marshall)(f)}))).Items||[]).map(e=>s((0,r.unmarshall)(e)))}return(0,t.createAdapterFactory)({config:{adapterId:`dynamodb`,adapterName:`DynamoDB Adapter`,supportsJSON:!1,supportsDates:!1,supportsBooleans:!1,supportsNumericIds:!1},adapter:()=>({create:async({model:e,data:t})=>{let a=t.id||crypto.randomUUID(),s={...t,id:a,_pk:`${e}#${a}`,_sk:`${e}#${a}`,_table:e};return await o.send(new n.PutItemCommand({TableName:i,Item:(0,r.marshall)(s,{removeUndefinedValues:!0})})),{...t,id:a}},findOne:async({model:e,where:t})=>{if(t.length===1&&t[0].field===`id`&&t[0].operator===`eq`){let a=t[0].value,c=await o.send(new n.GetItemCommand({TableName:i,Key:(0,r.marshall)({_pk:`${e}#${a}`,_sk:`${e}#${a}`})}));return c.Item?s((0,r.unmarshall)(c.Item)):null}return(await l(e,t))[0]||null},findMany:async({model:e,where:t,limit:n,sortBy:r,offset:i})=>{let a=await l(e,t);if(r){let e=r.direction===`desc`?-1:1;a.sort((t,n)=>t[r.field]<n[r.field]?-1*e:t[r.field]>n[r.field]?1*e:0)}return i&&(a=a.slice(i)),n&&(a=a.slice(0,n)),a},update:async({model:e,where:t,update:a})=>{let s=await l(e,t);if(s.length===0)return null;let c=s[0],u=c.id,d=Object.entries(a),f=[],p={},m={};return d.forEach(([e,t],n)=>{e===`id`||e.startsWith(`_`)||(f.push(`#u${n} = :u${n}`),m[`#u${n}`]=e,p[`:u${n}`]=t)}),f.length===0?c:(await o.send(new n.UpdateItemCommand({TableName:i,Key:(0,r.marshall)({_pk:`${e}#${u}`,_sk:`${e}#${u}`}),UpdateExpression:`SET ${f.join(`, `)}`,ExpressionAttributeNames:m,ExpressionAttributeValues:(0,r.marshall)(p,{removeUndefinedValues:!0})})),{...c,...a})},updateMany:async({model:e,where:t,update:a})=>{let s=await l(e,t),c=0;for(let t of s){let s=Object.entries(a),l=[],u={},d={};s.forEach(([e,t],n)=>{e===`id`||e.startsWith(`_`)||(l.push(`#u${n} = :u${n}`),d[`#u${n}`]=e,u[`:u${n}`]=t)}),l.length!==0&&(await o.send(new n.UpdateItemCommand({TableName:i,Key:(0,r.marshall)({_pk:`${e}#${t.id}`,_sk:`${e}#${t.id}`}),UpdateExpression:`SET ${l.join(`, `)}`,ExpressionAttributeNames:d,ExpressionAttributeValues:(0,r.marshall)(u,{removeUndefinedValues:!0})})),c++)}return c},delete:async({model:e,where:t})=>{let a=await l(e,t);a.length!==0&&await o.send(new n.DeleteItemCommand({TableName:i,Key:(0,r.marshall)({_pk:`${e}#${a[0].id}`,_sk:`${e}#${a[0].id}`})}))},deleteMany:async({model:e,where:t})=>{let a=await l(e,t);for(let t of a)await o.send(new n.DeleteItemCommand({TableName:i,Key:(0,r.marshall)({_pk:`${e}#${t.id}`,_sk:`${e}#${t.id}`})}));return a.length},count:async({model:e,where:t})=>(await l(e,t)).length})})};module.exports=i;