@wszerad/items 0.0.6 → 0.1.1

package/.github/dependabot.yml

@@ -0,0 +1,15 @@
+# To get started with Dependabot version updates, you'll need to specify which
+# package ecosystems to update and where the package manifests are located.
+# Please see the documentation for all configuration options:
+# https://docs.github.com/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file
+
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+  - package-ecosystem: npm
+    directory: "/"
+    schedule:
+      interval: "weekly"

package/.github/workflows/publish.yml

@@ -0,0 +1,22 @@
+name: Publish
+
+on:
+  release:
+    types: [created]
+
+jobs:
+  publish-chain:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+      contents: read
+      packages: write
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-node@v6
+        with:
+          node-version: "24"
+      - run: npm ci
+      - run: npm test
+      - run: npm run build
+      - run: npm publish --access public

package/.github/workflows/test.yml

@@ -0,0 +1,21 @@
+name: Test
+
+on:
+  pull_request:
+    branches:
+      - master
+  push:
+    branches:
+      - master
+
+jobs:
+  test:
+    name: Run tests for each push
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-node@v6
+        with:
+          node-version: "22"
+      - run: npm ci
+      - run: npm test

package/.idea/copilot.data.migration.ask2agent.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="Ask2AgentMigrationStateService">
+    <option name="migrationStatus" value="COMPLETED" />
+  </component>
+</project>

package/.idea/modules.xml

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="ProjectModuleManager">
+    <modules>
+      <module fileurl="file://$PROJECT_DIR$/.idea/items.iml" filepath="$PROJECT_DIR$/.idea/items.iml" />
+    </modules>
+  </component>
+</project>

package/.idea/vcs.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="VcsDirectoryMappings">
+    <mapping directory="" vcs="Git" />
+  </component>
+</project>

package/.oxlintrc.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "https://raw.githubusercontent.com/oxc-project/oxc/main/npm/oxlint/configuration_schema.json",
+  "env": {
+    "es2022": true,
+    "node": true
+  },
+  "plugins": ["typescript"],
+  "rules": {
+    "eslint/no-unused-vars": "error",
+    "typescript/no-explicit-any": "warn"
+  }
+}
+

package/README.md

@@ -4,7 +4,7 @@ Lightweight, immutable collection manager inspired by NgRx Entity Adapter.
 
 ## Features
 
-- ✅ Immutable operations (insert/insertMany, upsert/upsertMany, set/setMany, update, remove, filter, etc.)
+- ✅ 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`)
@@ -19,7 +19,7 @@ Lightweight, immutable collection manager inspired by NgRx Entity Adapter.
 ## Installation
 
 ```bash
-npm install items
+npm install @wszerad/items
 ```
 
 ## Quick Start
@@ -722,40 +722,45 @@ users = users.setMany([
 ### Checking Entity Existence
 
 ```typescript
-import { Items } from 'items'
+interface Product {
+  sku: string
+  name: string
+  price: number
+}
 
-const users = new Items<number, User>([
-  { id: 1, name: 'Alice', age: 25 },
-  { id: 2, name: 'Bob', age: 30 },
-  { id: 3, name: 'Charlie', age: 35 }
+const products = new Items<string, Product>([], {
+  selectId: (product) => product.sku
+})
+
+const updated = products.insert([
+  { sku: 'ABC-123', name: 'Widget', price: 19.99 }
 ])
 
-// Check single entity exists
-if (users.has(1)) {
-  console.log('User 1 exists')
-}
+console.log(updated.select('ABC-123'))
+```
 
-if (!users.has(99)) {
-  console.log('User 99 does not exist')
-}
+### With Sorting
 
-// Check multiple entities exist (ALL must exist)
-if (users.hasMany([1, 2])) {
-  console.log('Users 1 and 2 both exist')
-}
+```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) }
+)
 
-if (!users.hasMany([1, 99])) {
-  console.log('Not all users exist')
-}
+console.log(items.getIds()) // [1, 2, 3] - sorted by name
+```
 
-// Check if any entity matches condition
-if (users.hasMany(user => user.age >= 30)) {
-  console.log('At least one user is 30 or older')
-}
+---
+
+## Development
 
-// Use with conditionals
-const userExists = users.has(1)
-const allExist = users.hasMany([1, 2, 3])
-const hasAdults = users.hasMany(user => user.age >= 18)
+### Scripts
 
-// Combine with ot
+- `npm test` – runs tests (Vitest)
+- `npm run test:watch` – watch mode
+- `npm run build` – typecheck + bundling (tsc + tsdown)
+- `npm run typecheck` – TypeScript type checking (

package/package.json

@@ -1,16 +1,14 @@
 {
   "name": "@wszerad/items",
-  "version": "0.0.6",
+  "version": "0.1.1",
   "type": "module",
   "exports": {
-    ".": "./dist/index.js",
+    ".": "./dist/index.mjs",
     "./package.json": "./package.json"
   },
-  "main": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "files": [
-    "dist"
-  ],
+  "main": "./dist/index.mjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
   "engines": {
     "node": ">=20"
   },
@@ -47,6 +45,5 @@
     "type": "git",
     "url": "git+https://github.com/wszerad/items.git"
   },
-  "license": "MIT",
-  "module": "./dist/index.js"
+  "license": "MIT"
 }

package/src/Items.ts

@@ -0,0 +1,215 @@
+import { defaultSelectId, SelectId, StrOrNum } from './selectId'
+import { selector, Selector, SelectorFn } from './selector'
+import { Updater } from './updater'
+import { itemsDiff } from './diff'
+import { update } from './updater'
+
+export type ItemsOptions<E> = {
+  selectId?: SelectId<E>
+  sortComparer?: false | ((a: E, b: E) => number)
+}
+
+export interface ItemsState<E, I> {
+  ids: I[]
+  entities: Map<I, E>
+}
+
+export class Items<E, I extends StrOrNum = StrOrNum> {
+  private state: ItemsState<E, I>
+
+  constructor(
+    items: Iterable<E> = [],
+    private options: ItemsOptions<E> = {}
+  ) {
+    const entities = new Map(
+      Array
+        .from(items)
+        .map((item) => {
+          const id = this.selectId(item)
+          return [id, item]
+        })
+    )
+
+    this.state = {
+      ids: this.sortIds([...entities.keys()], entities),
+      entities
+    }
+  }
+
+  getIds(): I[] {
+    return [...this.state.ids]
+  }
+
+  getEntities(): Map<I, E> {
+    return new Map(this.state.entities)
+  }
+
+  get length(): number {
+    return this.state.ids.length
+  }
+
+  select(id: I): E | undefined {
+    return this.state.entities.get(id)
+  }
+
+  insert(entity: E) {
+    return this.insertMany([entity])
+  }
+
+  insertMany(entities: Iterable<E>) {
+    return new Items<E, I>([
+      ...this,
+      ...Array.from(entities).filter(entity => !this.has(this.selectId(entity)))
+    ], this.options)
+  }
+
+  upsert(entity: Partial<E>) {
+    return this.upsertMany([entity])
+  }
+
+  upsertMany(entities: Iterable<Partial<E>>) {
+    const clone = this.getEntities()
+    Array.from(entities).forEach(entity => {
+      const id = this.selectId(entity as E)
+      const existing = clone.get(id)
+      if (existing) {
+        clone.set(id, { ...existing, ...entity } as E)
+      } else {
+        clone.set(id, entity as E)
+      }
+    })
+    return new Items<E, I>(clone.values(), this.options)
+  }
+
+  set(entity: E) {
+    return this.setMany([entity])
+  }
+
+  setMany(entities: Iterable<E>) {
+    return new Items<E, I>([
+      ...this,
+      ...entities
+    ], this.options)
+  }
+
+  every(check: SelectorFn<E>) {
+    return this.getIds().every(id => check(this.select(id)!))
+  }
+
+  some(check: SelectorFn<E>) {
+    return this.getIds().some(id => check(this.select(id)!))
+  }
+
+  has(id: I) {
+    return this.state.ids.includes(id)
+  }
+
+  hasMany(select: Selector<E, I>) {
+    let failToFind = false
+    let result = false
+    selector(this, select, (entity) => {
+      if (entity) {
+        result = true
+      } else {
+        failToFind = true
+      }
+    })
+    return !failToFind && result
+  }
+
+  update(id: I, updater: Updater<E>) {
+    const entity = this.select(id)
+    if (!entity) {
+      return this
+    }
+    const clone = this.getEntities()
+    clone.set(id, update(entity, updater))
+    return new Items<E, I>(clone.values(), this.options)
+  }
+
+  updateMany(select: Selector<E, I>, updater: Updater<E>) {
+    const clone = this.getEntities()
+    selector(this, select, (entity, id) => {
+      if (entity) {
+        clone.set(id, update(entity, updater))
+      }
+    })
+    return new Items<E, I>(clone.values(), this.options)
+  }
+
+  remove(id: I) {
+    const clone = this.getEntities()
+    clone.delete(id)
+    return new Items<E, I>(clone.values(), this.options)
+  }
+
+  removeMany(select: Selector<E, I>) {
+    const clone = this.getEntities()
+    selector(this, select, (_, id) => {
+      clone.delete(id)
+    })
+    return new Items<E, I>(clone.values(), this.options)
+  }
+
+  clear() {
+    return new Items<E, I>([], this.options)
+  }
+
+  filter(select: Selector<E, I>) {
+    const clone = new Map<I, E>()
+
+    selector(this, select, (entity, id) => {
+      if (entity) {
+        clone.set(id, entity)
+      }
+    })
+
+    return new Items<E, I>(clone.values(), this.options)
+  }
+
+  page(page: number, pageSize: number) {
+    const totalPages = Math.ceil(this.length / pageSize)
+    return {
+      items: this.getIds()
+        .slice(page * pageSize, (page + 1) * pageSize)
+        .map(id => this.select(id)!),
+      page,
+      pageSize,
+      hasNext: page < totalPages - 1,
+      hasPrevious: page > 0,
+      total: this.length,
+      totalPages
+    }
+  }
+
+  diff(base: Items<E, I>) {
+    return itemsDiff(base, this)
+  }
+
+  private sortIds(
+    ids: I[],
+    entities: Map<I, E>
+  ): Array<I> {
+    if (this.sortComparer === false) {
+      return ids
+    }
+    const sorter = this.sortComparer
+    return [...ids].sort((aId, bId) => {
+      const a = entities.get(aId)!
+      const b = entities.get(bId)!
+      return sorter(a, b)
+    })
+  }
+
+  private selectId(entity: E): I {
+    return this.options?.selectId?.(entity) as undefined || defaultSelectId(entity as E & { id: I })
+  }
+
+  private get sortComparer() {
+    return this.options.sortComparer || false
+  }
+
+  [Symbol.iterator](): Iterator<E> {
+    return this.state.entities.values()
+  }
+}

package/src/diff.ts

@@ -0,0 +1,44 @@
+import { diff } from 'ohash/utils'
+import { Items } from './Items'
+import { StrOrNum } from './selectId'
+
+export interface ItemDiff<I> {
+  id: I
+  changes: ReturnType<typeof diff>
+}
+
+export interface ItemsDiff<I> {
+  added: I[]
+  removed: I[]
+  updated: ItemDiff<I>[]
+}
+
+export function itemsDiff<E, I extends StrOrNum>(fromItems: Items<E, I>, toItems: Items<E, I>): ItemsDiff<I> {
+  const ids = new Set(toItems.getIds())
+  const baseIds = new Set(fromItems.getIds())
+
+  const added: I[] = []
+  const updated: ItemDiff<I>[] = []
+
+  ids.forEach(id => {
+    if (!baseIds.has(id)) {
+      added.push(id)
+    } else {
+      const changes = diff(fromItems.select(id), toItems.select(id))
+
+      if (changes.length > 0) {
+        updated.push({ id, changes })
+      }
+
+      baseIds.delete(id)
+    }
+  })
+
+  const removed = [...baseIds]
+
+  return {
+    added,
+    removed,
+    updated
+  }
+}

package/src/index.ts

@@ -0,0 +1,6 @@
+export { Items } from './Items'
+export type { ItemsOptions, ItemsState } from './Items'
+export type { SelectId, StrOrNum } from './selectId'
+export type { Selector, SelectorFn, Operation } from './selector'
+export type { Updater, UpdateFn } from './updater'
+export type { ItemDiff, ItemsDiff } from './diff'

package/src/selectId.ts

@@ -0,0 +1,7 @@
+export type StrOrNum = string | number
+
+export type SelectId<E> = (entity: E) => StrOrNum
+
+export function defaultSelectId<E extends { id: I }, I = E['id']>(entity: E) {
+  return entity.id
+}

package/src/selector.ts

@@ -0,0 +1,20 @@
+import { Items } from './Items'
+import { StrOrNum } from './selectId'
+
+export type SelectorFn<E> = (entity: E) => boolean
+export type Selector<E, I> = Iterable<I> | SelectorFn<E>
+export type Operation<E, I> = (entity: E | undefined, id: I) => void
+
+export function selector<E, I extends StrOrNum>(items: Items<E, I>, selector: Selector<E, I>, operation: Operation<E, I>) {
+  if (typeof selector === 'function') {
+    items.getEntities().forEach((entity, id) => {
+      if ((selector as SelectorFn<E>)(entity)) {
+        operation(entity, id)
+      }
+    })
+  } else {
+    Array
+      .from(selector as Iterable<I>)
+      .forEach(id => operation(items.select(id), id))
+  }
+}

package/src/updater.ts

@@ -0,0 +1,6 @@
+export type UpdateFn<E> = (entity: E) => E
+export type Updater<E> = UpdateFn<E> | Partial<E>
+
+export function update<E>(entity: E, updater: Updater<E>) {
+  return { ...entity, ...(typeof updater === 'function' ? updater(entity) : updater) }
+}