@furystack/repository 10.1.11 → 11.0.1

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,122 @@
+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>> = {
+  /**
+   * Debug-only identifier. Token identity is established by the returned
+   * {@link DataSetToken} object reference, not this string.
+   */
+  name: string
+  /** Backing store; its `model` and `primaryKey` propagate to the returned token. */
+  store: StoreToken<T, TPrimaryKey>
+  settings?: NoInfer<DefineDataSetSettings<T, TPrimaryKey, TWritableData>>
+}
+
+/**
+ * Defines a singleton {@link DataSet} token backed by a {@link StoreToken}.
+ * The token mirrors the store's `model` and `primaryKey` so reflection
+ * tools (entity sync, OpenAPI generators, test harnesses) can discover the
+ * dataset's shape from the token alone. Disposal of the owning injector
+ * tears down the dataset's event subscriptions.
+ *
+ * @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,
+      })
+      // 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
+}

package/src/helpers.ts

@@ -1,46 +1,27 @@
-import type { Constructable, Injector } from '@furystack/inject'
-import { Repository } from './repository.js'
+import type { WithOptionalId } from '@furystack/core'
+import type { Injector } from '@furystack/inject'
+import type { DataSet } from './data-set.js'
+import type { DataSetToken } from './define-data-set.js'
 
 /**
- * Returns a Repository on an injector
- * @param injector The Injector instance
- * @returns The Repository instance
- */
-export const getRepository = (injector: Injector) => injector.getInstance(Repository)
-
-/**
- * Gets a DataSet for a specific model from the repository.
- *
- * The DataSet is the recommended way to perform all entity mutations (add, update, remove).
- * Writing through the DataSet ensures that authorization, modification hooks, and change events
- * are properly triggered -- which is required for features like entity sync.
- *
- * For server-side or background operations that don't originate from an HTTP request,
- * use {@link useSystemIdentityContext} to create a scoped child injector with elevated privileges.
- *
- * @param injector The Injector instance
- * @param model The Model
- * @param primaryKey The Primary Key field
- * @returns A Repository DataSet for a specific model
+ * Resolves the {@link DataSet} for `token` on `injector`. The preferred
+ * write gateway for application code — `furystack/no-direct-store-token`
+ * forbids resolving the underlying `StoreToken` directly. For server-side
+ * or background work, wrap `injector` with `useSystemIdentityContext` from
+ * `@furystack/core` to obtain an elevated identity before calling this.
  *
  * @example
  * ```ts
- * import { useSystemIdentityContext } from '@furystack/core'
- * import { getDataSetFor } from '@furystack/repository'
- * import { usingAsync } from '@furystack/utils'
- *
- * // In a background job or service
  * await usingAsync(
  *   useSystemIdentityContext({ injector, username: 'background-job' }),
  *   async (systemInjector) => {
- *     const dataSet = getDataSetFor(systemInjector, MyModel, 'id')
- *     await dataSet.add(systemInjector, newEntity)
+ *     const dataSet = getDataSetFor(systemInjector, UserDataSet)
+ *     await dataSet.add(systemInjector, { username: 'alice', roles: [] })
  *   },
  * )
  * ```
  */
-export const getDataSetFor = <T, TPrimaryKey extends keyof T>(
+export const getDataSetFor = <T, TPrimaryKey extends keyof T, TWritableData = WithOptionalId<T, TPrimaryKey>>(
   injector: Injector,
-  model: Constructable<T>,
-  primaryKey: TPrimaryKey,
-) => injector.getInstance(Repository).getDataSetFor(model, primaryKey)
+  token: DataSetToken<T, TPrimaryKey, TWritableData>,
+): DataSet<T, TPrimaryKey, TWritableData> => injector.get(token)

package/src/index.ts

@@ -1,4 +1,4 @@
-export * from './repository.js'
-export * from './data-set.js'
 export * from './data-set-setting.js'
+export * from './data-set.js'
+export * from './define-data-set.js'
 export * from './helpers.js'

package/esm/dataset.spec.d.ts

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=dataset.spec.d.ts.map

package/esm/dataset.spec.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"dataset.spec.d.ts","sourceRoot":"","sources":["../src/dataset.spec.ts"],"names":[],"mappings":""}