@furystack/repository 10.0.36 → 10.0.37

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## [10.0.37] - 2026-02-19
+
+### 📚 Documentation
+
+- Expanded JSDoc on `DataSet` class to explain its role as the authorized write gateway with event dispatching
+- Expanded JSDoc on `add()`, `update()`, and `remove()` to document authorization checks, hooks, and emitted events
+- Expanded JSDoc on `getDataSetFor()` with usage examples for server-side writes using `useSystemIdentityContext`
+- Added README section covering server-side writes with the elevated `IdentityContext`, including a warning about bypassing the DataSet layer
+
+### ⬆️ Dependencies
+
+- Updated `@furystack/core`
+
 ## [10.0.36] - 2026-02-11
 
 ### ⬆️ Dependencies

package/README.md

@@ -70,3 +70,27 @@ There is an additional property called `addFilter`, you can use that to add a pr
 ### Getting the Context
 
 All methods above have an _injector instance_ on the call parameter - you can use that injector to get service instances from the right caller context. It means that you can use e.g. HttpUserContext to get the current user.
+
+### Server-side writes and the elevated IdentityContext
+
+The DataSet is the **recommended write gateway** for all entity mutations. Writing through the DataSet ensures that authorization rules, modification hooks, and change events (`onEntityAdded`, `onEntityUpdated`, `onEntityRemoved`) are all triggered. These events are required for features like [entity sync](./../entity-sync-service/README.md) to work correctly.
+
+> **Warning:** Writing directly to the underlying physical store bypasses the DataSet layer entirely. No authorization checks, hooks, or events will fire, and downstream consumers (such as entity sync) will **not** be notified of the change.
+
+For server-side or background operations that don't originate from an HTTP request (e.g. scheduled jobs, migrations, seed scripts), you won't have a user session. Use `useSystemIdentityContext` from `@furystack/core` to create a scoped child injector with elevated privileges:
+
+```ts
+import { useSystemIdentityContext } from '@furystack/core'
+import { getDataSetFor } from '@furystack/repository'
+import { usingAsync } from '@furystack/utils'
+
+await usingAsync(useSystemIdentityContext({ injector, username: 'background-job' }), async (systemInjector) => {
+  const dataSet = getDataSetFor(systemInjector, MyModel, 'id')
+  await dataSet.add(systemInjector, { value: 'created by background job' })
+})
+// systemInjector is disposed here -- all scoped instances cleaned up
+```
+
+> **Warning:** `useSystemIdentityContext` bypasses **all** authorization checks. Only use it in trusted server-side contexts. Never pass the returned injector to user-facing request handlers.
+
+This pattern ensures that all writes go through the same pipeline, keeping authorization, hooks, and event-driven features consistent regardless of the caller.

package/esm/data-set.d.ts

@@ -3,7 +3,33 @@ import type { Injector } from '@furystack/inject';
 import { EventHub } from '@furystack/utils';
 import type { DataSetSettings } from './data-set-setting.js';
 /**
- * An authorized Repository Store instance
+ * An authorized Repository Store instance that wraps a {@link PhysicalStore} with authorization,
+ * modification hooks, and event dispatching.
+ *
+ * The DataSet is the **recommended write gateway** for all entity mutations. Writing through the DataSet
+ * ensures that authorization rules are enforced, modification hooks are applied, and change events
+ * (`onEntityAdded`, `onEntityUpdated`, `onEntityRemoved`) are emitted -- which are required for features
+ * like entity sync to function correctly.
+ *
+ * All mutating methods require an `injector` parameter that provides the caller's context (e.g. the current
+ * user's identity). 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.
+ *
+ * @example
+ * ```ts
+ * import { useSystemIdentityContext } from '@furystack/core'
+ * import { getDataSetFor } from '@furystack/repository'
+ * import { usingAsync } from '@furystack/utils'
+ *
+ * // Server-side write with an elevated identity
+ * await usingAsync(
+ *   useSystemIdentityContext({ injector, username: 'background-job' }),
+ *   async (systemInjector) => {
+ *     const dataSet = getDataSetFor(systemInjector, MyModel, 'id')
+ *     await dataSet.add(systemInjector, newEntity)
+ *   },
+ * )
+ * ```
  */
 export declare class DataSet<T, TPrimaryKey extends keyof T, TWritableData = WithOptionalId<T, TPrimaryKey>> extends EventHub<{
     onEntityAdded: {
@@ -26,15 +52,21 @@ export declare class DataSet<T, TPrimaryKey extends keyof T, TWritableData = Wit
      */
     primaryKey: TPrimaryKey;
     /**
-     * Adds an entity to the DataSet
-     * @param injector The injector from the context
+     * Adds an entity to the DataSet.
+     * Runs authorization checks, applies modification hooks, persists to the physical store,
+     * and emits an `onEntityAdded` event for each created entity.
+     * @param injector The injector from the caller's context. For server-side or background operations
+     *   without an HTTP request, use a child injector with an elevated {@link IdentityContext}.
      * @param entities The entities to add
      * @returns The CreateResult with the created entities
      */
     add(injector: Injector, ...entities: TWritableData[]): Promise<CreateResult<T>>;
     /**
-     * Updates an entity in the store
-     * @param injector The injector from the context
+     * Updates an entity in the store.
+     * Runs authorization checks, applies modification hooks, persists to the physical store,
+     * and emits an `onEntityUpdated` event.
+     * @param injector The injector from the caller's context. For server-side or background operations
+     *   without an HTTP request, use a child injector with an elevated {@link IdentityContext}.
      * @param id The identifier of the entity
      * @param change The update
      */
@@ -62,8 +94,11 @@ export declare class DataSet<T, TPrimaryKey extends keyof T, TWritableData = Wit
      */
     get(injector: Injector, key: T[TPrimaryKey], select?: Array<keyof T>): Promise<PartialResult<T, (keyof T)[]> | undefined>;
     /**
-     * Removes an entity based on its primary key
-     * @param injector The Injector from the context
+     * Removes an entity based on its primary key.
+     * Runs authorization checks, persists to the physical store,
+     * and emits an `onEntityRemoved` event.
+     * @param injector The injector from the caller's context. For server-side or background operations
+     *   without an HTTP request, use a child injector with an elevated {@link IdentityContext}.
      * @param key The primary key
      * @returns A promise that will be resolved / rejected based on the remove success
      */

package/esm/data-set.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"data-set.d.ts","sourceRoot":"","sources":["../src/data-set.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,WAAW,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAE3G,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAA;AACjD,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAA;AAC3C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAA;AAE5D;;GAEG;AACH,qBAAa,OAAO,CAAC,CAAC,EAAE,WAAW,SAAS,MAAM,CAAC,EAAE,aAAa,GAAG,cAAc,CAAC,CAAC,EAAE,WAAW,CAAC,CACjG,SAAQ,QAAQ,CAAC;IACf,aAAa,EAAE;QAAE,QAAQ,EAAE,QAAQ,CAAC;QAAC,MAAM,EAAE,CAAC,CAAA;KAAE,CAAA;IAChD,eAAe,EAAE;QAAE,QAAQ,EAAE,QAAQ,CAAC;QAAC,EAAE,EAAE,CAAC,CAAC,WAAW,CAAC,CAAC;QAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,CAAA;KAAE,CAAA;IAC/E,eAAe,EAAE;QAAE,QAAQ,EAAE,QAAQ,CAAC;QAAC,GAAG,EAAE,CAAC,CAAC,WAAW,CAAC,CAAA;KAAE,CAAA;CAC7D,CACD,YAAW,UAAU;aAyJO,QAAQ,EAAE,eAAe,CAAC,CAAC,EAAE,WAAW,EAAE,aAAa,CAAC;IAvJpF;;OAEG;IACI,UAAU,EAAE,WAAW,CAAA;IAE9B;;;;;OAKG;IACU,GAAG,CAAC,QAAQ,EAAE,QAAQ,EAAE,GAAG,QAAQ,EAAE,aAAa,EAAE,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;IAyB5F;;;;;OAKG;IACU,MAAM,CAAC,QAAQ,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC,CAAC,WAAW,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAuB9F;;;;;OAKG;IACU,KAAK,CAAC,QAAQ,EAAE,QAAQ,EAAE,MAAM,CAAC,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC;IAU/E;;;;;OAKG;IACU,IAAI,CAAC,OAAO,SAAS,KAAK,CAAC,MAAM,CAAC,CAAC,EAC9C,QAAQ,EAAE,QAAQ,EAClB,MAAM,EAAE,WAAW,CAAC,CAAC,EAAE,OAAO,CAAC,GAC9B,OAAO,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC;IAW5C;;;;;;OAMG;IACU,GAAG,CAAC,QAAQ,EAAE,QAAQ,EAAE,GAAG,EAAE,CAAC,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IAiBjF;;;;;OAKG;IACU,MAAM,CAAC,QAAQ,EAAE,QAAQ,EAAE,GAAG,EAAE,CAAC,CAAC,WAAW,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;gBAoB/C,QAAQ,EAAE,eAAe,CAAC,CAAC,EAAE,WAAW,EAAE,aAAa,CAAC;CAIrF"}
+{"version":3,"file":"data-set.d.ts","sourceRoot":"","sources":["../src/data-set.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,WAAW,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAE3G,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAA;AACjD,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAA;AAC3C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAA;AAE5D;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,qBAAa,OAAO,CAAC,CAAC,EAAE,WAAW,SAAS,MAAM,CAAC,EAAE,aAAa,GAAG,cAAc,CAAC,CAAC,EAAE,WAAW,CAAC,CACjG,SAAQ,QAAQ,CAAC;IACf,aAAa,EAAE;QAAE,QAAQ,EAAE,QAAQ,CAAC;QAAC,MAAM,EAAE,CAAC,CAAA;KAAE,CAAA;IAChD,eAAe,EAAE;QAAE,QAAQ,EAAE,QAAQ,CAAC;QAAC,EAAE,EAAE,CAAC,CAAC,WAAW,CAAC,CAAC;QAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,CAAA;KAAE,CAAA;IAC/E,eAAe,EAAE;QAAE,QAAQ,EAAE,QAAQ,CAAC;QAAC,GAAG,EAAE,CAAC,CAAC,WAAW,CAAC,CAAA;KAAE,CAAA;CAC7D,CACD,YAAW,UAAU;aAkKO,QAAQ,EAAE,eAAe,CAAC,CAAC,EAAE,WAAW,EAAE,aAAa,CAAC;IAhKpF;;OAEG;IACI,UAAU,EAAE,WAAW,CAAA;IAE9B;;;;;;;;OAQG;IACU,GAAG,CAAC,QAAQ,EAAE,QAAQ,EAAE,GAAG,QAAQ,EAAE,aAAa,EAAE,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;IAyB5F;;;;;;;;OAQG;IACU,MAAM,CAAC,QAAQ,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC,CAAC,WAAW,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAuB9F;;;;;OAKG;IACU,KAAK,CAAC,QAAQ,EAAE,QAAQ,EAAE,MAAM,CAAC,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC;IAU/E;;;;;OAKG;IACU,IAAI,CAAC,OAAO,SAAS,KAAK,CAAC,MAAM,CAAC,CAAC,EAC9C,QAAQ,EAAE,QAAQ,EAClB,MAAM,EAAE,WAAW,CAAC,CAAC,EAAE,OAAO,CAAC,GAC9B,OAAO,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC;IAW5C;;;;;;OAMG;IACU,GAAG,CAAC,QAAQ,EAAE,QAAQ,EAAE,GAAG,EAAE,CAAC,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IAiBjF;;;;;;;;OAQG;IACU,MAAM,CAAC,QAAQ,EAAE,QAAQ,EAAE,GAAG,EAAE,CAAC,CAAC,WAAW,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;gBAoB/C,QAAQ,EAAE,eAAe,CAAC,CAAC,EAAE,WAAW,EAAE,aAAa,CAAC;CAIrF"}

package/esm/data-set.js

@@ -1,7 +1,33 @@
 import { AuthorizationError } from '@furystack/core';
 import { EventHub } from '@furystack/utils';
 /**
- * An authorized Repository Store instance
+ * An authorized Repository Store instance that wraps a {@link PhysicalStore} with authorization,
+ * modification hooks, and event dispatching.
+ *
+ * The DataSet is the **recommended write gateway** for all entity mutations. Writing through the DataSet
+ * ensures that authorization rules are enforced, modification hooks are applied, and change events
+ * (`onEntityAdded`, `onEntityUpdated`, `onEntityRemoved`) are emitted -- which are required for features
+ * like entity sync to function correctly.
+ *
+ * All mutating methods require an `injector` parameter that provides the caller's context (e.g. the current
+ * user's identity). 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.
+ *
+ * @example
+ * ```ts
+ * import { useSystemIdentityContext } from '@furystack/core'
+ * import { getDataSetFor } from '@furystack/repository'
+ * import { usingAsync } from '@furystack/utils'
+ *
+ * // Server-side write with an elevated identity
+ * await usingAsync(
+ *   useSystemIdentityContext({ injector, username: 'background-job' }),
+ *   async (systemInjector) => {
+ *     const dataSet = getDataSetFor(systemInjector, MyModel, 'id')
+ *     await dataSet.add(systemInjector, newEntity)
+ *   },
+ * )
+ * ```
  */
 export class DataSet extends EventHub {
     settings;
@@ -10,8 +36,11 @@ export class DataSet extends EventHub {
      */
     primaryKey;
     /**
-     * Adds an entity to the DataSet
-     * @param injector The injector from the context
+     * Adds an entity to the DataSet.
+     * Runs authorization checks, applies modification hooks, persists to the physical store,
+     * and emits an `onEntityAdded` event for each created entity.
+     * @param injector The injector from the caller's context. For server-side or background operations
+     *   without an HTTP request, use a child injector with an elevated {@link IdentityContext}.
      * @param entities The entities to add
      * @returns The CreateResult with the created entities
      */
@@ -34,8 +63,11 @@ export class DataSet extends EventHub {
         return createResult;
     }
     /**
-     * Updates an entity in the store
-     * @param injector The injector from the context
+     * Updates an entity in the store.
+     * Runs authorization checks, applies modification hooks, persists to the physical store,
+     * and emits an `onEntityUpdated` event.
+     * @param injector The injector from the caller's context. For server-side or background operations
+     *   without an HTTP request, use a child injector with an elevated {@link IdentityContext}.
      * @param id The identifier of the entity
      * @param change The update
      */
@@ -116,8 +148,11 @@ export class DataSet extends EventHub {
         return instance;
     }
     /**
-     * Removes an entity based on its primary key
-     * @param injector The Injector from the context
+     * Removes an entity based on its primary key.
+     * Runs authorization checks, persists to the physical store,
+     * and emits an `onEntityRemoved` event.
+     * @param injector The injector from the caller's context. For server-side or background operations
+     *   without an HTTP request, use a child injector with an elevated {@link IdentityContext}.
      * @param key The primary key
      * @returns A promise that will be resolved / rejected based on the remove success
      */

package/esm/data-set.js.map

@@ -1 +1 @@
-{"version":3,"file":"data-set.js","sourceRoot":"","sources":["../src/data-set.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"data-set.js","sourceRoot":"","sources":["../src/data-set.ts"],"names":[],"mappings":"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"}

package/esm/helpers.d.ts

@@ -7,11 +7,35 @@ import { Repository } from './repository.js';
  */
 export declare const getRepository: (injector: Injector) => Repository;
 /**
- * Gets a DataSet for a specific model from the 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
+ *
+ * @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)
+ *   },
+ * )
+ * ```
  */
 export declare const getDataSetFor: <T, TPrimaryKey extends keyof T>(injector: Injector, model: Constructable<T>, primaryKey: TPrimaryKey) => import("./data-set.js").DataSet<T, TPrimaryKey, import("@furystack/core").WithOptionalId<T, TPrimaryKey>>;
 //# sourceMappingURL=helpers.d.ts.map

package/esm/helpers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../src/helpers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAA;AAChE,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AAE5C;;;;GAIG;AACH,eAAO,MAAM,aAAa,GAAI,UAAU,QAAQ,eAAqC,CAAA;AAErF;;;;;;GAMG;AACH,eAAO,MAAM,aAAa,GAAI,CAAC,EAAE,WAAW,SAAS,MAAM,CAAC,EAC1D,UAAU,QAAQ,EAClB,OAAO,aAAa,CAAC,CAAC,CAAC,EACvB,YAAY,WAAW,8GAC6C,CAAA"}
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../src/helpers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAA;AAChE,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AAE5C;;;;GAIG;AACH,eAAO,MAAM,aAAa,GAAI,UAAU,QAAQ,eAAqC,CAAA;AAErF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,eAAO,MAAM,aAAa,GAAI,CAAC,EAAE,WAAW,SAAS,MAAM,CAAC,EAC1D,UAAU,QAAQ,EAClB,OAAO,aAAa,CAAC,CAAC,CAAC,EACvB,YAAY,WAAW,8GAC6C,CAAA"}

package/esm/helpers.js

@@ -6,11 +6,35 @@ import { Repository } from './repository.js';
  */
 export const getRepository = (injector) => injector.getInstance(Repository);
 /**
- * Gets a DataSet for a specific model from the 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
+ *
+ * @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)
+ *   },
+ * )
+ * ```
  */
 export const getDataSetFor = (injector, model, primaryKey) => injector.getInstance(Repository).getDataSetFor(model, primaryKey);
 //# sourceMappingURL=helpers.js.map

package/esm/helpers.js.map

@@ -1 +1 @@
-{"version":3,"file":"helpers.js","sourceRoot":"","sources":["../src/helpers.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AAE5C;;;;GAIG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,QAAkB,EAAE,EAAE,CAAC,QAAQ,CAAC,WAAW,CAAC,UAAU,CAAC,CAAA;AAErF;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,CAC3B,QAAkB,EAClB,KAAuB,EACvB,UAAuB,EACvB,EAAE,CAAC,QAAQ,CAAC,WAAW,CAAC,UAAU,CAAC,CAAC,aAAa,CAAC,KAAK,EAAE,UAAU,CAAC,CAAA"}
+{"version":3,"file":"helpers.js","sourceRoot":"","sources":["../src/helpers.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AAE5C;;;;GAIG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,QAAkB,EAAE,EAAE,CAAC,QAAQ,CAAC,WAAW,CAAC,UAAU,CAAC,CAAA;AAErF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,CAC3B,QAAkB,EAClB,KAAuB,EACvB,UAAuB,EACvB,EAAE,CAAC,QAAQ,CAAC,WAAW,CAAC,UAAU,CAAC,CAAC,aAAa,CAAC,KAAK,EAAE,UAAU,CAAC,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@furystack/repository",
-  "version": "10.0.36",
+  "version": "10.0.37",
   "description": "Repository implementation for FuryStack",
   "type": "module",
   "scripts": {
@@ -38,7 +38,7 @@
   },
   "homepage": "https://github.com/furystack/furystack",
   "dependencies": {
-    "@furystack/core": "^15.0.36",
+    "@furystack/core": "^15.1.0",
     "@furystack/inject": "^12.0.30",
     "@furystack/utils": "^8.1.10"
   },

package/src/data-set.ts

@@ -5,7 +5,33 @@ import { EventHub } from '@furystack/utils'
 import type { DataSetSettings } from './data-set-setting.js'
 
 /**
- * An authorized Repository Store instance
+ * An authorized Repository Store instance that wraps a {@link PhysicalStore} with authorization,
+ * modification hooks, and event dispatching.
+ *
+ * The DataSet is the **recommended write gateway** for all entity mutations. Writing through the DataSet
+ * ensures that authorization rules are enforced, modification hooks are applied, and change events
+ * (`onEntityAdded`, `onEntityUpdated`, `onEntityRemoved`) are emitted -- which are required for features
+ * like entity sync to function correctly.
+ *
+ * All mutating methods require an `injector` parameter that provides the caller's context (e.g. the current
+ * user's identity). 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.
+ *
+ * @example
+ * ```ts
+ * import { useSystemIdentityContext } from '@furystack/core'
+ * import { getDataSetFor } from '@furystack/repository'
+ * import { usingAsync } from '@furystack/utils'
+ *
+ * // Server-side write with an elevated identity
+ * await usingAsync(
+ *   useSystemIdentityContext({ injector, username: 'background-job' }),
+ *   async (systemInjector) => {
+ *     const dataSet = getDataSetFor(systemInjector, MyModel, 'id')
+ *     await dataSet.add(systemInjector, newEntity)
+ *   },
+ * )
+ * ```
  */
 export class DataSet<T, TPrimaryKey extends keyof T, TWritableData = WithOptionalId<T, TPrimaryKey>>
   extends EventHub<{
@@ -21,8 +47,11 @@ export class DataSet<T, TPrimaryKey extends keyof T, TWritableData = WithOptiona
   public primaryKey: TPrimaryKey
 
   /**
-   * Adds an entity to the DataSet
-   * @param injector The injector from the context
+   * Adds an entity to the DataSet.
+   * Runs authorization checks, applies modification hooks, persists to the physical store,
+   * and emits an `onEntityAdded` event for each created entity.
+   * @param injector The injector from the caller's context. For server-side or background operations
+   *   without an HTTP request, use a child injector with an elevated {@link IdentityContext}.
    * @param entities The entities to add
    * @returns The CreateResult with the created entities
    */
@@ -52,8 +81,11 @@ export class DataSet<T, TPrimaryKey extends keyof T, TWritableData = WithOptiona
   }
 
   /**
-   * Updates an entity in the store
-   * @param injector The injector from the context
+   * Updates an entity in the store.
+   * Runs authorization checks, applies modification hooks, persists to the physical store,
+   * and emits an `onEntityUpdated` event.
+   * @param injector The injector from the caller's context. For server-side or background operations
+   *   without an HTTP request, use a child injector with an elevated {@link IdentityContext}.
    * @param id The identifier of the entity
    * @param change The update
    */
@@ -141,8 +173,11 @@ export class DataSet<T, TPrimaryKey extends keyof T, TWritableData = WithOptiona
   }
 
   /**
-   * Removes an entity based on its primary key
-   * @param injector The Injector from the context
+   * Removes an entity based on its primary key.
+   * Runs authorization checks, persists to the physical store,
+   * and emits an `onEntityRemoved` event.
+   * @param injector The injector from the caller's context. For server-side or background operations
+   *   without an HTTP request, use a child injector with an elevated {@link IdentityContext}.
    * @param key The primary key
    * @returns A promise that will be resolved / rejected based on the remove success
    */

package/src/helpers.ts

@@ -9,11 +9,35 @@ import { Repository } from './repository.js'
 export const getRepository = (injector: Injector) => injector.getInstance(Repository)
 
 /**
- * Gets a DataSet for a specific model from the 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
+ *
+ * @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)
+ *   },
+ * )
+ * ```
  */
 export const getDataSetFor = <T, TPrimaryKey extends keyof T>(
   injector: Injector,