@x-sls/dynamodb-users 1.0.0

package/README.md

@@ -0,0 +1,199 @@
+# @x-sls/dynamodb-users
+
+Helpers for managing users in DynamoDB: create, update, get by ID or email, and list users by lookup list (e.g. active/inactive). The library never creates a DynamoDB client; you pass in a DocumentClient and table name.
+
+## Table requirements
+
+- **Base table:** partition key `pk` (String), sort key `sk` (String).
+- **GSI (default name `gsi1`):** partition key `pk1` (String), sort key `sk1` (String).
+
+If your table uses different key or index names, override them via `options.schema` (see [Schema](#schema)).
+
+## Data model
+
+Each user is represented by:
+
+1. **User item** — Main record: `pk = U#<uuid>`, `sk = A`, plus `pk1`/`sk1` for email lookup on the GSI (e.g. `pk1 = email#<normalized>`, `sk1 = A`). Get by ID via base table; get by email via GSI query.
+2. **Email item** — Sentinel for by-email lookup when the GSI is eventually consistent: `pk = EMAIL#<normalized>`, `sk = A`, `userId`. The library queries the GSI first, then falls back to this item + `getUser`.
+3. **LOOKUP item (optional)** — For list queries: `pk = U#<id>`, `sk = LOOKUP`, `pk1 = <lookupList>` (e.g. `USER#ACTIVE`), `sk1 = <normalized name>`. Projected attributes (e.g. email, name, picture, userId). Created/updated when `createLookupItem` / `updateLookupItem` are not set to `false`.
+
+## Installation
+
+```bash
+npm install @x-sls/dynamodb-users
+```
+
+**Peer dependency:** `@aws-sdk/lib-dynamodb` (DocumentClient). You must provide your own DynamoDB client and pass it via options.
+
+## API
+
+All functions take an `options` object that must include `documentClient` and `tableName`. Optional `schema` overrides the default key/index names and prefixes.
+
+### getUser(userId, options)
+
+Get a user by ID (with or without `U#` prefix).
+
+- **Returns:** User item or `null`.
+- **Options:** `documentClient`, `tableName` (required); `schema` (optional).
+
+```js
+const user = await getUser('abc-123', { documentClient, tableName });
+const user2 = await getUser('U#abc-123', { documentClient, tableName });
+```
+
+### getUserByEmail(email, options)
+
+Get a user by email. Queries the GSI first; if empty, falls back to the EMAIL sentinel and then `getUser`.
+
+- **Returns:** User item or `null`.
+- **Options:** `documentClient`, `tableName` (required); `schema` (optional; must have `lookupIndex` for by-email); `normalizeEmailFn` (optional, default: lowercased trim).
+
+```js
+const user = await getUserByEmail('alice@example.com', { documentClient, tableName });
+```
+
+### createUser(input, options)
+
+Create a user atomically: user item + email sentinel. By default also writes a LOOKUP item so the user can be returned by `listUsers` (opt-out with `createLookupItem: false`).
+
+- **Input:** `email`, `name` (required). Other keys (e.g. `picture`, `status`) are stored on the user item.
+- **Returns:** The created user item.
+- **Throws:** `"User with this email already exists"` on duplicate email (transaction conditional check).
+- **Options:** `documentClient`, `tableName` (required); `createLookupItem` (default `true`); `lookupList` (optional, default from `schema.defaultLookupList` e.g. `USER#ACTIVE`); `lookupExtraAttributes` (array of attribute names to add to LOOKUP); `extraTransactItems`, `normalizeEmailFn`, `schema` (optional).
+
+```js
+const user = await createUser(
+  { email: 'alice@example.com', name: 'Alice' },
+  { documentClient, tableName }
+);
+// With custom list
+await createUser(
+  { email: 'bob@example.com', name: 'Bob' },
+  { documentClient, tableName, lookupList: 'USER#INACTIVE' }
+);
+```
+
+### updateUser(userId, updates, options)
+
+Update a user. Writes a version record (if `createVersionRecord` is true), updates the user item, and on email change updates/deletes/puts email sentinels. By default also (re)writes the LOOKUP item (opt-out with `updateLookupItem: false`).
+
+- **Returns:** Updated user item.
+- **Throws:** `"User not found"`, or `"User with this email already exists"` if email is changed to an existing one.
+- **Options:** `documentClient`, `tableName`, `modifiedBy`, `modifiedReason` (required); `createVersionRecord` (default `true`); `updateLookupItem` (default `true`); `lookupList` (optional); `lookupExtraAttributes`; `allowedUpdateFields` (if set, only these keys are updated); `extraTransactItems`, `normalizeEmailFn`, `schema` (optional).
+
+```js
+await updateUser(
+  userId,
+  { name: 'Alice Smith' },
+  { documentClient, tableName, modifiedBy: 'admin', modifiedReason: 'name change' }
+);
+// Move to inactive list
+await updateUser(
+  userId,
+  {},
+  { documentClient, tableName, modifiedBy: 'admin', modifiedReason: 'deactivate', lookupList: 'USER#INACTIVE' }
+);
+```
+
+### listUsers(options)
+
+List users by querying the LOOKUP index (GSI). Only returns users for whom LOOKUP items exist (created/updated by this library with LOOKUP enabled). If you never create LOOKUP items, `listUsers` will return empty results; implement your own list logic in that case.
+
+- **Returns:** `{ items: object[], lastEvaluatedKey: object | null }`. Each item is a LOOKUP row (projected attributes + `userId`). Use `lastEvaluatedKey` for pagination.
+- **Options:** `documentClient`, `tableName`, `lookupList` (required, e.g. `'USER#ACTIVE'`); `beginsWith` (optional, prefix match on normalized name); `limit` (default 50, max 100); `exclusiveStartKey`, `scanIndexForward`; `schema` (optional).
+
+```js
+const { items, lastEvaluatedKey } = await listUsers({
+  documentClient,
+  tableName,
+  lookupList: 'USER#ACTIVE'
+});
+// Pagination
+const next = await listUsers({
+  documentClient,
+  tableName,
+  lookupList: 'USER#ACTIVE',
+  exclusiveStartKey: lastEvaluatedKey
+});
+// Search by name prefix (normalized)
+const { items } = await listUsers({
+  documentClient,
+  tableName,
+  lookupList: 'USER#ACTIVE',
+  beginsWith: 'alice'
+});
+```
+
+## LOOKUP behavior (opt-out)
+
+- **createUser:** Creates a LOOKUP item by default (`createLookupItem` defaults to `true`), so new users appear in the default list (e.g. `USER#ACTIVE`) and can be listed. Set `createLookupItem: false` to skip LOOKUP.
+- **updateUser:** Updates the LOOKUP item by default (`updateLookupItem` defaults to `true`). Set `updateLookupItem: false` to skip LOOKUP.
+- **listUsers:** Only returns items that match the LOOKUP pattern (same GSI, `pk1 = lookupList`). If you opt out of LOOKUP on create/update, you must implement your own listing (e.g. Scan or custom GSI).
+
+## Schema
+
+The library uses a default schema (exported as `DEFAULT_SCHEMA`). Override specific keys by passing `options.schema`; it is merged over the default.
+
+| Key | Default | Description |
+|-----|---------|-------------|
+| `userItemPK` | `'pk'` | Base table partition key attribute name |
+| `userItemSK` | `'sk'` | Base table sort key attribute name |
+| `userItemPrefix` | `'U#'` | Prefix for user item `pk` |
+| `userItemLookupPrefix` | `'email#'` | Prefix for user item GSI pk1 (email lookup) |
+| `userItemSKValue` | `'A'` | User item `sk` value |
+| `userItemLookupSKValue` | `'A'` | User item GSI sk1 value for email lookup |
+| `lookupIndex` | `'gsi1'` | GSI name |
+| `lookupIndexPK` | `'pk1'` | GSI partition key attribute |
+| `lookupIndexSK` | `'sk1'` | GSI sort key attribute |
+| `lookupItemSK` | `'LOOKUP'` | LOOKUP item `sk` value |
+| `defaultLookupList` | `'USER#ACTIVE'` | Default list for new users (LOOKUP pk1) |
+| `emailItemPrefix` | `'EMAIL#'` | Email sentinel `pk` prefix |
+| `emailItemUserAttribute` | `'userId'` | Attribute name for user ID on email/LOOKUP items |
+
+Example: use `U#` for the email lookup key instead of `email#`:
+
+```js
+const user = await getUserByEmail('alice@example.com', {
+  documentClient,
+  tableName,
+  schema: { userItemLookupPrefix: 'U#' }
+});
+```
+
+## Example: full flow
+
+```js
+const { createUser, getUser, getUserByEmail, updateUser, listUsers } = require('@x-sls/dynamodb-users');
+const { DynamoDBClient } = require('@aws-sdk/client-dynamodb');
+const { DynamoDBDocument } = require('@aws-sdk/lib-dynamodb');
+
+const client = new DynamoDBClient({ region: 'us-east-1' });
+const documentClient = DynamoDBDocument.from(client);
+const tableName = process.env.USERS_TABLE;
+
+const opts = { documentClient, tableName };
+
+// Create (includes LOOKUP on USER#ACTIVE by default)
+const user = await createUser({ email: 'alice@example.com', name: 'Alice' }, opts);
+
+// Get by ID or email
+const byId = await getUser(user.pk, opts);
+const byEmail = await getUserByEmail('alice@example.com', opts);
+
+// List active users
+const { items } = await listUsers({ ...opts, lookupList: 'USER#ACTIVE' });
+
+// Mark inactive
+await updateUser(user.pk, {}, { ...opts, modifiedBy: 'system', modifiedReason: 'deactivate', lookupList: 'USER#INACTIVE' });
+
+// List inactive users
+const { items: inactive } = await listUsers({ ...opts, lookupList: 'USER#INACTIVE' });
+```
+
+## Tests
+
+```bash
+npm test
+```
+
+Uses Node's built-in test runner (`node --test`).

package/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "@x-sls/dynamodb-users",
+  "version": "1.0.0",
+  "main": "src/index.js",
+  "scripts": {
+    "test": "node --test src/__tests__/*.js"
+  },
+  "peerDependencies": {
+    "@aws-sdk/lib-dynamodb": "^3.1006.0"
+  },
+  "devDependencies": {
+    "@aws-sdk/lib-dynamodb": "^3.1006.0"
+  }
+}

package/src/__tests__/index.test.js

@@ -0,0 +1,251 @@
+const { describe, it } = require('node:test');
+const assert = require('node:assert');
+const {
+  DEFAULT_SCHEMA,
+  getUser,
+  getUserByEmail,
+  createUser,
+  updateUser
+} = require('../index.js');
+
+function createMockDocClient(returnValues) {
+  const queue = Array.isArray(returnValues) ? [...returnValues] : [returnValues];
+  return {
+    send: async () => {
+      const next = queue.shift();
+      if (next instanceof Error) throw next;
+      return next;
+    }
+  };
+}
+
+const TABLE = 'test-table';
+const baseOptions = { documentClient: null, tableName: TABLE };
+
+describe('getUser', () => {
+  it('returns null when userId is falsy', async () => {
+    const doc = createMockDocClient({ Item: null });
+    assert.strictEqual(await getUser('', { ...baseOptions, documentClient: doc }), null);
+    assert.strictEqual(await getUser(null, { ...baseOptions, documentClient: doc }), null);
+  });
+
+  it('throws when documentClient or tableName is missing', async () => {
+    const doc = createMockDocClient({ Item: null });
+    await assert.rejects(() => getUser('user-1', {}), /getUser requires options.documentClient and options.tableName/);
+    await assert.rejects(() => getUser('user-1', { documentClient: doc }), /getUser requires options.documentClient and options.tableName/);
+    await assert.rejects(() => getUser('user-1', { tableName: TABLE }), /getUser requires options.documentClient and options.tableName/);
+  });
+
+  it('returns null when item is not found', async () => {
+    const doc = createMockDocClient({ Item: null });
+    const result = await getUser('user-1', { ...baseOptions, documentClient: doc });
+    assert.strictEqual(result, null);
+  });
+
+  it('returns item when found (userId without prefix)', async () => {
+    const item = { pk: 'U#user-1', sk: 'A', name: 'Test', email: 'test@example.com' };
+    const doc = createMockDocClient({ Item: item });
+    const result = await getUser('user-1', { ...baseOptions, documentClient: doc });
+    assert.deepStrictEqual(result, item);
+  });
+
+  it('returns item when found (userId with U# prefix)', async () => {
+    const item = { pk: 'U#user-1', sk: 'A', name: 'Test' };
+    const doc = createMockDocClient({ Item: item });
+    const result = await getUser('U#user-1', { ...baseOptions, documentClient: doc });
+    assert.deepStrictEqual(result, item);
+  });
+
+  it('coerces userId to string', async () => {
+    const item = { pk: 'U#123', sk: 'A' };
+    const doc = createMockDocClient({ Item: item });
+    const result = await getUser(123, { ...baseOptions, documentClient: doc });
+    assert.deepStrictEqual(result, item);
+  });
+});
+
+describe('getUserByEmail', () => {
+  it('returns null when email is falsy', async () => {
+    const doc = createMockDocClient({ Items: [] });
+    assert.strictEqual(await getUserByEmail('', { ...baseOptions, documentClient: doc, schema: { ...DEFAULT_SCHEMA } }), null);
+  });
+
+  it('throws when documentClient, tableName, or schema.lookupIndex missing', async () => {
+    const doc = createMockDocClient({ Items: [] });
+    await assert.rejects(() => getUserByEmail('a@b.com', {}), /getUserByEmail requires options.documentClient and options.tableName/);
+    await assert.rejects(() => getUserByEmail('a@b.com', { ...baseOptions, documentClient: doc, schema: { ...DEFAULT_SCHEMA, lookupIndex: '' } }), /getUserByEmail requires schema.lookupIndex/);
+  });
+
+  it('returns first item from index when GSI has results', async () => {
+    const item = { pk: 'U#user-1', sk: 'A', pk1: 'email#a@b.com', sk1: 'A', name: 'Test' };
+    const doc = createMockDocClient({ Items: [item] });
+    const result = await getUserByEmail('a@b.com', { ...baseOptions, documentClient: doc });
+    assert.deepStrictEqual(result, item);
+  });
+
+  it('uses schema override for lookup prefix (userItemLookupPrefix)', async () => {
+    const item = { pk: 'U#user-1', sk: 'A', pk1: 'U#a@b.com', sk1: 'A', name: 'Test' };
+    let capturedQuery;
+    const doc = createMockDocClient({ Items: [item] });
+    const origSend = doc.send.bind(doc);
+    doc.send = async (cmd) => {
+      if (cmd.input?.KeyConditionExpression) capturedQuery = { names: cmd.input.ExpressionAttributeNames, values: cmd.input.ExpressionAttributeValues };
+      return origSend(cmd);
+    };
+    const result = await getUserByEmail('a@b.com', { ...baseOptions, documentClient: doc, schema: { userItemLookupPrefix: 'U#' } });
+    assert.deepStrictEqual(result, item);
+    assert.strictEqual(capturedQuery?.values?.[':pk1'], 'U#a@b.com');
+  });
+
+  it('falls back to email sentinel then getUser when GSI is empty', async () => {
+    const userItem = { pk: 'U#user-1', sk: 'A', name: 'Test', email: 'a@b.com' };
+    const doc = createMockDocClient([
+      { Items: [] },
+      { Item: { [DEFAULT_SCHEMA.userItemPK]: 'EMAIL#a@b.com', [DEFAULT_SCHEMA.userItemSK]: 'A', [DEFAULT_SCHEMA.emailItemUserAttribute]: 'user-1' } },
+      { Item: userItem }
+    ]);
+    const result = await getUserByEmail('a@b.com', { ...baseOptions, documentClient: doc });
+    assert.deepStrictEqual(result, userItem);
+  });
+
+  it('returns null when GSI empty and no email sentinel', async () => {
+    const doc = createMockDocClient([{ Items: [] }, { Item: null }]);
+    const result = await getUserByEmail('missing@b.com', { ...baseOptions, documentClient: doc });
+    assert.strictEqual(result, null);
+  });
+});
+
+describe('createUser', () => {
+  it('throws when email or name is missing', async () => {
+    const doc = createMockDocClient(undefined);
+    await assert.rejects(() => createUser({ name: 'Test' }, { ...baseOptions, documentClient: doc }), /Email is required/);
+    await assert.rejects(() => createUser({ email: 'a@b.com' }, { ...baseOptions, documentClient: doc }), /Name is required/);
+    await assert.rejects(() => createUser({ email: '  ', name: 'Test' }, { ...baseOptions, documentClient: doc }), /Email is required/);
+  });
+
+  it('throws when documentClient or tableName is missing', async () => {
+    await assert.rejects(() => createUser({ email: 'a@b.com', name: 'Test' }, {}), /createUser requires options.documentClient and options.tableName/);
+  });
+
+  it('sends TransactWrite with user A, email item, and default LOOKUP item (USER#ACTIVE), returns userA', async () => {
+    let capturedTransactItems;
+    const doc = createMockDocClient(undefined);
+    doc.send = async (cmd) => {
+      capturedTransactItems = cmd.input?.TransactItems;
+      return undefined;
+    };
+    const result = await createUser({ email: 'a@b.com', name: 'Test' }, { ...baseOptions, documentClient: doc });
+    assert.ok(Array.isArray(capturedTransactItems));
+    assert.strictEqual(capturedTransactItems.length, 3);
+    assert.strictEqual(capturedTransactItems[0].Put.Item.type, DEFAULT_SCHEMA.userItemType);
+    assert.strictEqual(capturedTransactItems[1].Put.Item.type, DEFAULT_SCHEMA.emailItemType);
+    const lookupItem = capturedTransactItems[2].Put.Item;
+    assert.strictEqual(lookupItem.type, DEFAULT_SCHEMA.lookupItemType);
+    assert.strictEqual(lookupItem.sk, DEFAULT_SCHEMA.lookupItemSK);
+    assert.strictEqual(lookupItem.pk1, 'USER#ACTIVE');
+    assert.strictEqual(lookupItem.sk1, 'test');
+    assert.ok(result.pk.startsWith('U#'));
+    assert.strictEqual(result.sk, 'A');
+    assert.strictEqual(result.email, 'a@b.com');
+    assert.strictEqual(result.name, 'Test');
+  });
+
+  it('when createLookupItem false, sends only user A and email item', async () => {
+    let capturedTransactItems;
+    const doc = createMockDocClient(undefined);
+    doc.send = async (cmd) => {
+      capturedTransactItems = cmd.input?.TransactItems;
+      return undefined;
+    };
+    await createUser({ email: 'a@b.com', name: 'Test' }, { ...baseOptions, documentClient: doc, createLookupItem: false });
+    assert.strictEqual(capturedTransactItems.length, 2);
+    assert.strictEqual(capturedTransactItems[0].Put.Item.type, DEFAULT_SCHEMA.userItemType);
+    assert.strictEqual(capturedTransactItems[1].Put.Item.type, DEFAULT_SCHEMA.emailItemType);
+  });
+
+  it('throws User with this email already exists on TransactionCanceledException', async () => {
+    const doc = createMockDocClient(Object.assign(new Error(), { name: 'TransactionCanceledException' }));
+    await assert.rejects(() => createUser({ email: 'a@b.com', name: 'Test' }, { ...baseOptions, documentClient: doc }), /User with this email already exists/);
+  });
+
+  it('uses schema override for lookup prefix (userItemLookupPrefix) in written user item', async () => {
+    let capturedUserItem;
+    const doc = createMockDocClient(undefined);
+    doc.send = async (cmd) => {
+      const items = cmd.input?.TransactItems;
+      if (Array.isArray(items) && items[0]?.Put?.Item) capturedUserItem = items[0].Put.Item;
+      return undefined;
+    };
+    await createUser({ email: 'a@b.com', name: 'Test' }, { ...baseOptions, documentClient: doc, schema: { userItemLookupPrefix: 'U#' } });
+    assert.ok(capturedUserItem);
+    assert.strictEqual(capturedUserItem.pk1, 'U#a@b.com');
+    assert.ok(capturedUserItem.pk.startsWith('U#'));
+  });
+});
+
+describe('updateUser', () => {
+  const currentUser = { pk: 'U#user-1', sk: 'A', name: 'Old', email: 'old@b.com', modifiedAt: 'x', modifiedBy: 'x', modifiedReason: 'x' };
+
+  it('throws when documentClient, tableName, modifiedBy or modifiedReason missing', async () => {
+    const doc = createMockDocClient({ Item: currentUser });
+    await assert.rejects(() => updateUser('user-1', { name: 'New' }, {}), /updateUser requires options.documentClient and options.tableName/);
+    await assert.rejects(() => updateUser('user-1', { name: 'New' }, { ...baseOptions, documentClient: doc }), /updateUser requires options.modifiedBy and options.modifiedReason/);
+  });
+
+  it('throws when user not found', async () => {
+    const doc = createMockDocClient({ Item: null });
+    await assert.rejects(() => updateUser('user-1', { name: 'New' }, { ...baseOptions, documentClient: doc, modifiedBy: 'u', modifiedReason: 'r' }), /User not found/);
+  });
+
+  it('sends Update and returns updatedUser shape', async () => {
+    let callCount = 0;
+    let transactItems;
+    const doc = {
+      send: async (cmd) => {
+        if (cmd.input?.TransactItems) transactItems = cmd.input.TransactItems;
+        return callCount++ === 0 ? { Item: currentUser } : undefined;
+      }
+    };
+    const result = await updateUser('user-1', { name: 'New Name' }, { ...baseOptions, documentClient: doc, modifiedBy: 'u', modifiedReason: 'r' });
+    assert.strictEqual(result.name, 'New Name');
+    assert.strictEqual(result.email, 'old@b.com');
+    assert.ok(transactItems.some((t) => t.Update));
+  });
+
+  it('when email change: includes pk1/sk1 in Update and Delete + Put sentinels', async () => {
+    let callCount = 0;
+    let transactItems;
+    const doc = {
+      send: async (cmd) => {
+        if (cmd.input?.TransactItems) transactItems = cmd.input.TransactItems;
+        return callCount++ === 0 ? { Item: currentUser } : undefined;
+      }
+    };
+    await updateUser('user-1', { email: 'new@b.com' }, { ...baseOptions, documentClient: doc, modifiedBy: 'u', modifiedReason: 'r' });
+    const updateOp = transactItems.find((t) => t.Update);
+    assert.ok(updateOp?.Update?.ExpressionAttributeValues?.[':pk1']?.includes('new@b.com'));
+    const deleteOp = transactItems.find((t) => t.Delete);
+    const putOp = transactItems.find((t) => t.Put && t.Put.Item?.[DEFAULT_SCHEMA.emailItemUserAttribute]);
+    assert.ok(deleteOp?.Delete?.Key?.pk?.includes('old@b.com'));
+    assert.ok(putOp?.Put?.Item?.pk?.includes('new@b.com'));
+    assert.strictEqual(putOp.Put.Item[DEFAULT_SCHEMA.emailItemUserAttribute], 'user-1');
+  });
+
+  it('throws User with this email already exists when transaction fails during email change', async () => {
+    const doc = createMockDocClient([{ Item: currentUser }, Object.assign(new Error(), { name: 'TransactionCanceledException' })]);
+    await assert.rejects(() => updateUser('user-1', { email: 'taken@b.com' }, { ...baseOptions, documentClient: doc, modifiedBy: 'u', modifiedReason: 'r' }), /User with this email already exists/);
+  });
+});
+
+describe('DEFAULT_SCHEMA', () => {
+  it('has expected keys', () => {
+    assert.strictEqual(DEFAULT_SCHEMA.userItemPK, 'pk');
+    assert.strictEqual(DEFAULT_SCHEMA.userItemSK, 'sk');
+    assert.strictEqual(DEFAULT_SCHEMA.userItemPrefix, 'U#');
+    assert.strictEqual(DEFAULT_SCHEMA.userItemLookupPrefix, 'email#');
+    assert.strictEqual(DEFAULT_SCHEMA.defaultLookupList, 'USER#ACTIVE');
+    assert.strictEqual(DEFAULT_SCHEMA.emailItemPrefix, 'EMAIL#');
+    assert.strictEqual(DEFAULT_SCHEMA.emailItemUserAttribute, 'userId');
+    assert.ok(Array.isArray(DEFAULT_SCHEMA.purgeVersionAttributes));
+  });
+});

package/src/index.js

@@ -0,0 +1,416 @@
+/**
+ * Helpers for managing users in DynamoDB.
+ *
+ * @schema (DEFAULT_SCHEMA)
+ * - User item: pk=U#<uuid>, sk=A, pk1=email#<normalized>, sk1=A. Get by id: GetItem(pk, sk). Get by email: query lookup index.
+ * - Email item: pk=EMAIL#<email>, sk=A, userId. Fallback for by-email when index is eventually consistent.
+ * - Optional LOOKUP item (when createLookupItem/updateLookupItem): pk=U#<id>, sk=LOOKUP, pk1/sk1 for lookup list index. Out-of-the-box default is defaultLookupList (e.g. USER#ACTIVE); override via options.lookupList. sk1 is always normalized name (enables begins_with search via listUsers beginsWith). Default projection: defaultLookupAttributes (email, name, picture); extend via lookupExtraAttributes. listUsers({ lookupList }) queries this index; optional beginsWith, limit, exclusiveStartKey, scanIndexForward.
+ */
+
+const { randomUUID } = require('node:crypto');
+const { GetCommand, QueryCommand, TransactWriteCommand } = require('@aws-sdk/lib-dynamodb');
+
+const DEFAULT_SCHEMA = {
+  userItemPK: 'pk',
+  userItemSK: 'sk',
+  userItemPrefix: 'U#',
+  userItemLookupPrefix: 'email#',
+  userItemSKValue: 'A',
+  userItemLookupSKValue: 'A',
+  userItemVersionPrefix: 'v#',
+  lookupIndex: 'gsi1',
+  lookupIndexPK: 'pk1',
+  lookupIndexSK: 'sk1',
+  lookupItemSK: 'LOOKUP',
+  lookupItemType: 'user_lookup',
+  defaultLookupList: 'USER#ACTIVE',
+  defaultLookupAttributes: ['email', 'name', 'picture'],
+  emailItemPrefix: 'EMAIL#',
+  emailItemSKValue: 'A',
+  emailItemUserAttribute: 'userId',
+  userItemType: 'user',
+  userItemVersionType: 'user_version',
+  emailItemType: 'email',
+  purgeVersionAttributes: ['pk1', 'sk1', 'pk2', 'sk2', 'pk3', 'sk3']
+};
+
+function getSchema(options) {
+  return { ...DEFAULT_SCHEMA, ...(options?.schema) };
+}
+
+function normalizeString(text) {
+  return String(text).toLowerCase().trim();
+}
+
+function stripUserPrefix(pk, prefix) {
+  return pk && typeof pk === 'string' && pk.startsWith(prefix) ? pk.slice(prefix.length) : pk;
+}
+
+/**
+ * Build LOOKUP item for list queries on GSI1. Shallow projection from user record plus list keys.
+ * @param {object} schema - Resolved schema (getSchema(options)).
+ * @param {object} userRecord - User A record (or merged) to project from.
+ * @param {string} lookupList - Lookup list key for GSI1 partition (e.g. USER#ACTIVE).
+ * @param {string} sk1Value - GSI1 sort key value (normalized name, computed by caller).
+ * @param {string[]} [extraLookupAttributes] - Additional attribute names to copy from userRecord onto LOOKUP.
+ * @returns {object} Item suitable for Put (same table).
+ */
+function buildLookupItem(schema, userRecord, lookupList, sk1Value, extraLookupAttributes = []) {
+  const pk = userRecord[schema.userItemPK];
+  const userId = stripUserPrefix(pk, schema.userItemPrefix);
+  const defaultAttrs = Array.isArray(schema.defaultLookupAttributes) ? schema.defaultLookupAttributes : ['email', 'name', 'picture'];
+  const extraAttrs = Array.isArray(extraLookupAttributes) ? extraLookupAttributes : [];
+  const attrs = [...new Set([...defaultAttrs, ...extraAttrs])];
+
+  const item = {
+    [schema.userItemPK]: pk,
+    [schema.userItemSK]: schema.lookupItemSK,
+    type: schema.lookupItemType,
+    [schema.lookupIndexPK]: lookupList,
+    [schema.lookupIndexSK]: sk1Value,
+    [schema.emailItemUserAttribute]: userId
+  };
+  for (const key of attrs) {
+    if (userRecord[key] !== undefined) item[key] = userRecord[key];
+  }
+  return item;
+}
+
+/**
+ * Get user by ID. Access pattern: GetItem on base table.
+ *
+ * @param {string} userId - User ID (with or without prefix).
+ * @param {object} options - documentClient, tableName (required); schema (optional, overrides defaults).
+ * @returns {Promise<object|null>} User item or null if not found.
+ */
+async function getUser(userId, options) {
+  if (!userId) return null;
+  const userIdStr = String(userId);
+
+  const { documentClient, tableName } = options ?? {};
+  if (!documentClient || !tableName) throw new Error('getUser requires options.documentClient and options.tableName');
+
+  const schema = getSchema(options);
+  const prefix = schema.userItemPrefix;
+  const pk = userIdStr.startsWith(prefix) ? userIdStr : `${prefix}${userIdStr}`;
+
+  const result = await documentClient.send(
+    new GetCommand({
+      TableName: tableName,
+      Key: { [schema.userItemPK]: pk, [schema.userItemSK]: schema.userItemSKValue }
+    })
+  );
+  if (!result.Item) return null;
+  return result.Item;
+}
+
+/**
+ * Get user by email. Tries lookup index first; on empty, falls back to EMAIL sentinel + getUser.
+ *
+ * @param {string} email - User email (normalized internally).
+ * @param {object} options - documentClient, tableName (required); schema (optional; schema.lookupIndex required for by-email lookup); normalizeEmailFn (optional).
+ * @returns {Promise<object|null>} User item or null if not found.
+ */
+async function getUserByEmail(email, options) {
+  
+  if (!email) return null;  
+  
+  const { documentClient, tableName, normalizeEmailFn } = options ?? {};    
+  if (!documentClient || !tableName) throw new Error('getUserByEmail requires options.documentClient and options.tableName');
+  
+  const schema = getSchema(options);
+  if (!schema.lookupIndex) throw new Error('getUserByEmail requires schema.lookupIndex');
+
+  const normalize = normalizeEmailFn ?? normalizeString;
+  
+  const normalized = normalize(email);
+  const pk1Val = `${schema.userItemLookupPrefix}${normalized}`;
+  const sk1Val = schema.userItemLookupSKValue;
+
+  // Try lookup index first.
+  const gsiResult = await documentClient.send(
+    new QueryCommand({
+      TableName: tableName,
+      IndexName: schema.lookupIndex,
+      KeyConditionExpression: '#pk1 = :pk1 AND #sk1 = :sk1',
+      ExpressionAttributeNames: { '#pk1': schema.lookupIndexPK, '#sk1': schema.lookupIndexSK },
+      ExpressionAttributeValues: { ':pk1': pk1Val, ':sk1': sk1Val }
+    })
+  );
+
+  if (gsiResult.Items?.length) {
+    return gsiResult.Items[0];
+  }
+
+  // Fallback to email item.
+  const emailPk = `${schema.emailItemPrefix}${normalized}`;
+  const emailResult = await documentClient.send(
+    new GetCommand({
+      TableName: tableName,
+      Key: { [schema.userItemPK]: emailPk, [schema.userItemSK]: schema.emailItemSKValue }
+    })
+  );
+  const userId = emailResult.Item?.[schema.emailItemUserAttribute];
+  if (!userId) return null;
+  return getUser(userId, options);
+}
+
+/**
+ * List users by querying the LOOKUP index (GSI1 by default). Uses pk1/sk1 from schema.
+ *
+ * @param {object} options - documentClient, tableName, lookupList (required; e.g. 'USER#ACTIVE'); beginsWith (optional; begins_with on sk1, e.g. normalized name prefix), limit, exclusiveStartKey, scanIndexForward; schema (optional).
+ * @returns {Promise<{ items: object[], lastEvaluatedKey: object|null }>}
+ */
+async function listUsers(options = {}) {
+  const { documentClient, tableName, lookupList, beginsWith, limit = 50, exclusiveStartKey, scanIndexForward } = options;
+  if (!documentClient || !tableName) throw new Error('listUsers requires options.documentClient and options.tableName');
+  if (lookupList == null || lookupList === '') throw new Error('listUsers requires options.lookupList');
+  const schema = getSchema(options);
+  if (!schema.lookupIndex) throw new Error('listUsers requires schema.lookupIndex');
+
+  const cap = Math.min(Math.max(1, limit), 100);
+  let keyConditionExpression = `#pk1 = :pk1`;
+  const expressionAttributeNames = { '#pk1': schema.lookupIndexPK };
+  const expressionAttributeValues = { ':pk1': lookupList };
+
+  if (beginsWith != null && String(beginsWith).trim() !== '') {
+    keyConditionExpression += ' AND begins_with(#sk1, :beginsWith)';
+    expressionAttributeNames['#sk1'] = schema.lookupIndexSK;
+    expressionAttributeValues[':beginsWith'] = String(beginsWith).trim();
+  }
+
+  const result = await documentClient.send(
+    new QueryCommand({
+      TableName: tableName,
+      IndexName: schema.lookupIndex,
+      KeyConditionExpression: keyConditionExpression,
+      ExpressionAttributeNames: expressionAttributeNames,
+      ExpressionAttributeValues: expressionAttributeValues,
+      Limit: cap,
+      ...(exclusiveStartKey != null && { ExclusiveStartKey: exclusiveStartKey }),
+      ...(typeof scanIndexForward === 'boolean' && { ScanIndexForward: scanIndexForward })
+    })
+  );
+
+  return {
+    items: result.Items ?? [],
+    lastEvaluatedKey: result.LastEvaluatedKey ?? null
+  };
+}
+
+/**
+ * Create user atomically: A record and EMAIL sentinel. Optionally a LOOKUP item on GSI1 (when createLookupItem and list keys provided). Optionally add more items via options.extraTransactItems.
+ *
+ * @param {object} input - At least email, name (required). Other keys are spread onto the user A record (e.g. role, picture, scope, status).
+ * @param {object} options - documentClient, tableName (required); createLookupItem (default true), lookupList (optional), lookupExtraAttributes, extraTransactItems, normalizeEmailFn, schema (optional). When createLookupItem is true, the lookup list defaults to schema.defaultLookupList (e.g. USER#ACTIVE) unless options.lookupList is a non-empty string. LOOKUP sk1 is always the normalized name.
+ * @returns {Promise<object>} Created user A record shape. Throws on duplicate email.
+ */
+async function createUser(input, options = {}) {
+  const { documentClient, tableName, extraTransactItems, normalizeEmailFn, createLookupItem = true, lookupList, lookupExtraAttributes } = options;
+  if (!documentClient || !tableName) throw new Error('createUser requires options.documentClient and options.tableName');
+  const schema = getSchema(options);
+
+  const { email, name, ...rest } = input;
+  if (!email || !String(email).trim()) throw new Error('Email is required');
+  if (!name || !String(name).trim()) throw new Error('Name is required');
+
+  const normalize = normalizeEmailFn ?? normalizeString;
+  const userId = randomUUID();
+  const normalizedEmail = normalize(email);
+  const trimmedName = String(name).trim();
+  const now = new Date().toISOString();
+
+  const userA = {
+    [schema.userItemPK]: `${schema.userItemPrefix}${userId}`,
+    [schema.userItemSK]: schema.userItemSKValue,
+    type: schema.userItemType,
+    [schema.lookupIndexPK]: `${schema.userItemLookupPrefix}${normalizedEmail}`,
+    [schema.lookupIndexSK]: schema.userItemLookupSKValue,
+    name: trimmedName,
+    email: normalizedEmail,
+    createdAt: now,
+    modifiedAt: now,
+    modifiedBy: rest.modifiedBy ?? 'system',
+    modifiedReason: rest.modifiedReason ?? 'create',
+    ...rest
+  };
+
+  const emailItem = {
+    [schema.userItemPK]: `${schema.emailItemPrefix}${normalizedEmail}`,
+    [schema.userItemSK]: schema.emailItemSKValue,
+    type: schema.emailItemType,
+    [schema.emailItemUserAttribute]: userId
+  };
+
+  const transactItems = [
+    { Put: { TableName: tableName, Item: userA } },
+    {
+      Put: {
+        TableName: tableName,
+        Item: emailItem,
+        ConditionExpression: `attribute_not_exists(#pk)`,
+        ExpressionAttributeNames: { '#pk': schema.userItemPK }
+      }
+    }
+  ];
+
+  if (createLookupItem !== false && schema.lookupIndex) {
+    const listKey = (typeof lookupList === 'string' && lookupList.trim() !== '') ? lookupList.trim() : (schema.defaultLookupList ?? 'USER#ACTIVE');
+    const sk1 = normalizeString(trimmedName);
+    const lookupItem = buildLookupItem(schema, userA, listKey, sk1, lookupExtraAttributes);
+    transactItems.push({ Put: { TableName: tableName, Item: lookupItem } });
+  }
+  if (Array.isArray(extraTransactItems) && extraTransactItems.length) transactItems.push(...extraTransactItems);
+
+  try {
+    await documentClient.send(new TransactWriteCommand({ TransactItems: transactItems }));
+  } catch (err) {
+    if (err.name === 'TransactionCanceledException') {
+      throw new Error('User with this email already exists');
+    }
+    throw err;
+  }
+  return userA;
+}
+
+/**
+ * Update user: put version record (v#), update A record, then any options.extraTransactItems (e.g. LOOKUP, BALANCE).
+ *
+ * @param {string} userId - User ID (with or without prefix).
+ * @param {object} updates - Fields to update. If options.allowedUpdateFields is omitted, all keys in updates are applied.
+ * @param {object} options - documentClient, tableName, modifiedBy, modifiedReason (required); createVersionRecord, extraTransactItems, allowedUpdateFields, updateLookupItem (default true), lookupList (optional), lookupExtraAttributes, schema (optional). LOOKUP sk1 is always the normalized name.
+ * @returns {Promise<object>} Updated user A record shape. Throws if user not found, or if email is changed to one that already exists (sentinel).
+ */
+async function updateUser(userId, updates, options = {}) {
+  const { documentClient, tableName, modifiedBy, modifiedReason, createVersionRecord = true, extraTransactItems, allowedUpdateFields, updateLookupItem = true, lookupList, lookupExtraAttributes } = options;
+  if (!documentClient || !tableName) throw new Error('updateUser requires options.documentClient and options.tableName');
+  if (modifiedBy == null || modifiedReason == null) {
+    throw new Error('updateUser requires options.modifiedBy and options.modifiedReason');
+  }
+  const schema = getSchema(options);
+
+  const currentUser = await getUser(userId, options);
+  if (!currentUser) throw new Error('User not found');
+
+  const allowed = Array.isArray(allowedUpdateFields) ? allowedUpdateFields : Object.keys(updates || {});
+  const updatedUser = { ...currentUser };
+  for (const key of allowed) {
+    if (updates[key] !== undefined) updatedUser[key] = updates[key];
+  }
+
+  const timestamp = new Date().toISOString();
+  updatedUser.modifiedAt = timestamp;
+  updatedUser.modifiedBy = modifiedBy;
+  updatedUser.modifiedReason = modifiedReason;
+
+  const normalize = options.normalizeEmailFn ?? normalizeString;
+  const emailAllowed = !Array.isArray(allowedUpdateFields) || allowedUpdateFields.includes('email');
+  const normalizedCurrent = normalize(currentUser.email ?? '');
+  const normalizedNew = normalize(updatedUser.email ?? '');
+  const isEmailChange = emailAllowed && normalizedNew !== '' && normalizedNew !== normalizedCurrent;
+
+  const emailChange = isEmailChange
+    ? {
+        normalizedOld: normalizedCurrent,
+        normalizedNew,
+        userIdRaw: stripUserPrefix(currentUser[schema.userItemPK], schema.userItemPrefix)
+      }
+    : null;
+
+  const pkValue = currentUser[schema.userItemPK];
+  const vRecord = { ...currentUser, [schema.userItemSK]: `${schema.userItemVersionPrefix}${timestamp}`, type: schema.userItemVersionType };
+  const purgeAttrs = schema.purgeVersionAttributes;
+  if (Array.isArray(purgeAttrs)) {
+    for (const attr of purgeAttrs) {
+      delete vRecord[attr];
+    }
+  }
+
+  const names = {};
+  const values = {};
+  const setParts = [];
+  names['#modifiedAt'] = 'modifiedAt';
+  values[':modifiedAt'] = timestamp;
+  names['#modifiedBy'] = 'modifiedBy';
+  values[':modifiedBy'] = modifiedBy;
+  names['#modifiedReason'] = 'modifiedReason';
+  values[':modifiedReason'] = modifiedReason;
+  setParts.push('#modifiedAt = :modifiedAt', '#modifiedBy = :modifiedBy', '#modifiedReason = :modifiedReason');
+
+  for (const key of allowed) {
+    if (updates[key] === undefined) continue;
+    names[`#${key}`] = key;
+    values[`:${key}`] = updatedUser[key];
+    setParts.push(`#${key} = :${key}`);
+  }
+
+  if (emailChange) {
+    names[`#${schema.lookupIndexPK}`] = schema.lookupIndexPK;
+    names[`#${schema.lookupIndexSK}`] = schema.lookupIndexSK;
+    values[':pk1'] = `${schema.userItemLookupPrefix}${emailChange.normalizedNew}`;
+    values[':sk1'] = schema.userItemLookupSKValue;
+    setParts.push(`#${schema.lookupIndexPK} = :pk1`, `#${schema.lookupIndexSK} = :sk1`);
+  }
+
+  const updateA = {
+    TableName: tableName,
+    Key: { [schema.userItemPK]: pkValue, [schema.userItemSK]: schema.userItemSKValue },
+    UpdateExpression: `SET ${setParts.join(', ')}`,
+    ExpressionAttributeNames: names,
+    ExpressionAttributeValues: values
+  };
+
+  const transactItems = [{ Update: updateA }];
+  if (createVersionRecord) transactItems.unshift({ Put: { TableName: tableName, Item: vRecord } });
+  if (emailChange) {
+    transactItems.push(
+      {
+        Delete: {
+          TableName: tableName,
+          Key: { [schema.userItemPK]: `${schema.emailItemPrefix}${emailChange.normalizedOld}`, [schema.userItemSK]: schema.emailItemSKValue }
+        }
+      },
+      {
+        Put: {
+          TableName: tableName,
+          Item: {
+            [schema.userItemPK]: `${schema.emailItemPrefix}${emailChange.normalizedNew}`,
+            [schema.userItemSK]: schema.emailItemSKValue,
+            type: schema.emailItemType,
+            [schema.emailItemUserAttribute]: emailChange.userIdRaw
+          },
+          ConditionExpression: 'attribute_not_exists(#pk)',
+          ExpressionAttributeNames: { '#pk': schema.userItemPK }
+        }
+      }
+    );
+  }
+  if (updateLookupItem !== false && schema.lookupIndex) {
+    const listKey = (typeof lookupList === 'string' && lookupList.trim() !== '') ? lookupList.trim() : (schema.defaultLookupList ?? 'USER#ACTIVE');
+    const sk1 = normalizeString(String(updatedUser.name ?? '').trim());
+    const lookupItem = buildLookupItem(schema, updatedUser, listKey, sk1, lookupExtraAttributes);
+    transactItems.push({ Put: { TableName: tableName, Item: lookupItem } });
+  }
+  if (Array.isArray(extraTransactItems) && extraTransactItems.length) {
+    transactItems.push(...extraTransactItems);
+  }
+
+  try {
+    await documentClient.send(new TransactWriteCommand({ TransactItems: transactItems }));
+  } catch (err) {
+    if (err.name === 'TransactionCanceledException') {
+      throw new Error(emailChange ? 'User with this email already exists' : 'User update transaction failed');
+    }
+    throw err;
+  }
+  return { ...updatedUser };
+}
+
+module.exports = {
+  DEFAULT_SCHEMA,
+  getUser,
+  getUserByEmail,
+  listUsers,
+  createUser,
+  updateUser
+};