@furystack/core 15.0.36 → 15.2.0

package/src/filter-items.ts

@@ -0,0 +1,148 @@
+import type { FilterType } from './models/physical-store.js'
+import { isLogicalOperator, isOperator } from './models/physical-store.js'
+
+type FieldOperatorFilter = {
+  $eq?: unknown
+  $ne?: unknown
+  $in?: unknown[]
+  $nin?: unknown[]
+  $gt?: unknown
+  $gte?: unknown
+  $lt?: unknown
+  $lte?: unknown
+  $startsWith?: string
+  $endsWith?: string
+  $like?: string
+  $regex?: string
+}
+
+const escapeRegexMeta = (str: string) => str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+
+const evaluateLike = (value: string, likeString: string) => {
+  const likeRegex = `^${likeString.split('%').map(escapeRegexMeta).join('.*')}$`
+  return value.match(new RegExp(likeRegex, 'i'))
+}
+
+/**
+ * Filters an array of items using a {@link FilterType} expression.
+ * Supports field-level operators ($eq, $ne, $in, $nin, $gt, $gte, $lt, $lte, $startsWith, $endsWith, $like, $regex)
+ * and logical operators ($and, $or).
+ * @param values The array of items to filter
+ * @param filter The filter expression to apply
+ * @returns The filtered array of items
+ */
+export function filterItems<T>(values: T[], filter?: FilterType<T>): T[] {
+  if (!filter) {
+    return values
+  }
+  return values.filter((item) => {
+    const filterRecord = filter as Record<string, Array<FilterType<T>> | FieldOperatorFilter | undefined>
+    const itemRecord = item as Record<string, unknown>
+
+    for (const key in filterRecord) {
+      if (isLogicalOperator(key)) {
+        const filterValue = filterRecord[key] as Array<FilterType<T>>
+        switch (key) {
+          case '$and':
+            if (filterValue.some((v: FilterType<T>) => !filterItems([item], v).length)) {
+              return false
+            }
+            break
+          case '$or':
+            if (filterValue.some((v: FilterType<T>) => filterItems([item], v).length)) {
+              break
+            }
+            return false
+          default:
+            throw new Error(`The logical operation '${key}' is not a valid operation`)
+        }
+      } else {
+        const fieldFilter = filterRecord[key] as FieldOperatorFilter | undefined
+        if (typeof fieldFilter === 'object' && fieldFilter !== null) {
+          for (const filterKey in fieldFilter) {
+            if (isOperator(filterKey)) {
+              const itemValue = itemRecord[key]
+              const filterValue = fieldFilter[filterKey as keyof FieldOperatorFilter]
+              switch (filterKey) {
+                case '$eq':
+                  if (filterValue !== itemValue) {
+                    return false
+                  }
+                  break
+                case '$ne':
+                  if (filterValue === itemValue) {
+                    return false
+                  }
+                  break
+                case '$in':
+                  if (!(filterValue as unknown[]).includes(itemValue)) {
+                    return false
+                  }
+                  break
+                case '$nin':
+                  if ((filterValue as unknown[]).includes(itemValue)) {
+                    return false
+                  }
+                  break
+                case '$lt':
+                  if ((itemValue as number) < (filterValue as number)) {
+                    break
+                  }
+                  return false
+                case '$lte':
+                  if ((itemValue as number) <= (filterValue as number)) {
+                    break
+                  }
+                  return false
+                case '$gt':
+                  if ((itemValue as number) > (filterValue as number)) {
+                    break
+                  }
+                  return false
+                case '$gte':
+                  if ((itemValue as number) >= (filterValue as number)) {
+                    break
+                  }
+                  return false
+                case '$regex':
+                  try {
+                    if (!new RegExp(filterValue as string).test(String(itemValue))) {
+                      return false
+                    }
+                  } catch (e) {
+                    throw new Error(
+                      `Invalid regular expression for $regex filter on field '${key}': ${(e as Error).message}`,
+                      { cause: e },
+                    )
+                  }
+                  break
+                case '$startsWith':
+                  if (!(itemValue as string).startsWith(filterValue as string)) {
+                    return false
+                  }
+                  break
+                case '$endsWith':
+                  if (!(itemValue as string).endsWith(filterValue as string)) {
+                    return false
+                  }
+                  break
+                case '$like':
+                  if (!evaluateLike(itemValue as string, filterValue as string)) {
+                    return false
+                  }
+                  break
+                default:
+                  throw new Error(`The expression (${filterKey}) is not a supported filter operation`)
+              }
+            } else {
+              throw new Error(`The filter key '${filterKey}' is not a valid operation`)
+            }
+          }
+        } else {
+          throw new Error(`The filter has to be an object, got ${typeof fieldFilter} for field '${key}'`)
+        }
+      }
+    }
+    return true
+  })
+}

package/src/in-memory-store.ts

@@ -1,25 +1,8 @@
 import type { Constructable } from '@furystack/inject'
 import { EventHub } from '@furystack/utils'
 import type { CreateResult, FilterType, FindOptions, PartialResult, PhysicalStore } from './models/physical-store.js'
-import { isLogicalOperator, isOperator, selectFields } from './models/physical-store.js'
-
-/**
- * Helper type representing all possible field filter operations
- */
-type FieldOperatorFilter = {
-  $eq?: unknown
-  $ne?: unknown
-  $in?: unknown[]
-  $nin?: unknown[]
-  $gt?: unknown
-  $gte?: unknown
-  $lt?: unknown
-  $lte?: unknown
-  $startsWith?: string
-  $endsWith?: string
-  $like?: string
-  $regex?: string
-}
+import { selectFields } from './models/physical-store.js'
+import { filterItems } from './filter-items.js'
 
 export class InMemoryStore<T, TPrimaryKey extends keyof T>
   extends EventHub<{
@@ -59,123 +42,8 @@ export class InMemoryStore<T, TPrimaryKey extends keyof T>
     return Promise.resolve(item && select ? selectFields(item, ...select) : item)
   }
 
-  private evaluateLike = (value: string, likeString: string) => {
-    const likeRegex = `^${likeString.replace(/%/g, '.*')}$`
-    return value.match(new RegExp(likeRegex, 'i'))
-  }
-
-  private filterInternal(values: T[], filter?: FilterType<T>): T[] {
-    if (!filter) {
-      return values
-    }
-    return values.filter((item) => {
-      const filterRecord = filter as Record<string, Array<FilterType<T>> | FieldOperatorFilter | undefined>
-      const itemRecord = item as Record<string, unknown>
-
-      for (const key in filterRecord) {
-        if (isLogicalOperator(key)) {
-          const filterValue = filterRecord[key] as Array<FilterType<T>>
-          switch (key) {
-            case '$and':
-              if (filterValue.some((v: FilterType<T>) => !this.filterInternal([item], v).length)) {
-                return false
-              }
-              break
-            case '$or':
-              if (filterValue.some((v: FilterType<T>) => this.filterInternal([item], v).length)) {
-                break
-              }
-              return false
-            default:
-              throw new Error(`The logical operation '${key}' is not a valid operation`)
-          }
-        } else {
-          const fieldFilter = filterRecord[key] as FieldOperatorFilter | undefined
-          if (typeof fieldFilter === 'object' && fieldFilter !== null) {
-            for (const filterKey in fieldFilter) {
-              if (isOperator(filterKey)) {
-                const itemValue = itemRecord[key]
-                const filterValue = fieldFilter[filterKey as keyof FieldOperatorFilter]
-                switch (filterKey) {
-                  case '$eq':
-                    if (filterValue !== itemValue) {
-                      return false
-                    }
-                    break
-                  case '$ne':
-                    if (filterValue === itemValue) {
-                      return false
-                    }
-                    break
-                  case '$in':
-                    if (!(filterValue as unknown[]).includes(itemValue)) {
-                      return false
-                    }
-                    break
-
-                  case '$nin':
-                    if ((filterValue as unknown[]).includes(itemValue)) {
-                      return false
-                    }
-                    break
-                  case '$lt':
-                    if ((itemValue as number) < (filterValue as number)) {
-                      break
-                    }
-                    return false
-                  case '$lte':
-                    if ((itemValue as number) <= (filterValue as number)) {
-                      break
-                    }
-                    return false
-                  case '$gt':
-                    if ((itemValue as number) > (filterValue as number)) {
-                      break
-                    }
-                    return false
-                  case '$gte':
-                    if ((itemValue as number) >= (filterValue as number)) {
-                      break
-                    }
-                    return false
-                  case '$regex':
-                    if (!new RegExp(filterValue as string).test(String(itemValue))) {
-                      return false
-                    }
-                    break
-                  case '$startsWith':
-                    if (!(itemValue as string).startsWith(filterValue as string)) {
-                      return false
-                    }
-                    break
-                  case '$endsWith':
-                    if (!(itemValue as string).endsWith(filterValue as string)) {
-                      return false
-                    }
-                    break
-                  case '$like':
-                    if (!this.evaluateLike(itemValue as string, filterValue as string)) {
-                      return false
-                    }
-                    break
-                  default:
-                    throw new Error(`The expression (${filterKey}) is not supported by '${this.constructor.name}'!`)
-                }
-              } else {
-                throw new Error(`The filter key '${filterKey}' is not a valid operation`)
-              }
-            }
-          } else {
-            throw new Error(`The filter has to be an object, got ${typeof fieldFilter} for field '${key}'`)
-          }
-        }
-      }
-      return true
-    })
-  }
-
   public async find<TFields extends Array<keyof T>>(searchOptions: FindOptions<T, TFields>) {
-    let value: Array<PartialResult<T, TFields>> = this.filterInternal([...this.cache.values()], searchOptions.filter)
+    let value: Array<PartialResult<T, TFields>> = filterItems([...this.cache.values()], searchOptions.filter)
 
     if (searchOptions.order) {
       const orderRecord = searchOptions.order as Record<string, 'ASC' | 'DESC'>
@@ -203,7 +71,7 @@ export class InMemoryStore<T, TPrimaryKey extends keyof T>
   }
 
   public async count(filter?: FilterType<T>) {
-    return this.filterInternal([...this.cache.values()], filter).length
+    return filterItems([...this.cache.values()], filter).length
   }
 
   public async update(id: T[TPrimaryKey], data: T) {

package/src/index.ts

@@ -1,8 +1,10 @@
 export * from './errors/index.js'
 export * from './models/physical-store.js'
 export * from './models/user.js'
+export * from './filter-items.js'
 export * from './in-memory-store.js'
 export * from './store-manager.js'
 export * from './global-disposables.js'
 export * from './identity-context.js'
+export * from './system-identity-context.js'
 export * from './helpers.js'

package/src/models/physical-store.ts

@@ -88,7 +88,14 @@ export const selectFields = <T extends object, TField extends Array<keyof T>>(en
 }
 
 /**
- * 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,

package/src/system-identity-context.spec.ts

@@ -0,0 +1,101 @@
+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: Injector | undefined
+      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()
+    })
+  })
+})

package/src/system-identity-context.ts

@@ -0,0 +1,83 @@
+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 class SystemIdentityContext extends IdentityContext {
+  private readonly username: string
+
+  constructor(options?: { username?: string }) {
+    super()
+    this.username = options?.username ?? 'system'
+  }
+
+  public override isAuthenticated() {
+    return Promise.resolve(true)
+  }
+
+  public override isAuthorized(..._roles: string[]) {
+    return Promise.resolve(true)
+  }
+
+  public override getCurrentUser<TUser extends User>(): Promise<TUser> {
+    return Promise.resolve({ username: this.username, roles: [] } as unknown as 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 const useSystemIdentityContext = (options: { injector: Injector; username?: string }): Injector => {
+  const ctx = new SystemIdentityContext({ username: options.username })
+  const childInjector = options.injector.createChild({ owner: 'SystemIdentityContext' })
+  childInjector.setExplicitInstance(ctx, IdentityContext)
+  return childInjector
+}