@furystack/repository 10.1.10 → 11.0.0

package/src/data-set.spec.ts

@@ -0,0 +1,396 @@
+import type { StoreToken, WithOptionalId } from '@furystack/core'
+import { AuthorizationError, defineStore, InMemoryStore } from '@furystack/core'
+import { createInjector, type Injector } from '@furystack/inject'
+import { usingAsync } from '@furystack/utils'
+import { describe, expect, it, vi } from 'vitest'
+import type { AuthorizationResult, DataSetSettings } from './data-set-setting.js'
+import type { DataSet } from './data-set.js'
+import { defineDataSet, type DefineDataSetSettings } from './define-data-set.js'
+import { getDataSetFor } from './helpers.js'
+
+class TestClass {
+  declare id: number
+  declare value: string
+}
+
+// Token declared at module scope so TypeScript preserves the literal primary
+// key. The explicit `StoreToken<TestClass, 'id'>` annotation keeps
+// `TPrimaryKey` narrow when the token is later passed to `defineDataSet`;
+// inferred return types from `defineStore` tend to widen back to
+// `keyof TestClass` in downstream inference contexts.
+const TestStore: StoreToken<TestClass, 'id'> = defineStore({
+  name: 'test/DataSetSpecStore',
+  model: TestClass,
+  primaryKey: 'id',
+  factory: () => new InMemoryStore({ model: TestClass, primaryKey: 'id' }),
+})
+
+/**
+ * Builds a fresh injector with a disposable {@link InMemoryStore} bound as the
+ * backing store for a {@link TestClass} dataset. Each call mints a new
+ * dataset token so the injector cache starts from scratch for every test.
+ */
+const withDataSet = async (
+  settings: DefineDataSetSettings<TestClass, 'id'> | undefined,
+  fn: (ctx: { i: Injector; dataSet: DataSet<TestClass, 'id'> }) => Promise<void>,
+): Promise<void> => {
+  const TestDataSet = defineDataSet<TestClass, 'id', WithOptionalId<TestClass, 'id'>>({
+    name: `test/DataSet-${Math.random()}`,
+    store: TestStore,
+    settings,
+  })
+  await usingAsync(createInjector(), async (i) => {
+    const dataSet = getDataSetFor(i, TestDataSet)
+    await fn({ i, dataSet })
+  })
+}
+
+describe('DataSet', () => {
+  describe('Authorizers', () => {
+    describe('Add', () => {
+      it('adds an entity when no settings are provided', async () => {
+        await withDataSet(undefined, async ({ i, dataSet }) => {
+          await dataSet.add(i, { id: 1, value: 'asd' })
+          const result = await dataSet.get(i, 1)
+          expect(result?.value).toBe('asd')
+        })
+      })
+
+      it('runs authorizeAdd and persists the entity on pass', async () => {
+        const authorizeAdd = vi.fn(async () => ({ isAllowed: true }) as AuthorizationResult)
+        await withDataSet({ authorizeAdd }, async ({ i, dataSet }) => {
+          await dataSet.add(i, { id: 1, value: 'asd' })
+          expect(authorizeAdd).toHaveBeenCalled()
+          expect((await dataSet.get(i, 1))?.value).toBe('asd')
+        })
+      })
+
+      it('throws and does not persist when authorizeAdd fails', async () => {
+        const authorizeAdd = vi.fn(async () => ({ isAllowed: false, message: '...' }) as AuthorizationResult)
+        await withDataSet({ authorizeAdd }, async ({ i, dataSet }) => {
+          await expect(dataSet.add(i, { id: 1, value: 'asd' })).rejects.toBeInstanceOf(AuthorizationError)
+          expect(authorizeAdd).toHaveBeenCalled()
+          expect(await dataSet.get(i, 1)).toBeUndefined()
+        })
+      })
+
+      it('applies modifyOnAdd before persisting', async () => {
+        const modifyOnAdd = vi.fn<NonNullable<DataSetSettings<TestClass, 'id'>['modifyOnAdd']>>(async ({ entity }) => ({
+          ...entity,
+          value: entity.value.toUpperCase(),
+        }))
+        await withDataSet({ modifyOnAdd }, async ({ i, dataSet }) => {
+          await dataSet.add(i, { id: 1, value: 'asd' })
+          const result = await dataSet.get(i, 1)
+          expect(modifyOnAdd).toHaveBeenCalled()
+          expect(result?.value).toBe('ASD')
+        })
+      })
+
+      it('emits onEntityAdded after a successful add', async () => {
+        await withDataSet(undefined, async ({ i, dataSet }) => {
+          const listener = vi.fn()
+          dataSet.addListener('onEntityAdded', listener)
+          await dataSet.add(i, { id: 1, value: 'asd' })
+          expect(listener).toHaveBeenCalledWith(expect.objectContaining({ entity: { id: 1, value: 'asd' } }))
+        })
+      })
+    })
+
+    describe('Update', () => {
+      it('updates an entity when no settings are provided', async () => {
+        await withDataSet(undefined, async ({ i, dataSet }) => {
+          await dataSet.add(i, { id: 1, value: 'asd' })
+          await dataSet.update(i, 1, { id: 1, value: 'asd2' })
+          expect((await dataSet.get(i, 1))?.value).toBe('asd2')
+        })
+      })
+
+      it('runs authorizeUpdate and persists on pass', async () => {
+        const authorizeUpdate = vi.fn(async () => ({ isAllowed: true }) as AuthorizationResult)
+        await withDataSet({ authorizeUpdate }, async ({ i, dataSet }) => {
+          await dataSet.add(i, { id: 1, value: 'asd' })
+          await dataSet.update(i, 1, { id: 1, value: 'asd2' })
+          expect(authorizeUpdate).toHaveBeenCalled()
+          expect((await dataSet.get(i, 1))?.value).toBe('asd2')
+        })
+      })
+
+      it('throws when authorizeUpdate fails and leaves the entity untouched', async () => {
+        const authorizeUpdate = vi.fn(async () => ({ isAllowed: false, message: '...' }) as AuthorizationResult)
+        await withDataSet({ authorizeUpdate }, async ({ i, dataSet }) => {
+          await dataSet.add(i, { id: 1, value: 'asd' })
+          await expect(dataSet.update(i, 1, { id: 1, value: 'asd2' })).rejects.toBeInstanceOf(AuthorizationError)
+          expect((await dataSet.get(i, 1))?.value).toBe('asd')
+        })
+      })
+
+      it('runs authorizeUpdateEntity against the loaded entity and persists on pass', async () => {
+        const authorizeUpdateEntity = vi.fn(async () => ({ isAllowed: true }) as AuthorizationResult)
+        await withDataSet({ authorizeUpdateEntity }, async ({ i, dataSet }) => {
+          await dataSet.add(i, { id: 1, value: 'asd' })
+          await dataSet.update(i, 1, { id: 1, value: 'asd2' })
+          expect(authorizeUpdateEntity).toHaveBeenCalled()
+          expect((await dataSet.get(i, 1))?.value).toBe('asd2')
+        })
+      })
+
+      it('throws and leaves the entity untouched when authorizeUpdateEntity fails', async () => {
+        const authorizeUpdateEntity = vi.fn(async () => ({ isAllowed: false, message: '...' }) as AuthorizationResult)
+        await withDataSet({ authorizeUpdateEntity }, async ({ i, dataSet }) => {
+          await dataSet.add(i, { id: 1, value: 'asd' })
+          await expect(dataSet.update(i, 1, { id: 1, value: 'asd2' })).rejects.toBeInstanceOf(AuthorizationError)
+          expect((await dataSet.get(i, 1))?.value).toBe('asd')
+        })
+      })
+
+      it('applies modifyOnUpdate before persisting', async () => {
+        const modifyOnUpdate = vi.fn<NonNullable<DataSetSettings<TestClass, 'id'>['modifyOnUpdate']>>(
+          async ({ entity }) => ({
+            ...entity,
+            value: entity.value?.toUpperCase() ?? '',
+          }),
+        )
+        await withDataSet({ modifyOnUpdate }, async ({ i, dataSet }) => {
+          await dataSet.add(i, { id: 1, value: 'asd' })
+          await dataSet.update(i, 1, { id: 1, value: 'asd2' })
+          expect(modifyOnUpdate).toHaveBeenCalled()
+          expect((await dataSet.get(i, 1))?.value).toBe('ASD2')
+        })
+      })
+
+      it('emits onEntityUpdated with the applied change', async () => {
+        await withDataSet(undefined, async ({ i, dataSet }) => {
+          const listener = vi.fn()
+          dataSet.addListener('onEntityUpdated', listener)
+          await dataSet.add(i, { id: 1, value: 'asd' })
+          await dataSet.update(i, 1, { id: 1, value: 'asd2' })
+          expect(listener).toHaveBeenCalledWith(expect.objectContaining({ change: { id: 1, value: 'asd2' }, id: 1 }))
+        })
+      })
+    })
+
+    describe('Count', () => {
+      it('returns the count when no settings are provided', async () => {
+        await withDataSet(undefined, async ({ i, dataSet }) => {
+          await dataSet.add(i, { id: 1, value: 'asd' })
+          expect(await dataSet.count(i)).toBe(1)
+        })
+      })
+
+      it('returns the count when authorizeGet passes', async () => {
+        const authorizeGet = vi.fn(async () => ({ isAllowed: true, message: '' }) as AuthorizationResult)
+        await withDataSet({ authorizeGet }, async ({ i, dataSet }) => {
+          await dataSet.add(i, { id: 1, value: 'asd' })
+          expect(await dataSet.count(i)).toBe(1)
+        })
+      })
+
+      it('throws when authorizeGet fails', async () => {
+        const authorizeGet = vi.fn(async () => ({ isAllowed: false, message: ':(' }) as AuthorizationResult)
+        await withDataSet({ authorizeGet }, async ({ i, dataSet }) => {
+          await dataSet.add(i, { id: 1, value: 'asd' })
+          await expect(dataSet.count(i)).rejects.toBeInstanceOf(AuthorizationError)
+        })
+      })
+    })
+  })
+
+  describe('filter', () => {
+    it('returns the unfiltered result when no settings are provided', async () => {
+      await withDataSet(undefined, async ({ i, dataSet }) => {
+        await dataSet.add(i, { id: 1, value: 'asd' })
+        expect((await dataSet.find(i, {})).length).toBe(1)
+      })
+    })
+
+    it('returns the unfiltered result when authorizeGet passes', async () => {
+      const authorizeGet = vi.fn(async () => ({ isAllowed: true, message: '' }) as AuthorizationResult)
+      await withDataSet({ authorizeGet }, async ({ i, dataSet }) => {
+        await dataSet.add(i, { id: 1, value: 'asd' })
+        expect((await dataSet.find(i, {})).length).toBe(1)
+      })
+    })
+
+    it('throws when authorizeGet fails', async () => {
+      const authorizeGet = vi.fn(async () => ({ isAllowed: false, message: ':(' }) as AuthorizationResult)
+      await withDataSet({ authorizeGet }, async ({ i, dataSet }) => {
+        await dataSet.add(i, { id: 1, value: 'asd' })
+        await expect(dataSet.find(i, {})).rejects.toBeInstanceOf(AuthorizationError)
+      })
+    })
+  })
+
+  describe('get', () => {
+    it('returns the entity when no settings are provided', async () => {
+      await withDataSet(undefined, async ({ i, dataSet }) => {
+        await dataSet.add(i, { id: 1, value: 'asd' })
+        expect((await dataSet.get(i, 1))?.id).toBe(1)
+      })
+    })
+
+    it('returns the entity when authorizeGet passes', async () => {
+      const authorizeGet = vi.fn(async () => ({ isAllowed: true, message: '' }) as AuthorizationResult)
+      await withDataSet({ authorizeGet }, async ({ i, dataSet }) => {
+        await dataSet.add(i, { id: 1, value: 'asd' })
+        expect((await dataSet.get(i, 1))?.id).toBe(1)
+      })
+    })
+
+    it('throws when authorizeGet fails', async () => {
+      const authorizeGet = vi.fn(async () => ({ isAllowed: false, message: ':(' }) as AuthorizationResult)
+      await withDataSet({ authorizeGet }, async ({ i, dataSet }) => {
+        await dataSet.add(i, { id: 1, value: 'asd' })
+        await expect(dataSet.get(i, 1)).rejects.toBeInstanceOf(AuthorizationError)
+      })
+    })
+
+    it('returns the entity when authorizeGetEntity passes', async () => {
+      const authorizeGetEntity = vi.fn(async () => ({ isAllowed: true, message: '' }) as AuthorizationResult)
+      await withDataSet({ authorizeGetEntity }, async ({ i, dataSet }) => {
+        await dataSet.add(i, { id: 1, value: 'asd' })
+        expect((await dataSet.get(i, 1))?.id).toBe(1)
+      })
+    })
+
+    it('throws when authorizeGetEntity fails', async () => {
+      const authorizeGetEntity = vi.fn(async () => ({ isAllowed: false, message: ':(' }) as AuthorizationResult)
+      await withDataSet({ authorizeGetEntity }, async ({ i, dataSet }) => {
+        await dataSet.add(i, { id: 1, value: 'asd' })
+        await expect(dataSet.get(i, 1)).rejects.toBeInstanceOf(AuthorizationError)
+      })
+    })
+
+    it('receives the full entity in authorizeGetEntity even when select is used', async () => {
+      const authorizeGetEntity = vi.fn(async () => ({ isAllowed: true, message: '' }) as AuthorizationResult)
+      await withDataSet({ authorizeGetEntity }, async ({ i, dataSet }) => {
+        await dataSet.add(i, { id: 1, value: 'asd' })
+        const result = await dataSet.get(i, 1, ['value'])
+        expect(authorizeGetEntity).toHaveBeenCalledTimes(1)
+        const firstCall = authorizeGetEntity.mock.calls[0] as unknown as [{ entity: TestClass }]
+        expect(firstCall[0].entity).toEqual({ id: 1, value: 'asd' })
+        expect(result).toEqual({ value: 'asd' })
+        expect(result).not.toHaveProperty('id')
+      })
+    })
+
+    it('returns undefined without calling authorizeGetEntity when the entity does not exist', async () => {
+      const authorizeGetEntity = vi.fn(async () => ({ isAllowed: true, message: '' }) as AuthorizationResult)
+      await withDataSet({ authorizeGetEntity }, async ({ i, dataSet }) => {
+        const result = await dataSet.get(i, 999)
+        expect(result).toBeUndefined()
+        expect(authorizeGetEntity).not.toHaveBeenCalled()
+      })
+    })
+  })
+
+  describe('remove', () => {
+    it('removes the entity when no settings are provided', async () => {
+      await withDataSet(undefined, async ({ i, dataSet }) => {
+        await dataSet.add(i, { id: 1, value: 'asd' })
+        await dataSet.remove(i, 1)
+        expect(await dataSet.count(i)).toBe(0)
+      })
+    })
+
+    it('removes the entity when authorizeRemove passes', async () => {
+      const authorizeRemove = vi.fn(async () => ({ isAllowed: true, message: '' }) as AuthorizationResult)
+      await withDataSet({ authorizeRemove }, async ({ i, dataSet }) => {
+        await dataSet.add(i, { id: 1, value: 'asd' })
+        await dataSet.remove(i, 1)
+        expect(await dataSet.count(i)).toBe(0)
+      })
+    })
+
+    it('throws and preserves the entity when authorizeRemove fails', async () => {
+      const authorizeRemove = vi.fn(async () => ({ isAllowed: false, message: ':(' }) as AuthorizationResult)
+      await withDataSet({ authorizeRemove }, async ({ i, dataSet }) => {
+        await dataSet.add(i, { id: 1, value: 'asd' })
+        await expect(dataSet.remove(i, 1)).rejects.toBeInstanceOf(AuthorizationError)
+        expect(await dataSet.count(i)).toBe(1)
+      })
+    })
+
+    it('removes the entity when authorizeRemoveEntity passes', async () => {
+      const authorizeRemoveEntity = vi.fn(async () => ({ isAllowed: true, message: '' }) as AuthorizationResult)
+      await withDataSet({ authorizeRemoveEntity }, async ({ i, dataSet }) => {
+        await dataSet.add(i, { id: 1, value: 'asd' })
+        await dataSet.remove(i, 1)
+        expect(await dataSet.count(i)).toBe(0)
+      })
+    })
+
+    it('throws and preserves the entity when authorizeRemoveEntity fails', async () => {
+      const authorizeRemoveEntity = vi.fn(async () => ({ isAllowed: false, message: ':(' }) as AuthorizationResult)
+      await withDataSet({ authorizeRemoveEntity }, async ({ i, dataSet }) => {
+        await dataSet.add(i, { id: 1, value: 'asd' })
+        await expect(dataSet.remove(i, 1)).rejects.toBeInstanceOf(AuthorizationError)
+        expect(await dataSet.count(i)).toBe(1)
+      })
+    })
+
+    it('emits onEntityRemoved after a successful remove', async () => {
+      await withDataSet(undefined, async ({ i, dataSet }) => {
+        const listener = vi.fn()
+        dataSet.addListener('onEntityRemoved', listener)
+        await dataSet.add(i, { id: 1, value: 'asd' })
+        await dataSet.remove(i, 1)
+        expect(listener).toHaveBeenCalledWith(expect.objectContaining({ key: 1 }))
+      })
+    })
+
+    it('removes multiple entities at once', async () => {
+      await withDataSet(undefined, async ({ i, dataSet }) => {
+        await dataSet.add(i, { id: 1, value: 'a' }, { id: 2, value: 'b' }, { id: 3, value: 'c' })
+        await dataSet.remove(i, 1, 3)
+        expect(await dataSet.count(i)).toBe(1)
+        expect((await dataSet.get(i, 2))?.value).toBe('b')
+      })
+    })
+
+    it('emits onEntityRemoved for each removed key', async () => {
+      await withDataSet(undefined, async ({ i, dataSet }) => {
+        const removedKeys: number[] = []
+        dataSet.addListener('onEntityRemoved', ({ key }) => {
+          removedKeys.push(key)
+        })
+        await dataSet.add(i, { id: 1, value: 'a' }, { id: 2, value: 'b' })
+        await dataSet.remove(i, 1, 2)
+        expect(removedKeys).toEqual([1, 2])
+      })
+    })
+
+    it('authorizes each entity when authorizeRemoveEntity is set', async () => {
+      const authorizeRemoveEntity = vi.fn(async () => ({ isAllowed: true, message: '' }) as AuthorizationResult)
+      await withDataSet({ authorizeRemoveEntity }, async ({ i, dataSet }) => {
+        await dataSet.add(i, { id: 1, value: 'a' }, { id: 2, value: 'b' })
+        await dataSet.remove(i, 1, 2)
+        expect(authorizeRemoveEntity).toHaveBeenCalledTimes(2)
+        expect(await dataSet.count(i)).toBe(0)
+      })
+    })
+
+    it('does not remove anything when authorizeRemoveEntity fails for one entity (all-or-nothing)', async () => {
+      const authorizeRemoveEntity = vi.fn(async ({ entity }: { entity: TestClass }) => {
+        if (entity.id === 2) {
+          return { isAllowed: false, message: 'forbidden' } as AuthorizationResult
+        }
+        return { isAllowed: true } as AuthorizationResult
+      })
+      await withDataSet({ authorizeRemoveEntity }, async ({ i, dataSet }) => {
+        await dataSet.add(i, { id: 1, value: 'a' }, { id: 2, value: 'b' }, { id: 3, value: 'c' })
+        await expect(dataSet.remove(i, 1, 2, 3)).rejects.toBeInstanceOf(AuthorizationError)
+        expect(await dataSet.count(i)).toBe(3)
+      })
+    })
+
+    it('no-ops when called without keys', async () => {
+      await withDataSet(undefined, async ({ i, dataSet }) => {
+        const listener = vi.fn()
+        dataSet.addListener('onEntityRemoved', listener)
+        await dataSet.remove(i)
+        expect(listener).not.toHaveBeenCalled()
+      })
+    })
+  })
+})

package/src/define-data-set.spec.ts

@@ -0,0 +1,145 @@
+import { defineStore, InMemoryStore } from '@furystack/core'
+import { createInjector } from '@furystack/inject'
+import { usingAsync } from '@furystack/utils'
+import { describe, expect, it, vi } from 'vitest'
+import { DataSet } from './data-set.js'
+import { defineDataSet } from './define-data-set.js'
+
+class Test {
+  declare id: number
+  declare value: string
+}
+
+// Store tokens are declared at module scope so TypeScript keeps the literal
+// primary-key narrowing. Wrapping `defineStore` in an arrow function would
+// widen the inferred `TPrimaryKey` back to `keyof Test` in the return type.
+const BasicStore = defineStore({
+  name: 'test/BasicStore',
+  model: Test,
+  primaryKey: 'id',
+  factory: () => new InMemoryStore({ model: Test, primaryKey: 'id' }),
+})
+const SingletonStore = defineStore({
+  name: 'test/SingletonStore',
+  model: Test,
+  primaryKey: 'id',
+  factory: () => new InMemoryStore({ model: Test, primaryKey: 'id' }),
+})
+const MetaStore = defineStore({
+  name: 'test/MetaStore',
+  model: Test,
+  primaryKey: 'id',
+  factory: () => new InMemoryStore({ model: Test, primaryKey: 'id' }),
+})
+const HooksStore = defineStore({
+  name: 'test/HooksStore',
+  model: Test,
+  primaryKey: 'id',
+  factory: () => new InMemoryStore({ model: Test, primaryKey: 'id' }),
+})
+const EventsStore = defineStore({
+  name: 'test/EventsStore',
+  model: Test,
+  primaryKey: 'id',
+  factory: () => new InMemoryStore({ model: Test, primaryKey: 'id' }),
+})
+const DisposeStore = defineStore({
+  name: 'test/DisposeStore',
+  model: Test,
+  primaryKey: 'id',
+  factory: () => new InMemoryStore({ model: Test, primaryKey: 'id' }),
+})
+const RebindStore = defineStore({
+  name: 'test/RebindStore',
+  model: Test,
+  primaryKey: 'id',
+  factory: () => new InMemoryStore({ model: Test, primaryKey: 'id' }),
+})
+
+const modifyOnAddSpy = vi.fn()
+const BasicDataSet = defineDataSet({ name: 'test/BasicDataSet', store: BasicStore })
+const SingletonDataSet = defineDataSet({ name: 'test/SingletonDataSet', store: SingletonStore })
+const MetaDataSet = defineDataSet({ name: 'test/MetaDataSet', store: MetaStore })
+// The `settings` callback participates in bidirectional inference against the
+// surrounding generics. Even with `NoInfer` on the settings position, inline
+// callbacks currently widen `TPrimaryKey` to `keyof T` because TypeScript has
+// to contextually type the callback before it can commit to the store-driven
+// inference. The runtime value of `token.primaryKey` is still correct; only
+// the entity parameter is typed as the wider `WithOptionalId<Test, keyof Test>`.
+// The non-null assertion on `entity.value` reflects that widening.
+const HooksDataSet = defineDataSet({
+  name: 'test/HooksDataSet',
+  store: HooksStore,
+  settings: {
+    modifyOnAdd: async ({ entity }) => {
+      modifyOnAddSpy()
+      return { ...entity, value: entity.value!.toUpperCase() }
+    },
+  },
+})
+const EventsDataSet = defineDataSet({ name: 'test/EventsDataSet', store: EventsStore })
+const DisposeDataSet = defineDataSet({ name: 'test/DisposeDataSet', store: DisposeStore })
+const RebindDataSet = defineDataSet({ name: 'test/RebindDataSet', store: RebindStore })
+
+describe('defineDataSet', () => {
+  it('resolves to a DataSet backed by the supplied store', async () => {
+    await usingAsync(createInjector(), async (i) => {
+      const ds = i.get(BasicDataSet)
+      expect(ds).toBeInstanceOf(DataSet)
+      expect(ds.settings.physicalStore).toBe(i.get(BasicStore))
+    })
+  })
+
+  it('caches the DataSet as a singleton across resolutions', async () => {
+    await usingAsync(createInjector(), async (i) => {
+      expect(i.get(SingletonDataSet)).toBe(i.get(SingletonDataSet))
+    })
+  })
+
+  it('mirrors the model and primary key from the backing store token', () => {
+    expect(MetaDataSet.model).toBe(Test)
+    expect(MetaDataSet.primaryKey).toBe('id')
+  })
+
+  it('applies the configured authorizers and hooks', async () => {
+    modifyOnAddSpy.mockClear()
+    await usingAsync(createInjector(), async (i) => {
+      const ds = i.get(HooksDataSet)
+      await ds.add(i, { id: 1, value: 'asd' })
+      const stored = await ds.get(i, 1)
+      expect(modifyOnAddSpy).toHaveBeenCalledTimes(1)
+      expect(stored?.value).toBe('ASD')
+    })
+  })
+
+  it('emits change events through the DataSet EventHub', async () => {
+    await usingAsync(createInjector(), async (i) => {
+      const added = vi.fn()
+      const ds = i.get(EventsDataSet)
+      ds.addListener('onEntityAdded', added)
+      await ds.add(i, { id: 1, value: 'x' })
+      expect(added).toHaveBeenCalledWith(expect.objectContaining({ entity: { id: 1, value: 'x' } }))
+    })
+  })
+
+  it('clears DataSet listeners when the injector is disposed', async () => {
+    const i = createInjector()
+    const ds = i.get(DisposeDataSet)
+    const listener = vi.fn()
+    ds.addListener('onEntityAdded', listener)
+    await i[Symbol.asyncDispose]()
+    // After disposal the DataSet's event subscriptions are cleared;
+    // emitting directly would be a no-op.
+    ds.emit('onEntityAdded', { injector: i, entity: { id: 1, value: 'x' } })
+    expect(listener).not.toHaveBeenCalled()
+  })
+
+  it('allows rebinding the backing store for tests', async () => {
+    await usingAsync(createInjector(), async (i) => {
+      const replacement = new InMemoryStore({ model: Test, primaryKey: 'id' })
+      i.bind(RebindStore, () => replacement)
+      const ds = i.get(RebindDataSet)
+      expect(ds.settings.physicalStore).toBe(replacement)
+    })
+  })
+})

package/src/define-data-set.ts

@@ -0,0 +1,140 @@
+import type { Constructable, PhysicalStore, StoreToken, WithOptionalId } from '@furystack/core'
+import type { ServiceContext, Token } from '@furystack/inject'
+import { defineService } from '@furystack/inject'
+import type { DataSetSettings } from './data-set-setting.js'
+import { DataSet } from './data-set.js'
+
+/**
+ * Resolves a {@link StoreToken} to a {@link PhysicalStore} whose
+ * `TWritableData` generic matches the owning data set. `StoreToken` defaults
+ * `TWritableData` to `WithOptionalId`, while a {@link DataSet} may narrow it
+ * (e.g. to strip system-owned fields). The write surface of `PhysicalStore`
+ * is contravariant in `TWritableData` — a store that accepts
+ * `WithOptionalId<T, TPK>` also accepts any narrower shape — but TypeScript
+ * cannot express that with the default generic, so the cast is localized
+ * here with this explanation rather than scattered at call sites.
+ */
+const resolvePhysicalStore = <T, TPrimaryKey extends keyof T, TWritableData>(
+  ctx: ServiceContext<'singleton'>,
+  store: StoreToken<T, TPrimaryKey>,
+): PhysicalStore<T, TPrimaryKey, TWritableData> =>
+  ctx.inject(store) as unknown as PhysicalStore<T, TPrimaryKey, TWritableData>
+
+/**
+ * A DI token that resolves to a {@link DataSet} and carries its model and
+ * primary key metadata (mirrored from the backing {@link StoreToken}).
+ *
+ * Consumers can `injector.get(token)` to obtain the dataset, or read the
+ * `model` / `primaryKey` fields to drive reflection-style tooling such as
+ * entity sync and OpenAPI generation.
+ */
+export type DataSetToken<T, TPrimaryKey extends keyof T, TWritableData = WithOptionalId<T, TPrimaryKey>> = Token<
+  DataSet<T, TPrimaryKey, TWritableData>,
+  'singleton'
+> & {
+  readonly model: Constructable<T>
+  readonly primaryKey: TPrimaryKey
+}
+
+/**
+ * Settings accepted by {@link defineDataSet}. A subset of
+ * {@link DataSetSettings}: the physical store is supplied by the store token
+ * and must not be passed here.
+ */
+export type DefineDataSetSettings<
+  T,
+  TPrimaryKey extends keyof T,
+  TWritableData = WithOptionalId<T, TPrimaryKey>,
+> = Omit<DataSetSettings<T, TPrimaryKey, TWritableData>, 'physicalStore'>
+
+/**
+ * Options accepted by {@link defineDataSet}.
+ *
+ * `settings` is wrapped in `NoInfer` so the `store` token alone fixes the
+ * generic parameters. Without it, an inline callback inside `settings`
+ * (e.g. a `modifyOnAdd` arrow) triggers bidirectional inference where
+ * TypeScript widens `TPrimaryKey` back to `keyof T` to satisfy the
+ * callback's contextual typing.
+ */
+export type DefineDataSetOptions<T, TPrimaryKey extends keyof T, TWritableData = WithOptionalId<T, TPrimaryKey>> = {
+  /**
+   * Human-readable identifier used for debug/readability. Token identity is
+   * established by the returned {@link DataSetToken} object reference.
+   */
+  name: string
+  /**
+   * The store this data set is backed by. Its `model` and `primaryKey` are
+   * propagated onto the returned token.
+   */
+  store: StoreToken<T, TPrimaryKey>
+  /**
+   * Authorizers, modification hooks and filter post-processors. Optional —
+   * a data set without settings performs no authorization and forwards
+   * operations straight to the physical store.
+   */
+  settings?: NoInfer<DefineDataSetSettings<T, TPrimaryKey, TWritableData>>
+}
+
+/**
+ * Defines a {@link DataSet} as a first-class DI token backed by a
+ * {@link StoreToken}.
+ *
+ * The returned token resolves to a singleton `DataSet`. On the first
+ * resolution the factory:
+ *
+ * 1. Resolves the backing physical store through the injector.
+ * 2. Constructs a {@link DataSet} with the supplied {@link DefineDataSetSettings}
+ *    and that store.
+ * 3. Registers a disposal callback that clears the DataSet's event
+ *    subscriptions when the owning injector is disposed.
+ *
+ * The token also carries the `model` and `primaryKey` of the backing store so
+ * that downstream tooling (entity sync, OpenAPI generators, test harnesses)
+ * can discover the dataset's shape without additional wiring.
+ *
+ * @example
+ * ```ts
+ * const UserStore = defineStore({
+ *   name: 'my-app/UserStore',
+ *   model: User,
+ *   primaryKey: 'username',
+ *   factory: () => new InMemoryStore({ model: User, primaryKey: 'username' }),
+ * })
+ *
+ * export const UserDataSet = defineDataSet({
+ *   name: 'my-app/UserDataSet',
+ *   store: UserStore,
+ *   settings: {
+ *     authorizeAdd: async ({ injector, entity }) => ({ isAllowed: true }),
+ *   },
+ * })
+ *
+ * const ds = injector.get(UserDataSet)
+ * await ds.add(injector, { username: 'alice', roles: [] })
+ * ```
+ */
+export const defineDataSet = <T, const TPrimaryKey extends keyof T, TWritableData = WithOptionalId<T, TPrimaryKey>>(
+  options: DefineDataSetOptions<T, TPrimaryKey, TWritableData>,
+): DataSetToken<T, TPrimaryKey, TWritableData> => {
+  const token = defineService({
+    name: options.name,
+    lifetime: 'singleton',
+    factory: (ctx: ServiceContext<'singleton'>) => {
+      const physicalStore = resolvePhysicalStore<T, TPrimaryKey, TWritableData>(ctx, options.store)
+      const dataSet = new DataSet<T, TPrimaryKey, TWritableData>({
+        ...options.settings,
+        physicalStore,
+      } as DataSetSettings<T, TPrimaryKey, TWritableData>)
+      // Disposal is delegated to the injector via `onDispose`; the dataset
+      // outlives this factory invocation and is torn down on scope teardown.
+      // eslint-disable-next-line furystack/prefer-using-wrapper
+      ctx.onDispose(() => dataSet[Symbol.dispose]())
+      return dataSet
+    },
+  })
+  const result: DataSetToken<T, TPrimaryKey, TWritableData> = Object.assign(token, {
+    model: options.store.model,
+    primaryKey: options.store.primaryKey,
+  })
+  return result
+}