@wszerad/items 0.1.1 → 0.2.0

package/README.md

@@ -1,20 +1,18 @@
-# items
+# @wszerad/items
 
-Lightweight, immutable collection manager inspired by NgRx Entity Adapter.
+An immutable collection library for managing entities with built-in selection, filtering, and diffing capabilities.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![npm version](https://badge.fury.io/js/@wszerad%2Fitems.svg)](https://badge.fury.io/js/@wszerad%2Fitems)
 
 ## Features
 
-- ✅ Immutable operations (insert/insertMany, upsert/upsertMany, set/setMany, update, remove/removeMany, filter, etc.)
-- ✅ Single entity and batch operations
-- ✅ Custom ID selection (`selectId`)
-- ✅ Optional sorting (`sortComparer`)
-- ✅ TypeScript-first with full type safety
-- ✅ Zero dependencies
-- ✅ Tree-shakeable ESM build
-- ✅ Flexible selectors (ID, array of IDs, or predicate function)
-- ✅ Built-in pagination support
-- ✅ Diff detection between collections
-- ✅ `every()` and `some()` collection validators
+- 🔒 **Immutable**: All operations return new instances without mutating the original
+- 🎯 **Type-safe**: Full TypeScript support with generic types
+- 🔍 **Powerful Selection**: Query and filter items with a fluent API
+- 📊 **Diff Tracking**: Compare collections and track changes
+- ⚡ **Performance**: Efficient internal storage using Maps
+- 🎨 **Flexible**: Custom ID selectors and sorting comparers
 
 ## Installation
 
@@ -25,7 +23,7 @@ npm install @wszerad/items
 ## Quick Start
 
 ```typescript
-import { Items } from 'items'
+import { Items } from '@wszerad/items'
 
 interface User {
   id: number
@@ -33,734 +31,566 @@ interface User {
   age: number
 }
 
-// Create collection
-const items = new Items<number, User>()
-
-// Add single entity
-const withUser = items.insert({ id: 1, name: 'Alice', age: 25 })
+// Create a collection
+const users = new Items<User>([
+  { id: 1, name: 'Alice', age: 30 },
+  { id: 2, name: 'Bob', age: 25 },
+  { id: 3, name: 'Charlie', age: 35 }
+])
 
-// Add multiple entities (batch operation)
-const withUsers = items.insertMany([
-  { id: 1, name: 'Alice', age: 25 },
-  { id: 2, name: 'Bob', age: 30 }
+// Add items
+const updated = users.add([
+  { id: 4, name: 'David', age: 40 }
 ])
 
-// Query
-console.log(withUsers.getIds()) // [1, 2]
-console.log(withUsers.select(1)) // { id: 1, name: 'Alice', age: 25 }
-console.log(withUsers.length) // 2
+// Update items
+const older = users.update([1, 2], (user) => ({
+  ...user!,
+  age: user!.age + 1
+}))
+
+// Select and filter - returns array
+const adults = users.select((s) => 
+  s.filter((user) => user.age >= 30)
+    .sort((a, b) => a.age - b.age)
+)
+console.log(adults) // [{ id: 1, name: 'Alice', age: 30 }, { id: 3, name: 'Charlie', age: 35 }]
 
-// Update
-const updated = withUsers.update(1, { age: 26 })
+// Select single item using at() - returns single item or undefined
+const oldestUser = users.select((s) => 
+  s.sort((a, b) => b.age - a.age).at(0)
+)
+console.log(oldestUser) // { id: 3, name: 'Charlie', age: 35 }
 
-// Remove
-const removed = updated.remove(1)
+// Get IDs instead of items
+const adultIds = users.selectId((s) => 
+  s.filter((user) => user.age >= 30)
+)
+console.log(adultIds) // [1, 3]
 ```
 
 ## API Reference
 
-### Constructor
-
-#### `new Items<I, E>(items?, options?)`
+### Items Class
 
-Creates an `Items` instance with optional initial items and options.
+#### Constructor
 
 ```typescript
-// Empty collection
-const items = new Items<number, User>()
+new Items<E>(items?: Iterable<E>, options?: ItemsOptions<E>)
+```
 
-// With initial items
-const items = new Items<number, User>([
-  { id: 1, name: 'Alice' },
-  { id: 2, name: 'Bob' }
-])
+**Options:**
+- `selectId?: (entity: E) => ItemId` - Custom ID selector (defaults to `entity.id`)
+- `sortComparer?: false | ((a: E, b: E) => number)` - Sorting comparator for maintaining order
 
-// With options
-const items = new Items<number, User>([], {
-  selectId: (user) => user.id,           // default: entity.id
-  sortComparer: (a, b) => a.name.localeCompare(b.name) // default: false
+**Example:**
+```typescript
+const items = new Items(users, {
+  selectId: (user) => user.userId,
+  sortComparer: (a, b) => a.name.localeCompare(b.name)
 })
 ```
 
-### Properties
+#### Methods
+
+##### `add(items: Iterable<E>): Items<E>`
 
-- **`length`** – Number of entities in the collection
+Adds new items to the collection. Items with existing IDs are ignored.
 
 ```typescript
-items.length // 2
+const updated = users.add([
+  { id: 4, name: 'David', age: 40 }
+])
 ```
 
-### Methods
+##### `update(selector: Selector<E>, updater: Updater<E>): Items<E>`
 
-#### Insert Operations
-
-- **`insert(entity)`** – Adds a single entity (skips if already exists)
-- **`insertMany(entities)`** – Adds multiple entities (skips duplicates). Accepts an `Iterable<E>` (array, Set, etc.)
+Updates selected items with partial data or a function. Can create new items if using a function updater.
 
 ```typescript
-// Insert single entity
-items.insert({ id: 1, name: 'Alice' })
+// Update with partial data
+const updated = users.update(1, { age: 31 })
+
+// Update with function
+const updated = users.update([1, 2], (user) => ({
+  ...user!,
+  age: user!.age + 1
+}))
+
+// Update with selector function
+const updated = users.update(
+  (s) => s.filter((u) => u.age > 25),
+  { active: true }
+)
+```
 
-// Insert multiple entities
-items.insertMany([
-  { id: 1, name: 'Alice' },
-  { id: 2, name: 'Bob' }
-])
+##### `merge(items: Iterable<E>): Items<E>`
 
-// Insert from Set
-const usersSet = new Set([
-  { id: 1, name: 'Alice' },
-  { id: 2, name: 'Bob' }
-])
-items.insertMany(usersSet)
+Merges items into the collection. Adds new items and overwrites existing ones.
 
-// Skips duplicates - won't replace existing entity with id: 1
-items.insert({ id: 1, name: 'Alice Updated' }) // Original stays
+```typescript
+const merged = users.merge([
+  { id: 1, name: 'Alice', age: 31 }, // Updates existing
+  { id: 5, name: 'Eve', age: 28 }     // Adds new
+])
 ```
 
-#### Upsert Operations
-
-- **`upsert(entity)`** – Adds or **merges** a single entity (extends existing properties)
-- **`upsertMany(entities)`** – Adds or **merges** multiple entities. Accepts an `Iterable<E>` (array, Set, etc.)
+##### `remove(selector: Selector<E>): Items<E>`
 
-**Note:** `upsert` merges/extends properties with existing entities, similar to `Object.assign()` or spread operator behavior.
+Removes selected items from the collection.
 
 ```typescript
-// Upsert single entity
-items.upsert({ id: 1, name: 'Alice' })
+// Remove by ID
+const removed = users.remove(1)
 
-// Upsert existing entity - MERGES properties
-const items = new Items([{ id: 1, name: 'Alice', age: 25 }])
-const updated = items.upsert({ id: 1, name: 'Alice Updated' })
-// Result: { id: 1, name: 'Alice Updated', age: 25 }
-// Note: age is preserved!
+// Remove by IDs
+const removed = users.remove([1, 2])
 
-// Upsert multiple entities
-items.upsertMany([
-  { id: 1, name: 'Alice' },
-  { id: 2, name: 'Bob' }
-])
-
-// Adding new properties
-const items = new Items([{ id: 1, name: 'Alice' }])
-const updated = items.upsert({ id: 1, age: 25 })
-// Result: { id: 1, name: 'Alice', age: 25 }
-// Note: name is preserved, age is added
+// Remove by function
+const removed = users.remove((s) => s.filter((u) => u.age < 30))
 ```
 
-#### Set Operations
-
-- **`set(entity)`** – Adds or **completely replaces** a single entity
-- **`setMany(entities)`** – Adds or **completely replaces** multiple entities. Accepts an `Iterable<E>` (array, Set, etc.)
+##### `pick(selector: Selector<E>): Items<E>`
 
-**Note:** `set` completely replaces existing entities, removing any properties not in the new entity.
+Returns a new Items instance containing only the selected items.
 
 ```typescript
-// Set single entity
-items.set({ id: 1, name: 'Alice' })
-
-// Set existing entity - REPLACES completely
-const items = new Items([{ id: 1, name: 'Alice', age: 25 }])
-const updated = items.set({ id: 1, name: 'Alice Updated' })
-// Result: { id: 1, name: 'Alice Updated' }
-// Note: age is removed!
-
-// Set multiple entities
-items.setMany([
-  { id: 1, name: 'Alice' },
-  { id: 2, name: 'Bob' }
-])
+const picked = users.pick((s) => s.filter((u) => u.age >= 30))
 ```
 
-#### Update Operations
-
-- **`update(id, updater)`** – Updates a single entity by ID
-- **`updateMany(selector, updater)`** – Updates multiple entities matching selector
+##### `select(selector: Selector<E>): E[] | E | undefined`
 
-The updater can be a partial object or a function that returns the updated entity.
+Selects items and returns them. Returns an array for multiple selections, or a single item (or undefined) when using SingleSelect methods like `at()` or `on()`.
 
 ```typescript
-// Update single entity by ID with partial
-items.update(1, { age: 26 })
+// Select by ID - returns single item or undefined
+const user = items.select(1)
 
-// Update single entity by ID with function
-items.update(1, user => ({ ...user, age: user.age + 1 }))
+// Select by IDs - returns array
+const users = items.select([1, 2])
 
-// Update multiple entities by IDs
-items.updateMany([1, 2], { age: 26 })
+// Select with function returning Select - returns array
+const adults = items.select((s) => s.filter((u) => u.age >= 30))
 
-// Update multiple entities by predicate
-items.updateMany(
-  user => user.age < 30,
-  { age: 26 }
-)
+// Select with function returning SingleSelect - returns single item or undefined
+const firstUser = items.select((s) => s.at(0))
+const oldest = items.select((s) => s.sort((a, b) => b.age - a.age).at(0))
 ```
 
-#### Remove Operations
+##### `selectId(selector: Selector<E>): ItemId[] | ItemId | undefined`
 
-- **`remove(id)`** – Removes a single entity by ID
-- **`removeMany(selector)`** – Removes multiple entities matching selector
+Selects item IDs instead of items. Returns an array of IDs for multiple selections, or a single ID (or undefined) when using SingleSelect methods.
 
 ```typescript
-// Remove single entity by ID
-items.remove(1)
+// Get IDs for filtered items - returns array
+const adultIds = items.selectId((s) => s.filter((u) => u.age >= 30))
 
-// Remove multiple entities by IDs
-items.removeMany([1, 2])
+// Get ID of first item - returns ItemId or undefined
+const firstId = items.selectId((s) => s.at(0))
 
-// Remove multiple entities by predicate
-items.removeMany(user => user.age < 30)
+// Get ID of oldest user - returns ItemId or undefined
+const oldestId = items.selectId((s) => s.sort((a, b) => b.age - a.age).at(0))
 ```
 
-- **`clear()`** – Removes all entities
+##### `extractId(entity: E): ItemId`
+
+Extracts the ID from an entity using the configured ID selector.
 
 ```typescript
-items.clear()
+const user = { id: 5, name: 'Eve', age: 28 }
+const id = items.extractId(user) // Returns: 5
+
+// With custom selector
+const products = new Items(items, { 
+  selectId: (p) => p.sku 
+})
+const product = { sku: 'ABC123', name: 'Widget' }
+const sku = products.extractId(product) // Returns: 'ABC123'
 ```
 
-#### Filter Operations
+##### `clear(): Items<E>`
 
-- **`filter(selector)`** – Returns new collection with only matching entities
+Returns an empty Items instance with the same options.
 
 ```typescript
-// Filter by ID
-items.filter(1)
-
-// Filter by multiple IDs
-items.filter([1, 2])
-
-// Filter by predicate
-items.filter(user => user.age >= 30)
+const empty = users.clear()
 ```
 
-#### Selectors
+##### `every(check: (entity: E) => boolean): boolean`
 
-- **`getIds()`** – Returns array of IDs
-- **`getEntities()`** – Returns Map of entities
-- **`select(id)`** – Returns entity by ID or `undefined`
+Tests whether all items pass the provided function.
 
 ```typescript
-items.getIds() // [1, 2]
-items.getEntities() // Map { 1 => {...}, 2 => {...} }
-items.select(1) // { id: 1, name: 'Alice' }
+const allAdults = users.every((u) => u.age >= 18)
 ```
 
-#### Has/Check Operations
+##### `some(check: (entity: E) => boolean): boolean`
 
-- **`has(id)`** – Checks if a single entity exists by ID
-- **`hasMany(selector)`** – Checks if entities exist matching selector
+Tests whether at least one item passes the provided function.
 
 ```typescript
-// Check single entity by ID
-items.has(1) // true
-items.has(99) // false
+const hasSenior = users.some((u) => u.age >= 65)
+```
 
-// Check multiple IDs (returns true only if ALL exist)
-items.hasMany([1, 2]) // true
-items.hasMany([1, 99]) // false
+##### `has(id: ItemId): boolean`
 
-// Check by predicate (returns true if ANY matches)
-items.hasMany(user => user.age >= 30) // true
-items.hasMany(user => user.age >= 100) // false
+Checks if an item with the given ID exists.
 
-// Check single ID using array
-items.hasMany([1]) // true
+```typescript
+const exists = users.has(1)
 ```
 
-- **`every(predicate)`** – Returns `true` if ALL entities match the predicate
+##### `get(id: ItemId): E | undefined`
+
+Gets an item by ID.
 
 ```typescript
-const items = new Items<number, User>([
-  { id: 1, name: 'Alice', age: 25 },
-  { id: 2, name: 'Bob', age: 30 },
-  { id: 3, name: 'Charlie', age: 35 }
-])
+const user = users.get(1)
+```
 
-// Check if all users are adults
-items.every(user => user.age >= 18) // true
+##### `getIds(): ItemId[]`
 
-// Check if all users are seniors
-items.every(user => user.age >= 65) // false
+Returns an array of all item IDs.
 
-// Returns true for empty collection
-new Items<number, User>().every(user => false) // true
+```typescript
+const ids = users.getIds() // [1, 2, 3]
 ```
 
-- **`some(predicate)`** – Returns `true` if AT LEAST ONE entity matches the predicate
+##### `getEntities(): E[]`
+
+Returns an array of all items.
 
 ```typescript
-const items = new Items<number, User>([
-  { id: 1, name: 'Alice', age: 25 },
-  { id: 2, name: 'Bob', age: 30 },
-  { id: 3, name: 'Charlie', age: 35 }
-])
+const allUsers = users.getEntities()
+```
 
-// Check if any user is under 30
-items.some(user => user.age < 30) // true
+##### `length: number`
 
-// Check if any user is named 'Dave'
-items.some(user => user.name === 'Dave') // false
+Gets the number of items in the collection.
 
-// Returns false for empty collection
-new Items<number, User>().some(user => true) // false
+```typescript
+console.log(users.length) // 3
 ```
 
-#### Pagination
 
-- **`page(pageNumber, pageSize)`** – Returns paginated results
+#### Static Methods
+
+##### `Items.compare<E>(base: Items<E>, to: Items<E>): ItemsDiff`
+
+Compares two Items instances and returns the differences.
 
 ```typescript
-const result = items.page(0, 10)
+const before = new Items(users)
+const after = before.update(1, { age: 31 })
+
+const diff = Items.compare(before, after)
+console.log(diff)
 // {
-//   items: [...],
-//   page: 0,
-//   pageSize: 10,
-//   hasNext: true,
-//   hasPrevious: false,
-//   total: 25,
-//   totalPages: 3
+//   added: [],
+//   removed: [],
+//   updated: [{ id: 1, changes: [...] }]
 // }
 ```
 
-#### Diff Detection
+### Select Class
 
-- **`diff(base)`** – Compares with another collection and returns detailed changes
+The Select class provides a fluent API for querying and transforming item collections.
 
-The diff method returns an object with three arrays:
-- `added`: IDs of entities that exist in the new collection but not in the base
-- `removed`: IDs of entities that exist in the base but not in the new collection
-- `updated`: Array of `ItemDiff` objects containing the ID and detailed property changes
+#### Methods
 
-Each change object contains:
-- `key`: The property name
-- `type`: `'added'`, `'removed'`, or `'changed'`
-- `oldValue`: The old value (wrapped in a `DiffHashedObject` with a `value` property)
-- `newValue`: The new value (wrapped in a `DiffHashedObject` with a `value` property)
+##### `take(len: number): Select<E>`
+
+Takes the first `n` items.
 
 ```typescript
-// Detect added entities
-const base = new Items([{ id: 1, name: 'Alice' }])
-const updated = base.insert([{ id: 2, name: 'Bob' }])
-const diff = updated.diff(base)
-// {
-//   added: [2],
-//   removed: [],
-//   updated: []
-// }
+users.select((s) => s.take(2))
+```
 
-// Detect removed entities
-const base = new Items([
-  { id: 1, name: 'Alice' },
-  { id: 2, name: 'Bob' }
-])
-const updated = base.remove(2)
-const diff = updated.diff(base)
-// {
-//   added: [],
-//   removed: [2],
-//   updated: []
-// }
+##### `skip(len: number): Select<E>`
 
-// Detect property changes
-const base = new Items([{ id: 1, name: 'Alice', age: 25 }])
-const updated = base.update(1, { age: 26 })
-const diff = updated.diff(base)
-// {
-//   added: [],
-//   removed: [],
-//   updated: [
-//     {
-//       id: 1,
-//       changes: [
-//         { 
-//           key: 'age', 
-//           type: 'changed', 
-//           oldValue: { value: 25, ... }, 
-//           newValue: { value: 26, ... }
-//         }
-//       ]
-//     }
-//   ]
-// }
+Skips the first `n` items.
 
-// Detect property addition
-const base = new Items([{ id: 1, name: 'Alice' }])
-const updated = base.update(1, { age: 25 })
-const diff = updated.diff(base)
-// {
-//   added: [],
-//   removed: [],
-//   updated: [
-//     {
-//       id: 1,
-//       changes: [
-//         { key: 'age', type: 'added', newValue: { value: 25, ... } }
-//       ]
-//     }
-//   ]
-// }
+```typescript
+users.select((s) => s.skip(1))
+```
 
-// Detect property removal (using set to replace completely)
-const base = new Items([{ id: 1, name: 'Alice', age: 25 }])
-const updated = base.set([{ id: 1, name: 'Alice' }])
-const diff = updated.diff(base)
-// {
-//   added: [],
-//   removed: [],
-//   updated: [
-//     {
-//       id: 1,
-//       changes: [
-//         { key: 'age', type: 'removed', oldValue: { value: 25, ... } }
-//       ]
-//     }
-//   ]
-// }
+##### `filter(testFn: (entry: E, id: ItemId, index: number) => boolean): Select<E>`
 
-// Detect multiple changes at once
-const base = new Items([
-  { id: 1, name: 'Alice', age: 25 },
-  { id: 2, name: 'Bob', age: 30 },
-  { id: 3, name: 'Charlie', age: 35 }
-])
-const updated = base
-  .remove(3)                                      // Remove Charlie
-  .update(1, { age: 26 })                         // Update Alice's age
-  .insert([{ id: 4, name: 'Dave', age: 40 }])     // Add Dave
-  
-const diff = updated.diff(base)
-// {
-//   added: [4],
-//   removed: [3],
-//   updated: [
-//     {
-//       id: 1,
-//       changes: [
-//         { 
-//           key: 'age', 
-//           type: 'changed', 
-//           oldValue: { value: 25, ... }, 
-//           newValue: { value: 26, ... }
-//         }
-//       ]
-//     }
-//   ]
-// }
+Filters items based on a predicate function.
 
-// Working with diff results
-const diff = updated.diff(base)
-
-// Access changed values
-diff.updated.forEach(item => {
-  console.log(`Entity ${item.id} was updated`)
-  item.changes.forEach(change => {
-    if (change.type === 'changed') {
-      console.log(`  ${change.key}: ${change.oldValue?.value} -> ${change.newValue?.value}`)
-    } else if (change.type === 'added') {
-      console.log(`  ${change.key}: added with value ${change.newValue?.value}`)
-    } else if (change.type === 'removed') {
-      console.log(`  ${change.key}: removed (was ${change.oldValue?.value})`)
-    }
-  })
-})
+```typescript
+users.select((s) => s.filter((user, id, index) => user.age > 25))
+```
 
-// Nested objects are also tracked
-interface UserWithAddress {
-  id: number
-  name: string
-  address: { city: string; country: string }
-}
+##### `revert(): Select<E>`
 
-const base = new Items<number, UserWithAddress>([
-  { id: 1, name: 'Alice', address: { city: 'NYC', country: 'USA' } }
-])
-const updated = base.update(1, {
-  address: { city: 'LA', country: 'USA' }
-})
-const diff = updated.diff(base)
-// Detects changes in nested object properties
+Reverses the order of items.
+
+```typescript
+users.select((s) => s.revert())
 ```
 
-#### Iteration
+##### `sort(sortFn: (a: E, b: E) => number): Select<E>`
 
-Items implements the iterable protocol:
+Sorts items using a comparator function.
 
 ```typescript
-for (const user of items) {
-  console.log(user.name)
-}
+users.select((s) => s.sort((a, b) => a.age - b.age))
+```
+
+##### `at(index: number): SingleSelect<E>`
+
+Returns a SingleSelect for the item at the given index.
 
-// Or use spread
-const array = [...items]
+```typescript
+const select = new Select(users.getIds(), users)
+const single = select.at(0)
 ```
 
-## Options
+##### `from(entities: Iterable<E>): Select<E>`
+
+Creates a new Select from the given entities.
+
+```typescript
+const select = new Select(users.getIds(), users)
+const newSelect = select.from([
+  { id: 2, name: 'Bob', age: 25 }
+])
+```
 
-### `selectId`
+##### `on(entry: E): SingleSelect<E>`
 
-Custom ID selector function. Defaults to `entity.id`.
+Creates a SingleSelect for the given entity.
 
 ```typescript
-interface Book {
-  isbn: string
-  title: string
-}
+const select = new Select(users.getIds(), users)
+const single = select.on({ id: 1, name: 'Alice', age: 30 })
+```
 
-const items = new Items<string, Book>([], {
-  selectId: (book) => book.isbn
-})
+### Chaining Selectors
+
+Selectors can be chained for powerful queries:
+
+```typescript
+const result = users.select((s) => 
+  s.filter((u) => u.age >= 25)
+    .sort((a, b) => a.age - b.age)
+    .skip(1)
+    .take(2)
+)
 ```
 
-### `sortComparer`
+## Diff Tracking
 
-Optional sort function. Set to `false` to disable sorting (default).
+Track changes between two Items instances:
 
 ```typescript
-// Sort by name ascending
-const items = new Items<number, User>([], {
-  sortComparer: (a, b) => a.name.localeCompare(b.name)
-})
+import { Items, itemsDiff } from '@wszerad/items'
 
-// Sort by age descending
-const items = new Items<number, User>([], {
-  sortComparer: (a, b) => b.age - a.age
-})
+const before = new Items([
+  { id: 1, name: 'Alice', age: 30 },
+  { id: 2, name: 'Bob', age: 25 }
+])
+
+const after = before
+  .update(1, { age: 31 })
+  .add([{ id: 3, name: 'Charlie', age: 35 }])
+  .remove(2)
+
+const diff = itemsDiff(before, after)
+console.log(diff)
+// {
+//   added: [3],
+//   removed: [2],
+//   updated: [{ id: 1, changes: [...] }]
+// }
 ```
 
-### Using every() and some()
+## Advanced Usage
+
+### Custom ID Selector
+
+Use a custom field as the ID:
 
 ```typescript
 interface Product {
-  id: number
+  sku: string
   name: string
   price: number
-  inStock: boolean
 }
 
-const products = new Items<number, Product>([
-  { id: 1, name: 'Laptop', price: 999, inStock: true },
-  { id: 2, name: 'Mouse', price: 29, inStock: true },
-  { id: 3, name: 'Keyboard', price: 79, inStock: false }
-])
-
-// Check if all products are in stock
-const allInStock = products.every(p => p.inStock) // false
+const products = new Items<Product>(
+  [
+    { sku: 'ABC123', name: 'Widget', price: 9.99 },
+    { sku: 'XYZ789', name: 'Gadget', price: 19.99 }
+  ],
+  { selectId: (product) => product.sku }
+)
 
-// Check if any product is expensive (over $500)
-const hasExpensive = products.some(p => p.price > 500) // true
+const widget = products.get('ABC123')
+```
 
-// Check if all products have names
-const allNamed = products.every(p => p.name.length > 0) // true
+### Automatic Sorting
 
-// Check if any product is cheap (under $30)
-const hasCheap = products.some(p => p.price < 30) // true
+Keep items sorted automatically:
 
-// Validation example
-const validateProducts = (items: Items<number, Product>) => {
-  const errors: string[] = []
-  
-  if (!items.every(p => p.price > 0)) {
-    errors.push('All products must have positive prices')
-  }
-  
-  if (!items.every(p => p.name.trim().length > 0)) {
-    errors.push('All products must have names')
-  }
-  
-  if (items.some(p => p.price > 10000)) {
-    errors.push('Warning: Some products are very expensive')
+```typescript
+const users = new Items(
+  [
+    { id: 3, name: 'Charlie', age: 35 },
+    { id: 1, name: 'Alice', age: 30 },
+    { id: 2, name: 'Bob', age: 25 }
+  ],
+  {
+    sortComparer: (a, b) => a.age - b.age
   }
-  
-  return errors
-}
-```
-
-## Selectors
+)
 
-Methods come in two flavors:
+console.log(users.getIds()) // [2, 1, 3] - sorted by age
+```
 
-### Single Entity Methods
-Accept a single ID directly:
-- `insert(entity)`, `upsert(entity)`, `set(entity)`
-- `update(id, updater)` – `items.update(1, { age: 26 })`
-- `remove(id)` – `items.remove(1)`
-- `has(id)` – `items.has(1)`
+### Complex Updates
 
-### Batch Methods
-Accept a `Selector` parameter that can be:
-1. **Array of IDs** – `items.removeMany([1, 2, 3])`
-2. **Predicate function** – `items.filter(user => user.age >= 30)`
+Perform complex transformations:
 
-Methods with `*Many` suffix always operate on multiple entities:
-- `insertMany(entities)`, `upsertMany(entities)`, `setMany(entities)`
-- `updateMany(selector, updater)`
-- `removeMany(selector)`
-- `filter(selector)`, `hasMany(selector)`
+```typescript
+// Increment age for all users over 25
+const updated = users.update(
+  (s) => s.filter((u) => u.age > 25),
+  (user) => ({
+    ...user!,
+    age: user!.age + 1,
+    senior: user!.age >= 65
+  })
+)
+```
 
-## Immutability
+### Immutability
 
-All operations return a **new** `Items` instance. Original instance is never modified.
+All operations are immutable:
 
 ```typescript
-const items1 = new Items<number, User>()
-const items2 = items1.insert({ id: 1, name: 'Alice' })
+const original = new Items([
+  { id: 1, name: 'Alice', age: 30 }
+])
+
+const updated = original.update(1, { age: 31 })
 
-console.log(items1.length) // 0
-console.log(items2.length) // 1
+console.log(original.get(1)?.age) // 30 - unchanged
+console.log(updated.get(1)?.age)  // 31 - new instance
 ```
 
-## TypeScript
+### Iteration
 
-Full type safety with generics:
+Items are iterable:
 
 ```typescript
-interface User {
-  id: number
-  name: string
-  age: number
+for (const user of users) {
+  console.log(user.name)
 }
 
-const items = new Items<number, User>()
-
-// ✅ Type-safe
-items.insert({ id: 1, name: 'Alice', age: 25 })
-
-// ❌ Type error
-items.insert({ id: 1, name: 'Alice' }) // Missing 'age'
+const array = Array.from(users)
+const names = [...users].map(u => u.name)
 ```
 
-## Examples
+### Single Item Selection
 
-### Basic CRUD
+The `select()` method automatically returns a single item (or undefined) when using `at()` or `on()` methods:
 
 ```typescript
-import { Items } from 'items'
-
-interface Todo {
-  id: number
-  text: string
-  completed: boolean
-}
+const users = new Items<User>([
+  { id: 1, name: 'Alice', age: 30 },
+  { id: 2, name: 'Bob', age: 25 },
+  { id: 3, name: 'Charlie', age: 35 }
+])
 
-let todos = new Items<number, Todo>()
+// Select by index - returns single User or undefined
+const firstUser = users.select((s) => s.at(0))
+console.log(firstUser?.name) // 'Alice'
 
-// Add single todo
-todos = todos.insert({ id: 1, text: 'Learn Items', completed: false })
+const secondUser = users.select((s) => s.at(1))
+console.log(secondUser?.name) // 'Bob'
 
-// Add multiple todos
-todos = todos.insertMany([
-  { id: 2, text: 'Build app', completed: false },
-  { id: 3, text: 'Deploy', completed: false }
-])
+// Select by ID - returns single User or undefined
+const user = users.select(2)
+console.log(user?.name) // 'Bob'
 
-// Update (merges with existing)
-todos = todos.update(1, { completed: true })
+// Out of bounds returns undefined
+const notFound = users.select((s) => s.at(10))
+console.log(notFound) // undefined
 
-// Filter
-const completed = todos.filter(todo => todo.completed)
+// Chain operations before selecting single item
+const oldestUser = users.select((s) => 
+  s.sort((a, b) => b.age - a.age).at(0)
+)
+console.log(oldestUser?.name) // 'Charlie' (age 35)
 
-// Remove
-todos = todos.remove(1)
+// Get just the ID instead of the full item
+const oldestId = users.selectId((s) => 
+  s.sort((a, b) => b.age - a.age).at(0)
+)
+console.log(oldestId) // 3
 ```
 
-### Understanding insert, upsert, set, and update
+## TypeScript Support
 
-```typescript
-import { Items } from 'items'
+Full TypeScript support with generics:
 
+```typescript
 interface User {
   id: number
   name: string
-  email?: string
-  age?: number
+  age: number
 }
 
-// Start with a user
-let users = new Items<number, User>([
-  { id: 1, name: 'Alice', email: 'alice@example.com', age: 25 }
-])
+const users = new Items<User>() // Fully typed
 
-// INSERT - only adds if doesn't exist, skips if exists
-users = users.insert({ id: 1, name: 'Alice Updated', age: 30 })
-// Result: { id: 1, name: 'Alice', email: 'alice@example.com', age: 25 }
-// Note: Original entity unchanged because id: 1 already exists
-
-users = users.insert({ id: 2, name: 'Bob' })
-// Result: Adds Bob with id: 2 since it doesn't exist
-
-// UPSERT - merges properties (adds new, extends existing)
-users = users.upsert({ id: 1, name: 'Alicia', age: 26 })
-// Result: { id: 1, name: 'Alicia', email: 'alice@example.com', age: 26 }
-// Note: name and age updated, email preserved!
-
-// SET - completely replaces entity
-users = users.set({ id: 1, name: 'Alice' })
-// Result: { id: 1, name: 'Alice' }
-// Note: email and age are removed!
-
-// UPDATE - merges partial update with existing entity
-users = users.update(1, { age: 27 })
-// Result: { id: 1, name: 'Alice', age: 27 }
-// Note: age added, name preserved
-
-// Batch operations with *Many methods
-users = users.insertMany([
-  { id: 3, name: 'Charlie' },
-  { id: 4, name: 'Dave' }
-])
-
-users = users.upsertMany([
-  { id: 1, age: 28 },
-  { id: 3, email: 'charlie@example.com' }
-])
-
-users = users.setMany([
-  { id: 2, name: 'Robert', age: 35 }
-])
+// Type inference works automatically
+const names: string[] = users
+  .select((s) => s.filter((u) => u.age >= 30))
+  .map(u => u.name)
 ```
 
-### Checking Entity Existence
+## Types
 
 ```typescript
-interface Product {
-  sku: string
-  name: string
-  price: number
-}
+type ItemId = string | number
 
-const products = new Items<string, Product>([], {
-  selectId: (product) => product.sku
-})
+type Selector<E> = 
+  | ((selector: BaseSelect<E>) => BaseSelect<E>) 
+  | ItemId 
+  | Iterable<ItemId>
 
-const updated = products.insert([
-  { sku: 'ABC-123', name: 'Widget', price: 19.99 }
-])
+type Updater<E> = 
+  | ((entity: E | undefined) => E)
+  | Partial<E>
 
-console.log(updated.select('ABC-123'))
+type ItemsOptions<E> = {
+  selectId?: (entity: E) => ItemId
+  sortComparer?: false | ((a: E, b: E) => number)
+}
+
+interface ItemsDiff {
+  added: ItemId[]
+  removed: ItemId[]
+  updated: ItemDiff[]
+}
+
+interface ItemDiff {
+  id: ItemId
+  changes: any[]
+}
 ```
 
-### With Sorting
+## License
 
-```typescript
-const items = new Items<number, User>(
-  [
-    { id: 3, name: 'Charlie', age: 35 },
-    { id: 1, name: 'Alice', age: 25 },
-    { id: 2, name: 'Bob', age: 30 }
-  ],
-  { sortComparer: (a, b) => a.name.localeCompare(b.name) }
-)
+MIT © Wszerad Martynowski
 
-console.log(items.getIds()) // [1, 2, 3] - sorted by name
-```
+## Contributing
 
----
+Contributions are welcome! Please feel free to submit a Pull Request.
 
-## Development
+## Repository
 
-### Scripts
+https://github.com/wszerad/items
 
-- `npm test` – runs tests (Vitest)
-- `npm run test:watch` – watch mode
-- `npm run build` – typecheck + bundling (tsc + tsdown)
-- `npm run typecheck` – TypeScript type checking (