@synchronized-console/objectloader2 2.25.7 → 2.31.14

package/src/deferment/MemoryCache.test.ts

@@ -0,0 +1,187 @@
+import { vi, describe, it, expect, beforeEach, afterEach } from 'vitest'
+import { MemoryCache, MemoryCacheItem, MemoryCacheOptions } from './MemoryCache.js'
+import { Item, Base } from '../types/types.js'
+import { CustomLogger } from '../types/functions.js'
+
+const logger: CustomLogger = () => {
+  // console.log(message, ...optionalParams)
+}
+
+const defaultOptions: MemoryCacheOptions = {
+  maxSizeInMb: 10,
+  ttlms: 1000
+}
+
+const createItem = (id: string, size: number, referencedIds: string[] = []): Item => {
+  const base: Base & { data?: unknown } = {
+    id,
+    // eslint-disable-next-line camelcase
+    synchronized_type: 'Base'
+  }
+
+  if (referencedIds.length > 0) {
+    base.data = referencedIds.map((referencedId) => ({
+      // eslint-disable-next-line camelcase
+      synchronized_type: 'reference',
+      referencedId
+    }))
+  }
+
+  return {
+    baseId: id,
+    base,
+    size
+  }
+}
+
+describe('MemoryCacheItem', () => {
+  it('should correctly determine if it is expired', () => {
+    const item = createItem('1', 100)
+    const now = Date.now()
+    const cacheItem = new MemoryCacheItem(item, now + 1000)
+    expect(cacheItem.isExpired(now + 500)).toBe(false)
+    expect(cacheItem.isExpired(now + 1500)).toBe(true)
+  })
+
+  it('should update its access time', () => {
+    const item = createItem('1', 100)
+    const now = Date.now()
+    const cacheItem = new MemoryCacheItem(item, now + 1000)
+    cacheItem.setAccess(now + 500, 1000)
+    expect(cacheItem.isExpired(now + 1000)).toBe(false)
+    expect(cacheItem.isExpired(now + 1600)).toBe(true)
+  })
+
+  it('should return the correct item', () => {
+    const item = createItem('1', 100)
+    const cacheItem = new MemoryCacheItem(item, Date.now() + 1000)
+    expect(cacheItem.getItem()).toEqual(item)
+  })
+
+  it('should be done if expired', () => {
+    const item = createItem('1', 100)
+    const now = Date.now()
+    const cacheItem = new MemoryCacheItem(item, now + 1000)
+    expect(cacheItem.done(now + 1500)).toBe(true)
+    expect(cacheItem.done(now + 500)).toBe(false)
+  })
+})
+
+describe('MemoryCache', () => {
+  beforeEach(() => {
+    vi.useFakeTimers()
+  })
+
+  afterEach(() => {
+    vi.useRealTimers()
+  })
+
+  it('should add and get an item', () => {
+    const cache = new MemoryCache(defaultOptions, logger)
+    const item = createItem('1', 100)
+    const requestItem = vi.fn()
+
+    cache.add(item, requestItem)
+    const retrieved = cache.get('1')
+
+    expect(retrieved).toEqual(item)
+    expect(requestItem).not.toHaveBeenCalled()
+  })
+
+  it('should update expiry on get', () => {
+    const cache = new MemoryCache({ ...defaultOptions, ttlms: 100 }, logger)
+    const item = createItem('1', 100)
+    cache.add(item, vi.fn())
+
+    vi.advanceTimersByTime(50)
+    const retrieved = cache.get('1')
+    expect(retrieved).toBeDefined()
+
+    vi.advanceTimersByTime(80)
+    const retrievedAgain = cache.get('1')
+    expect(retrievedAgain).toBeDefined()
+  })
+
+  it('should return undefined for non-existent item', () => {
+    const cache = new MemoryCache(defaultOptions, logger)
+    expect(cache.get('non-existent')).toBeUndefined()
+  })
+
+  it('should scan for references and request missing ones', () => {
+    const cache = new MemoryCache(defaultOptions, logger)
+    const requestItem = vi.fn()
+    const item = createItem('1', 100, ['2', '3'])
+
+    cache.add(createItem('3', 50), vi.fn()) // pre-cache one of the references
+    cache.scanForReferences(item.base, requestItem)
+
+    expect(requestItem).toHaveBeenCalledTimes(1)
+    expect(requestItem).toHaveBeenCalledWith('2')
+    expect(requestItem).not.toHaveBeenCalledWith('3')
+  })
+
+  it('should clean up expired items when size exceeds max', () => {
+    const options = { maxSizeInMb: 0, ttlms: 100 } // 100 bytes
+    const cache = new MemoryCache(options, logger)
+    const requestItem = vi.fn()
+
+    const item1 = createItem('1', 60)
+    const item2 = createItem('2', 60)
+
+    const now = 1
+    cache.add(item1, requestItem, now - 200)
+    cache.cleanCache(now)
+    cache.add(item2, requestItem, now + 100)
+
+    expect(cache.get('1')).toBeUndefined()
+    expect(cache.get('2')).toBeDefined()
+  })
+
+  it('should not clean up expired items if they have references', () => {
+    const options = { maxSizeInMb: 0.0001, ttlms: 100 } // 100 bytes
+    const cache = new MemoryCache(options, logger)
+    const requestItem = vi.fn()
+
+    const item1 = createItem('1', 60)
+    const item2 = createItem('2', 60, ['1'])
+
+    cache.add(item1, requestItem)
+    vi.advanceTimersByTime(110) // item1 expires
+    cache.add(item2, requestItem) // item2 adds a reference to item1
+
+    vi.advanceTimersByTime(100)
+
+    expect(cache.get('1')).toBeDefined()
+    expect(cache.get('2')).toBeDefined()
+  })
+
+  it('compareMaybeBasesByReferences should sort correctly', () => {
+    const cache = new MemoryCache(defaultOptions, logger)
+    const requestItem = vi.fn()
+
+    const item1 = createItem('1', 10)
+    const item2 = createItem('2', 10)
+    const item3 = createItem('3', 10, ['1', '2'])
+    const item4 = createItem('4', 10, ['2'])
+
+    cache.add(item1, requestItem)
+    cache.add(item2, requestItem)
+    cache.add(item3, requestItem)
+    cache.add(item4, requestItem)
+
+    expect(cache.compareMaybeBasesByReferences('1', '2')).toBe(-1)
+    expect(cache.compareMaybeBasesByReferences('2', '1')).toBe(1)
+    expect(cache.compareMaybeBasesByReferences('1', '1')).toBe(0)
+    expect(cache.compareMaybeBasesByReferences('1', '5')).toBe(1)
+    expect(cache.compareMaybeBasesByReferences('5', '1')).toBe(-1)
+    expect(cache.compareMaybeBasesByReferences('5', '6')).toBe(0)
+  })
+
+  it('should throw when used after dispose', () => {
+    const cache = new MemoryCache(defaultOptions, logger)
+    cache.dispose()
+    const item = createItem('1', 100)
+    expect(() => cache.add(item, vi.fn())).toThrow('MemoryCache is disposed')
+    expect(() => cache.get('1')).toThrow('MemoryCache is disposed')
+  })
+})

package/src/deferment/MemoryCache.ts

@@ -0,0 +1,189 @@
+import { CustomLogger } from '../types/functions.js'
+import { Item } from '../types/types.js'
+
+export interface MemoryCacheOptions {
+  maxSizeInMb: number
+  ttlms: number
+}
+
+export class MemoryCacheItem {
+  private item: Item
+  private expiresAt: number // Timestamp in ms
+
+  constructor(item: Item, expiresAt: number) {
+    this.item = item
+    this.expiresAt = expiresAt
+  }
+
+  isExpired(now: number): boolean {
+    return now > this.expiresAt
+  }
+  setAccess(now: number, ttl: number): void {
+    this.expiresAt = now + ttl
+  }
+
+  getItem(): Item {
+    return this.item
+  }
+
+  done(now: number): boolean {
+    if (this.isExpired(now)) {
+      return true
+    }
+    return false
+  }
+}
+
+export class MemoryCache {
+  private isGathered: Map<string, boolean> = new Map()
+  private references: Map<string, number> = new Map()
+  private cache: Map<string, MemoryCacheItem> = new Map()
+
+  private options: MemoryCacheOptions
+  private logger: CustomLogger
+  private disposed = false
+  private currentSize = 0
+  private timer?: ReturnType<typeof setTimeout>
+
+  constructor(options: MemoryCacheOptions, logger: CustomLogger) {
+    this.options = options
+    this.logger = logger
+    this.resetGlobalTimer()
+  }
+
+  add(item: Item, requestItem: (id: string) => void, testNow?: number): void {
+    if (this.disposed) throw new Error('MemoryCache is disposed')
+    this.currentSize += item.size || 0
+    this.cache.set(
+      item.baseId,
+      new MemoryCacheItem(item, (testNow || this.now()) + this.options.ttlms)
+    )
+
+    if (!this.isGathered.has(item.baseId)) {
+      this.isGathered.set(item.baseId, true)
+      this.scanForReferences(item.base!, requestItem)
+    }
+  }
+
+  get(id: string): Item | undefined {
+    if (this.disposed) throw new Error('MemoryCache is disposed')
+    const item = this.cache.get(id)
+    if (item) {
+      item.setAccess(this.now(), this.options.ttlms)
+      return item.getItem()
+    }
+    return undefined
+  }
+
+  scanForReferences(data: unknown, requestItem: (id: string) => void): void {
+    const scan = (item: unknown): void => {
+      // Stop if the item is null or not an object (i.e., primitive)
+      if (item === null || typeof item !== 'object') {
+        return
+      }
+
+      // If it's an array, scan each element
+      if (Array.isArray(item)) {
+        for (const element of item) {
+          scan(element)
+        }
+        return
+      }
+
+      // If it's an object, scan its properties
+      for (const key in item) {
+        if (Object.prototype.hasOwnProperty.call(item, key)) {
+          // We found the target property!
+          if (key === 'referencedId') {
+            const value = (item as { referencedId: unknown }).referencedId
+            // Ensure the value is a string before adding it
+            if (typeof value === 'string') {
+              this.references.set(value, (this.references.get(value) || 0) + 1)
+              if (!this.cache.has(value)) {
+                requestItem(value)
+              }
+            }
+          }
+
+          // Continue scanning deeper into the object's properties
+          scan((item as Record<string, unknown>)[key])
+        }
+      }
+    }
+
+    scan(data)
+  }
+
+  private resetGlobalTimer(): void {
+    const run = (): void => {
+      this.cleanCache()
+      this.timer = setTimeout(run, this.options.ttlms)
+    }
+    this.timer = setTimeout(run, this.options.ttlms)
+  }
+
+  private now(): number {
+    return Date.now()
+  }
+
+  cleanCache(testNow?: number): void {
+    const maxSizeBytes = this.options.maxSizeInMb * 1024 * 1024
+    if (this.currentSize < maxSizeBytes) {
+      this.logger(
+        `cache size (${this.currentSize} < ${maxSizeBytes}) is ok, no need to clean`
+      )
+      return
+    }
+    const now = testNow || this.now()
+    let cleaned = 0
+    const start = performance.now()
+    for (const deferredBase of Array.from(this.cache.values())
+      .filter((x) => x.isExpired(now))
+      .sort((a, b) =>
+        this.compareMaybeBasesByReferences(a.getItem().baseId, b.getItem().baseId)
+      )) {
+      if (deferredBase.done(now)) {
+        const id = deferredBase.getItem().baseId
+        const referenceCount = this.references.get(id) || 0
+        if (referenceCount > 0) {
+          // Skip eviction for items with reference counts greater than 0,
+          // as they are still in use and should not be removed from the cache.
+          continue
+        }
+        this.currentSize -= deferredBase.getItem().size || 0
+        this.cache.delete(id)
+        cleaned++
+        if (this.currentSize < maxSizeBytes) {
+          break
+        }
+      }
+    }
+    this.logger(
+      `cleaned cache: cleaned ${cleaned}, cached ${this.cache.size}, time ${
+        performance.now() - start
+      }`
+    )
+    return
+  }
+
+  compareMaybeBasesByReferences(id1: string, id2: string): number {
+    const a = this.references.get(id1)
+    const b = this.references.get(id2)
+    if (a === undefined && b === undefined) return 0
+    if (a === undefined) return -1
+    if (b === undefined) return 1
+    return a - b
+  }
+
+  dispose(): void {
+    if (this.disposed) return
+    this.disposed = true
+    if (this.timer) {
+      clearTimeout(this.timer)
+      this.timer = undefined
+    }
+    this.cache.clear()
+    this.isGathered.clear()
+    this.references.clear()
+  }
+}

package/src/deferment/defermentManager.test.ts

@@ -0,0 +1,225 @@
+import { vi, describe, it, expect } from 'vitest'
+import { DefermentManager } from './defermentManager.js'
+import { MemoryCache } from './MemoryCache.js'
+import { CustomLogger } from '../types/functions.js'
+import { Item } from '../types/types.js'
+
+describe('DefermentManager', () => {
+  it('should be created', () => {
+    const mockLogger: CustomLogger = vi.fn()
+    const mockCache = {
+      get: vi.fn(),
+      add: vi.fn(),
+      dispose: vi.fn()
+    } as unknown as MemoryCache
+    const defermentManager = new DefermentManager(mockLogger, mockCache)
+    expect(defermentManager).toBeDefined()
+  })
+
+  describe('defer', () => {
+    it('should return a resolved promise if item is in cache', async () => {
+      const mockLogger: CustomLogger = vi.fn()
+      const get = vi.fn()
+      const add = vi.fn()
+      const mockCache = {
+        get,
+        add
+      } as unknown as MemoryCache
+      const defermentManager = new DefermentManager(mockLogger, mockCache)
+
+      const item: Item = {
+        // eslint-disable-next-line camelcase
+        base: { id: 'testId', synchronized_type: 'Base' },
+        baseId: 'testId'
+      }
+      get.mockReturnValue(item)
+
+      const [promise, wasInCache] = defermentManager.defer({ id: 'testId' })
+      const result = await promise
+
+      expect(wasInCache).toBe(true)
+      expect(result).toEqual(item.base)
+      expect(get).toHaveBeenCalledWith('testId')
+    })
+
+    it('should return the same promise if item is already outstanding', () => {
+      const mockLogger: CustomLogger = vi.fn()
+      const get = vi.fn()
+      const add = vi.fn()
+      const mockCache = {
+        get,
+        add
+      } as unknown as MemoryCache
+      const defermentManager = new DefermentManager(mockLogger, mockCache)
+
+      const [promise1, wasInCache1] = defermentManager.defer({ id: 'testId' })
+      const [promise2, wasInCache2] = defermentManager.defer({ id: 'testId' })
+
+      expect(wasInCache1).toBe(false)
+      expect(wasInCache2).toBe(true)
+      expect(promise1).toBe(promise2)
+    })
+
+    it('should create a new deferred base if not in cache and not outstanding', () => {
+      const mockLogger: CustomLogger = vi.fn()
+      const get = vi.fn()
+      const add = vi.fn()
+      const mockCache = {
+        get,
+        add
+      } as unknown as MemoryCache
+      const defermentManager = new DefermentManager(mockLogger, mockCache)
+
+      const [promise, wasInCache] = defermentManager.defer({ id: 'testId' })
+
+      expect(wasInCache).toBe(false)
+      expect(promise).toBeInstanceOf(Promise)
+    })
+
+    it('should throw if disposed', () => {
+      const mockLogger: CustomLogger = vi.fn()
+      const get = vi.fn()
+      const add = vi.fn()
+      const mockCache = {
+        get,
+        add,
+        dispose: vi.fn()
+      } as unknown as MemoryCache
+      const defermentManager = new DefermentManager(mockLogger, mockCache)
+
+      defermentManager.dispose()
+      expect(() => defermentManager.defer({ id: 'testId' })).toThrow(
+        'DefermentManager is disposed'
+      )
+    })
+  })
+
+  describe('undefer', () => {
+    it('should resolve the promise when an outstanding item is found', async () => {
+      const mockLogger: CustomLogger = vi.fn()
+      const get = vi.fn()
+      const add = vi.fn()
+      const mockCache = {
+        get,
+        add
+      } as unknown as MemoryCache
+      const defermentManager = new DefermentManager(mockLogger, mockCache)
+      const requestItem = vi.fn()
+
+      const [promise] = defermentManager.defer({ id: 'testId' })
+
+      const item: Item = {
+        // eslint-disable-next-line camelcase
+        base: { id: 'testId', synchronized_type: 'Base' },
+        baseId: 'testId'
+      }
+      defermentManager.undefer(item, requestItem)
+
+      const result = await promise
+      expect(result).toEqual(item.base)
+    })
+
+    it('should log an error if item has no base', () => {
+      const mockLogger: CustomLogger = vi.fn()
+      const get = vi.fn()
+      const add = vi.fn()
+      const mockCache = {
+        get,
+        add
+      } as unknown as MemoryCache
+      const defermentManager = new DefermentManager(mockLogger, mockCache)
+      const requestItem = vi.fn()
+
+      const item: Item = { baseId: 'testId' }
+      defermentManager.undefer(item, requestItem)
+      expect(mockLogger).toHaveBeenCalledWith('undefer called with no base', item)
+    })
+
+    it('should add to cache and request item if not outstanding', () => {
+      const mockLogger: CustomLogger = vi.fn()
+      const get = vi.fn()
+      const add = vi.fn()
+      const mockCache = {
+        get,
+        add
+      } as unknown as MemoryCache
+      const defermentManager = new DefermentManager(mockLogger, mockCache)
+      const requestItem = vi.fn()
+
+      const item: Item = {
+        // eslint-disable-next-line camelcase
+        base: { id: 'testId', synchronized_type: 'Base' },
+        baseId: 'testId'
+      }
+      add.mockImplementation((_item: Item, getDependencies?: (id: string) => void) => {
+        if (getDependencies) getDependencies('testId')
+      })
+
+      defermentManager.undefer(item, requestItem)
+
+      expect(add).toHaveBeenCalledWith(item, expect.any(Function))
+      expect(requestItem).toHaveBeenCalledWith('testId')
+    })
+
+    it('should throw if disposed', () => {
+      const mockLogger: CustomLogger = vi.fn()
+      const get = vi.fn()
+      const add = vi.fn()
+      const mockCache = {
+        get,
+        add,
+        dispose: vi.fn()
+      } as unknown as MemoryCache
+      const defermentManager = new DefermentManager(mockLogger, mockCache)
+      const requestItem = vi.fn()
+
+      defermentManager.dispose()
+      const item: Item = {
+        // eslint-disable-next-line camelcase
+        base: { id: 'testId', synchronized_type: 'Base' },
+        baseId: 'testId'
+      }
+      expect(() => defermentManager.undefer(item, requestItem)).toThrow(
+        'DefermentManager is disposed'
+      )
+    })
+  })
+
+  describe('dispose', () => {
+    it('should clear all outstanding deferments', () => {
+      const mockLogger: CustomLogger = vi.fn()
+      const get = vi.fn()
+      const add = vi.fn()
+      const mockCache = {
+        get,
+        add,
+        dispose: vi.fn()
+      } as unknown as MemoryCache
+      const defermentManager = new DefermentManager(mockLogger, mockCache)
+
+      void defermentManager.defer({ id: 'testId' })
+      defermentManager.dispose()
+      // @ts-expect-error - accessing private property for testing
+      expect(defermentManager.outstanding.size).toBe(0)
+    })
+
+    it('should not do anything if already disposed', () => {
+      const mockLogger: CustomLogger = vi.fn()
+      const get = vi.fn()
+      const add = vi.fn()
+      const mockCache = {
+        get,
+        add,
+        dispose: vi.fn()
+      } as unknown as MemoryCache
+      const defermentManager = new DefermentManager(mockLogger, mockCache)
+
+      defermentManager.dispose()
+      // @ts-expect-error - accessing private property for testing
+      const outstanding = defermentManager.outstanding
+      const clearSpy = vi.spyOn(outstanding, 'clear')
+      defermentManager.dispose()
+      expect(clearSpy).not.toHaveBeenCalled()
+    })
+  })
+})

package/src/deferment/defermentManager.ts

@@ -0,0 +1,95 @@
+import { DeferredBase } from './deferredBase.js'
+import { CustomLogger } from '../types/functions.js'
+import { Item, Base } from '../types/types.js'
+import { MemoryCache } from './MemoryCache.js'
+
+export interface Deferment {
+  defer(params: { id: string }): [Promise<Base>, boolean]
+  undefer(item: Item, requestItem: (id: string) => void): void
+  dispose(): void
+}
+
+export class MemoryOnlyDeferment implements Deferment {
+  private items: Map<string, Base>
+
+  constructor(items: Map<string, Base>) {
+    this.items = items
+  }
+  defer(params: { id: string }): [Promise<Base>, boolean] {
+    const item = this.items.get(params.id)
+    if (item) {
+      return [Promise.resolve(item), true]
+    }
+    return [Promise.reject(new Error('Not found in cache: ' + params.id)), false]
+  }
+  undefer(): void {
+    //no-op
+  }
+  dispose(): void {
+    //no-op
+  }
+}
+
+export class DefermentManager implements Deferment {
+  private outstanding: Map<string, DeferredBase> = new Map()
+  private logger: CustomLogger
+  private disposed = false
+  private cache: MemoryCache
+
+  constructor(logger: CustomLogger, cache?: MemoryCache) {
+    this.logger = logger
+    this.cache =
+      cache ||
+      new MemoryCache(
+        {
+          maxSizeInMb: 500, // 500 MB
+          ttlms: 5_000 // 5 seconds
+        },
+        logger
+      )
+  }
+
+  defer(params: { id: string }): [Promise<Base>, boolean] {
+    if (this.disposed) throw new Error('DefermentManager is disposed')
+    const item = this.cache.get(params.id)
+    if (item) {
+      return [Promise.resolve(item.base!), true]
+    }
+    const deferredBase = this.outstanding.get(params.id)
+    if (deferredBase) {
+      return [deferredBase.getPromise(), true]
+    }
+    const notYetFound = new DeferredBase(params.id)
+    this.outstanding.set(params.id, notYetFound)
+    return [notYetFound.getPromise(), false]
+  }
+
+  undefer(item: Item, requestItem: (id: string) => void): void {
+    if (this.disposed) throw new Error('DefermentManager is disposed')
+    const base = item.base
+    if (!base) {
+      this.logger('undefer called with no base', item)
+      return
+    }
+    this.cache.add(item, (id) => {
+      if (!this.outstanding.has(id)) {
+        requestItem(id)
+      }
+    })
+
+    //order matters here with found before undefer
+    const deferredBase = this.outstanding.get(item.baseId)
+    if (deferredBase) {
+      deferredBase.found(base)
+      this.outstanding.delete(item.baseId)
+    }
+  }
+
+  dispose(): void {
+    if (this.disposed) return
+    this.disposed = true
+    this.logger('cleared deferments, left', this.outstanding.size)
+    this.outstanding.clear()
+    this.cache.dispose()
+  }
+}