@furystack/core 15.0.36 → 15.2.0

package/esm/models/physical-store.d.ts

@@ -62,7 +62,14 @@ export interface FindOptions<T, TSelect extends Array<keyof T>> {
 export type PartialResult<T, TFields extends Array<keyof T>> = Pick<T, TFields[number]>;
 export declare const selectFields: <T extends object, TField extends Array<keyof T>>(entry: T, ...fields: TField) => PartialResult<T, TField>;
 /**
- * Interface that defines a physical store implementation
+ * Interface that defines a physical store implementation.
+ *
+ * **Important:** Writing directly to a physical store bypasses the Repository {@link DataSet} layer.
+ * This means authorization, modification hooks, and DataSet events (used by entity sync) will **not** be triggered.
+ * For any write operation that should be observable by other parts of the system (e.g. entity sync, audit logging),
+ * use the corresponding {@link DataSet} method instead via `getDataSetFor()`.
+ *
+ * @see {@link DataSet} for the authorized, event-emitting write gateway
  */
 export interface PhysicalStore<T, TPrimaryKey extends keyof T, TWriteableData = WithOptionalId<T, TPrimaryKey>> extends EventHub<{
     onEntityAdded: {

package/esm/models/physical-store.d.ts.map

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

package/esm/system-identity-context.d.ts

@@ -0,0 +1,68 @@
+import type { Injector } from '@furystack/inject';
+import { IdentityContext } from './identity-context.js';
+import type { User } from './models/user.js';
+/**
+ * An elevated {@link IdentityContext} that is always authenticated and authorized.
+ * Intended for trusted server-side operations such as background jobs, migrations, and seed scripts.
+ *
+ * **Warning:** This context bypasses **all** authorization checks. Never use it in user-facing
+ * request pipelines or any context where untrusted input could reach the DataSet.
+ * Prefer {@link useSystemIdentityContext} for scoped usage with automatic cleanup.
+ *
+ * @example
+ * ```ts
+ * import { useSystemIdentityContext } from '@furystack/core'
+ * import { getDataSetFor } from '@furystack/repository'
+ * import { usingAsync } from '@furystack/utils'
+ *
+ * await usingAsync(
+ *   useSystemIdentityContext({ injector, username: 'migration-job' }),
+ *   async (systemInjector) => {
+ *     const dataSet = getDataSetFor(systemInjector, MyModel, 'id')
+ *     await dataSet.add(systemInjector, newEntity)
+ *   },
+ * )
+ * ```
+ */
+export declare class SystemIdentityContext extends IdentityContext {
+    private readonly username;
+    constructor(options?: {
+        username?: string;
+    });
+    isAuthenticated(): Promise<boolean>;
+    isAuthorized(..._roles: string[]): Promise<boolean>;
+    getCurrentUser<TUser extends User>(): Promise<TUser>;
+}
+/**
+ * Creates a scoped child injector with an elevated {@link SystemIdentityContext}.
+ * The returned injector is {@link AsyncDisposable} and works with `usingAsync()` for automatic cleanup.
+ *
+ * **Warning:** The returned injector bypasses **all** authorization checks. Only use this in trusted
+ * server-side contexts (background jobs, migrations, seed scripts). Never pass the returned injector
+ * to user-facing request handlers.
+ *
+ * @param options.injector The parent injector to create a child from
+ * @param options.username The username for the system identity (defaults to `'system'`)
+ * @returns A child injector with the SystemIdentityContext set as the IdentityContext
+ *
+ * @example
+ * ```ts
+ * import { useSystemIdentityContext } from '@furystack/core'
+ * import { getDataSetFor } from '@furystack/repository'
+ * import { usingAsync } from '@furystack/utils'
+ *
+ * await usingAsync(
+ *   useSystemIdentityContext({ injector, username: 'seed-script' }),
+ *   async (systemInjector) => {
+ *     const dataSet = getDataSetFor(systemInjector, MyModel, 'id')
+ *     await dataSet.add(systemInjector, { value: 'seeded' })
+ *   },
+ * )
+ * // systemInjector is disposed here -- all scoped instances cleaned up
+ * ```
+ */
+export declare const useSystemIdentityContext: (options: {
+    injector: Injector;
+    username?: string;
+}) => Injector;
+//# sourceMappingURL=system-identity-context.d.ts.map

package/esm/system-identity-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"system-identity-context.d.ts","sourceRoot":"","sources":["../src/system-identity-context.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAA;AAEjD,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAA;AACvD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAA;AAE5C;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,qBAAsB,SAAQ,eAAe;IACxD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAQ;gBAErB,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE;IAK3B,eAAe;IAIf,YAAY,CAAC,GAAG,MAAM,EAAE,MAAM,EAAE;IAIhC,cAAc,CAAC,KAAK,SAAS,IAAI,KAAK,OAAO,CAAC,KAAK,CAAC;CAGrE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,eAAO,MAAM,wBAAwB,GAAI,SAAS;IAAE,QAAQ,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,KAAG,QAK7F,CAAA"}

package/esm/system-identity-context.js

@@ -0,0 +1,75 @@
+import { IdentityContext } from './identity-context.js';
+/**
+ * An elevated {@link IdentityContext} that is always authenticated and authorized.
+ * Intended for trusted server-side operations such as background jobs, migrations, and seed scripts.
+ *
+ * **Warning:** This context bypasses **all** authorization checks. Never use it in user-facing
+ * request pipelines or any context where untrusted input could reach the DataSet.
+ * Prefer {@link useSystemIdentityContext} for scoped usage with automatic cleanup.
+ *
+ * @example
+ * ```ts
+ * import { useSystemIdentityContext } from '@furystack/core'
+ * import { getDataSetFor } from '@furystack/repository'
+ * import { usingAsync } from '@furystack/utils'
+ *
+ * await usingAsync(
+ *   useSystemIdentityContext({ injector, username: 'migration-job' }),
+ *   async (systemInjector) => {
+ *     const dataSet = getDataSetFor(systemInjector, MyModel, 'id')
+ *     await dataSet.add(systemInjector, newEntity)
+ *   },
+ * )
+ * ```
+ */
+export class SystemIdentityContext extends IdentityContext {
+    username;
+    constructor(options) {
+        super();
+        this.username = options?.username ?? 'system';
+    }
+    isAuthenticated() {
+        return Promise.resolve(true);
+    }
+    isAuthorized(..._roles) {
+        return Promise.resolve(true);
+    }
+    getCurrentUser() {
+        return Promise.resolve({ username: this.username, roles: [] });
+    }
+}
+/**
+ * Creates a scoped child injector with an elevated {@link SystemIdentityContext}.
+ * The returned injector is {@link AsyncDisposable} and works with `usingAsync()` for automatic cleanup.
+ *
+ * **Warning:** The returned injector bypasses **all** authorization checks. Only use this in trusted
+ * server-side contexts (background jobs, migrations, seed scripts). Never pass the returned injector
+ * to user-facing request handlers.
+ *
+ * @param options.injector The parent injector to create a child from
+ * @param options.username The username for the system identity (defaults to `'system'`)
+ * @returns A child injector with the SystemIdentityContext set as the IdentityContext
+ *
+ * @example
+ * ```ts
+ * import { useSystemIdentityContext } from '@furystack/core'
+ * import { getDataSetFor } from '@furystack/repository'
+ * import { usingAsync } from '@furystack/utils'
+ *
+ * await usingAsync(
+ *   useSystemIdentityContext({ injector, username: 'seed-script' }),
+ *   async (systemInjector) => {
+ *     const dataSet = getDataSetFor(systemInjector, MyModel, 'id')
+ *     await dataSet.add(systemInjector, { value: 'seeded' })
+ *   },
+ * )
+ * // systemInjector is disposed here -- all scoped instances cleaned up
+ * ```
+ */
+export const useSystemIdentityContext = (options) => {
+    const ctx = new SystemIdentityContext({ username: options.username });
+    const childInjector = options.injector.createChild({ owner: 'SystemIdentityContext' });
+    childInjector.setExplicitInstance(ctx, IdentityContext);
+    return childInjector;
+};
+//# sourceMappingURL=system-identity-context.js.map

package/esm/system-identity-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"system-identity-context.js","sourceRoot":"","sources":["../src/system-identity-context.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAA;AAGvD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,OAAO,qBAAsB,SAAQ,eAAe;IACvC,QAAQ,CAAQ;IAEjC,YAAY,OAA+B;QACzC,KAAK,EAAE,CAAA;QACP,IAAI,CAAC,QAAQ,GAAG,OAAO,EAAE,QAAQ,IAAI,QAAQ,CAAA;IAC/C,CAAC;IAEe,eAAe;QAC7B,OAAO,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,CAAA;IAC9B,CAAC;IAEe,YAAY,CAAC,GAAG,MAAgB;QAC9C,OAAO,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,CAAA;IAC9B,CAAC;IAEe,cAAc;QAC5B,OAAO,OAAO,CAAC,OAAO,CAAC,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,KAAK,EAAE,EAAE,EAAsB,CAAC,CAAA;IACpF,CAAC;CACF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,OAAkD,EAAY,EAAE;IACvG,MAAM,GAAG,GAAG,IAAI,qBAAqB,CAAC,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAA;IACrE,MAAM,aAAa,GAAG,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC,EAAE,KAAK,EAAE,uBAAuB,EAAE,CAAC,CAAA;IACtF,aAAa,CAAC,mBAAmB,CAAC,GAAG,EAAE,eAAe,CAAC,CAAA;IACvD,OAAO,aAAa,CAAA;AACtB,CAAC,CAAA"}

package/esm/system-identity-context.spec.d.ts

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

package/esm/system-identity-context.spec.d.ts.map

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

package/esm/system-identity-context.spec.js

@@ -0,0 +1,90 @@
+import { Injector } from '@furystack/inject';
+import { usingAsync } from '@furystack/utils';
+import { describe, expect, it } from 'vitest';
+import { getCurrentUser, isAuthenticated, isAuthorized } from './helpers.js';
+import { IdentityContext } from './identity-context.js';
+import { SystemIdentityContext, useSystemIdentityContext } from './system-identity-context.js';
+describe('SystemIdentityContext', () => {
+    it('isAuthenticated should return true', async () => {
+        const ctx = new SystemIdentityContext();
+        expect(await ctx.isAuthenticated()).toBe(true);
+    });
+    it('isAuthorized should return true without roles', async () => {
+        const ctx = new SystemIdentityContext();
+        expect(await ctx.isAuthorized()).toBe(true);
+    });
+    it('isAuthorized should return true with roles', async () => {
+        const ctx = new SystemIdentityContext();
+        expect(await ctx.isAuthorized('admin', 'superuser')).toBe(true);
+    });
+    it('getCurrentUser should return default system user', async () => {
+        const ctx = new SystemIdentityContext();
+        const user = await ctx.getCurrentUser();
+        expect(user).toEqual({ username: 'system', roles: [] });
+    });
+    it('getCurrentUser should respect custom username', async () => {
+        const ctx = new SystemIdentityContext({ username: 'migration-job' });
+        const user = await ctx.getCurrentUser();
+        expect(user).toEqual({ username: 'migration-job', roles: [] });
+    });
+});
+describe('useSystemIdentityContext', () => {
+    it('should return a child injector, not the parent', async () => {
+        await usingAsync(new Injector(), async (parent) => {
+            const child = useSystemIdentityContext({ injector: parent });
+            expect(child).not.toBe(parent);
+            await child[Symbol.asyncDispose]();
+        });
+    });
+    it('should resolve IdentityContext to a SystemIdentityContext', async () => {
+        await usingAsync(new Injector(), async (parent) => {
+            await usingAsync(useSystemIdentityContext({ injector: parent }), async (child) => {
+                const ctx = child.getInstance(IdentityContext);
+                expect(ctx).toBeInstanceOf(SystemIdentityContext);
+            });
+        });
+    });
+    it('should be authenticated and authorized via helpers', async () => {
+        await usingAsync(new Injector(), async (parent) => {
+            await usingAsync(useSystemIdentityContext({ injector: parent }), async (child) => {
+                expect(await isAuthenticated(child)).toBe(true);
+                expect(await isAuthorized(child, 'admin')).toBe(true);
+            });
+        });
+    });
+    it('should return the configured username via getCurrentUser', async () => {
+        await usingAsync(new Injector(), async (parent) => {
+            await usingAsync(useSystemIdentityContext({ injector: parent, username: 'seed-script' }), async (child) => {
+                const user = await getCurrentUser(child);
+                expect(user).toEqual({ username: 'seed-script', roles: [] });
+            });
+        });
+    });
+    it('should use default username when not specified', async () => {
+        await usingAsync(new Injector(), async (parent) => {
+            await usingAsync(useSystemIdentityContext({ injector: parent }), async (child) => {
+                const user = await getCurrentUser(child);
+                expect(user.username).toBe('system');
+            });
+        });
+    });
+    it('should dispose the child injector after usingAsync completes', async () => {
+        await usingAsync(new Injector(), async (parent) => {
+            let childRef;
+            await usingAsync(useSystemIdentityContext({ injector: parent }), async (child) => {
+                childRef = child;
+            });
+            expect(childRef).toBeDefined();
+            expect(() => childRef.getInstance(IdentityContext)).toThrow('Injector already disposed');
+        });
+    });
+    it('should not dispose the parent injector', async () => {
+        await usingAsync(new Injector(), async (parent) => {
+            await usingAsync(useSystemIdentityContext({ injector: parent }), async () => {
+                // no-op
+            });
+            expect(() => parent.getInstance(IdentityContext)).not.toThrow();
+        });
+    });
+});
+//# sourceMappingURL=system-identity-context.spec.js.map

package/esm/system-identity-context.spec.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@furystack/core",
-  "version": "15.0.36",
+  "version": "15.2.0",
   "description": "Core FuryStack package",
   "type": "module",
   "scripts": {
@@ -46,7 +46,7 @@
   },
   "homepage": "https://github.com/furystack/furystack",
   "devDependencies": {
-    "@types/node": "^25.2.3",
+    "@types/node": "^25.3.0",
     "typescript": "^5.9.3",
     "vitest": "^4.0.18"
   },

package/src/filter-items.spec.ts

@@ -0,0 +1,216 @@
+import { describe, it, expect } from 'vitest'
+import { filterItems } from './filter-items.js'
+import type { FilterType } from './models/physical-store.js'
+
+type TestItem = {
+  id: number
+  name: string
+  age: number
+  active: boolean
+}
+
+const items: TestItem[] = [
+  { id: 1, name: 'Alice', age: 30, active: true },
+  { id: 2, name: 'Bob', age: 25, active: false },
+  { id: 3, name: 'Charlie', age: 35, active: true },
+  { id: 4, name: 'Diana', age: 28, active: false },
+  { id: 5, name: 'Eve', age: 22, active: true },
+]
+
+describe('filterItems', () => {
+  describe('no filter', () => {
+    it('should return all items when filter is undefined', () => {
+      expect(filterItems(items, undefined)).toEqual(items)
+    })
+
+    it('should return all items when filter is not provided', () => {
+      expect(filterItems(items)).toEqual(items)
+    })
+
+    it('should return an empty array when input is empty', () => {
+      expect(filterItems<TestItem>([], { name: { $eq: 'Alice' } })).toEqual([])
+    })
+
+    it('should return all items when filter is an empty object', () => {
+      expect(filterItems(items, {} as FilterType<TestItem>)).toEqual(items)
+    })
+  })
+
+  describe('$eq', () => {
+    it('should return items matching the exact value', () => {
+      const result = filterItems(items, { name: { $eq: 'Alice' } })
+      expect(result).toEqual([items[0]])
+    })
+
+    it('should return empty array when no items match', () => {
+      const result = filterItems(items, { name: { $eq: 'Nobody' } })
+      expect(result).toEqual([])
+    })
+  })
+
+  describe('$ne', () => {
+    it('should return items not matching the value', () => {
+      const result = filterItems(items, { name: { $ne: 'Alice' } })
+      expect(result).toEqual([items[1], items[2], items[3], items[4]])
+    })
+  })
+
+  describe('$in', () => {
+    it('should return items whose value is in the array', () => {
+      const result = filterItems(items, { name: { $in: ['Alice', 'Bob'] } })
+      expect(result).toEqual([items[0], items[1]])
+    })
+
+    it('should return empty array when no values match', () => {
+      const result = filterItems(items, { name: { $in: ['Nobody'] } })
+      expect(result).toEqual([])
+    })
+  })
+
+  describe('$nin', () => {
+    it('should return items whose value is not in the array', () => {
+      const result = filterItems(items, { name: { $nin: ['Alice', 'Bob'] } })
+      expect(result).toEqual([items[2], items[3], items[4]])
+    })
+  })
+
+  describe('$gt', () => {
+    it('should return items with value greater than the threshold', () => {
+      const result = filterItems(items, { age: { $gt: 30 } })
+      expect(result).toEqual([items[2]])
+    })
+
+    it('should exclude items equal to the threshold', () => {
+      const result = filterItems(items, { age: { $gt: 35 } })
+      expect(result).toEqual([])
+    })
+  })
+
+  describe('$gte', () => {
+    it('should return items with value greater than or equal to the threshold', () => {
+      const result = filterItems(items, { age: { $gte: 30 } })
+      expect(result).toEqual([items[0], items[2]])
+    })
+  })
+
+  describe('$lt', () => {
+    it('should return items with value less than the threshold', () => {
+      const result = filterItems(items, { age: { $lt: 25 } })
+      expect(result).toEqual([items[4]])
+    })
+
+    it('should exclude items equal to the threshold', () => {
+      const result = filterItems(items, { age: { $lt: 22 } })
+      expect(result).toEqual([])
+    })
+  })
+
+  describe('$lte', () => {
+    it('should return items with value less than or equal to the threshold', () => {
+      const result = filterItems(items, { age: { $lte: 25 } })
+      expect(result).toEqual([items[1], items[4]])
+    })
+  })
+
+  describe('$startsWith', () => {
+    it('should return items whose string field starts with the value', () => {
+      const result = filterItems(items, { name: { $startsWith: 'Al' } })
+      expect(result).toEqual([items[0]])
+    })
+
+    it('should return empty array when no items match', () => {
+      const result = filterItems(items, { name: { $startsWith: 'Zz' } })
+      expect(result).toEqual([])
+    })
+  })
+
+  describe('$endsWith', () => {
+    it('should return items whose string field ends with the value', () => {
+      const result = filterItems(items, { name: { $endsWith: 'ce' } })
+      expect(result).toEqual([items[0]])
+    })
+  })
+
+  describe('$like', () => {
+    it('should match with % wildcards', () => {
+      const result = filterItems(items, { name: { $like: 'A%' } })
+      expect(result).toEqual([items[0]])
+    })
+
+    it('should match with % in the middle', () => {
+      const result = filterItems(items, { name: { $like: 'A%e' } })
+      expect(result).toEqual([items[0]])
+    })
+
+    it('should be case-insensitive', () => {
+      const result = filterItems(items, { name: { $like: 'alice' } })
+      expect(result).toEqual([items[0]])
+    })
+
+    it('should escape regex metacharacters in the pattern', () => {
+      type Item = { value: string }
+      const testItems: Item[] = [{ value: 'foo.bar' }, { value: 'fooXbar' }]
+      const result = filterItems(testItems, { value: { $like: 'foo.bar' } } as FilterType<Item>)
+      expect(result).toEqual([{ value: 'foo.bar' }])
+    })
+  })
+
+  describe('$regex', () => {
+    it('should return items matching the regex', () => {
+      const result = filterItems(items, { name: { $regex: '^[A-C]' } })
+      expect(result).toEqual([items[0], items[1], items[2]])
+    })
+
+    it('should return empty array when no items match', () => {
+      const result = filterItems(items, { name: { $regex: '^Z' } })
+      expect(result).toEqual([])
+    })
+
+    it('should throw on invalid regex syntax', () => {
+      expect(() => filterItems(items, { name: { $regex: '[invalid' } })).toThrow()
+    })
+  })
+
+  describe('$and', () => {
+    it('should return items matching all conditions', () => {
+      const result = filterItems(items, { $and: [{ age: { $gte: 25 } }, { active: { $eq: true } }] })
+      expect(result).toEqual([items[0], items[2]])
+    })
+
+    it('should return empty array when conditions are mutually exclusive', () => {
+      const result = filterItems(items, { $and: [{ name: { $eq: 'Alice' } }, { name: { $eq: 'Bob' } }] })
+      expect(result).toEqual([])
+    })
+  })
+
+  describe('$or', () => {
+    it('should return items matching any condition', () => {
+      const result = filterItems(items, { $or: [{ name: { $eq: 'Alice' } }, { name: { $eq: 'Bob' } }] })
+      expect(result).toEqual([items[0], items[1]])
+    })
+
+    it('should return empty array when no conditions match', () => {
+      const result = filterItems(items, { $or: [{ name: { $eq: 'Nobody' } }, { name: { $eq: 'Nope' } }] })
+      expect(result).toEqual([])
+    })
+  })
+
+  describe('combined field-level filters', () => {
+    it('should AND multiple field filters together', () => {
+      const result = filterItems(items, { age: { $gte: 25 }, active: { $eq: true } })
+      expect(result).toEqual([items[0], items[2]])
+    })
+  })
+
+  describe('error cases', () => {
+    it('should throw when a field filter is not an object', () => {
+      const badFilter = { name: 'Alice' } as unknown as FilterType<TestItem>
+      expect(() => filterItems(items, badFilter)).toThrow("The filter has to be an object, got string for field 'name'")
+    })
+
+    it('should throw for an unsupported filter operation', () => {
+      const badFilter = { name: { $unknown: 'x' } } as unknown as FilterType<TestItem>
+      expect(() => filterItems(items, badFilter)).toThrow("The filter key '$unknown' is not a valid operation")
+    })
+  })
+})