EntityClient: CRUD and Batches

Token-aware reads and convenient batches with strong types.

Token-aware getItem/getItems

// Record shape narrowed by the literal entity token
const rec = await client.getItem('user', { hashKey2: 'h', rangeKey: 'r' });
const item = rec.Item && client.entityManager.removeKeys('user', rec.Item);

// Project selected attributes (tuple preserves types)
const recProj = await client.getItem('user', { hashKey2: 'h', rangeKey: 'r' }, [
  'a',
] as const);

// Batch get
const many = await client.getItems('user', [
  { hashKey2: 'h', rangeKey: 'r1' },
  { hashKey2: 'h', rangeKey: 'r2' },
]);
const domain = client.entityManager.removeKeys('user', many.items);
Copy

Basic CRUD (records)

// Put a storage record (keys included)
await client.putItem({ hashKey2: 'h', rangeKey: 'r', a: 1 });

// Delete a record
await client.deleteItem({ hashKey2: 'h', rangeKey: 'r' });
Copy

Batched writes

// putItems
await client.putItems([
  { hashKey2: 'h', rangeKey: '1' },
  { hashKey2: 'h', rangeKey: '2' },
]);

// deleteItems
await client.deleteItems([
  { hashKey2: 'h', rangeKey: '1' },
  { hashKey2: 'h', rangeKey: '2' },
]);
Copy

Purge (scan + batched deletes)

const purged = await client.purgeItems();
Copy

Transactions

await client.transactPutItems([
  { hashKey2: 'h', rangeKey: '10', x: 1 },
  { hashKey2: 'h', rangeKey: '11', x: 2 },
]);

await client.transactDeleteItems([
  { hashKey2: 'h', rangeKey: '10' },
  { hashKey2: 'h', rangeKey: '11' },
]);
Copy

Notes

• Token in → narrowed type out. Pass a literal entity token to narrow record types automatically.
• Domain vs storage: when you want domain shapes, strip keys via entityManager.removeKeys(entityToken, records).
• Projection tuples (const) narrow shapes at the call site for token-aware reads.

Related

• Querying with QueryBuilder
• Type inference mental model