@speckle/objectloader2 2.25.4 → 2.25.8

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,220 @@
+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()
+    } as unknown as MemoryCache
+    const defermentManager = new DefermentManager(mockCache, mockLogger)
+    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(mockCache, mockLogger)
+
+      const item: Item = {
+        // eslint-disable-next-line camelcase
+        base: { id: 'testId', speckle_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(mockCache, mockLogger)
+
+      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(mockCache, mockLogger)
+
+      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
+      } as unknown as MemoryCache
+      const defermentManager = new DefermentManager(mockCache, mockLogger)
+
+      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(mockCache, mockLogger)
+      const requestItem = vi.fn()
+
+      const [promise] = defermentManager.defer({ id: 'testId' })
+
+      const item: Item = {
+        // eslint-disable-next-line camelcase
+        base: { id: 'testId', speckle_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(mockCache, mockLogger)
+      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(mockCache, mockLogger)
+      const requestItem = vi.fn()
+
+      const item: Item = {
+        // eslint-disable-next-line camelcase
+        base: { id: 'testId', speckle_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
+      } as unknown as MemoryCache
+      const defermentManager = new DefermentManager(mockCache, mockLogger)
+      const requestItem = vi.fn()
+
+      defermentManager.dispose()
+      const item: Item = {
+        // eslint-disable-next-line camelcase
+        base: { id: 'testId', speckle_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
+      } as unknown as MemoryCache
+      const defermentManager = new DefermentManager(mockCache, mockLogger)
+
+      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
+      } as unknown as MemoryCache
+      const defermentManager = new DefermentManager(mockCache, mockLogger)
+
+      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,59 @@
+import { DeferredBase } from './deferredBase.js'
+import { CustomLogger } from '../types/functions.js'
+import { Item, Base } from '../types/types.js'
+import { MemoryCache } from './MemoryCache.js'
+
+export class DefermentManager {
+  private outstanding: Map<string, DeferredBase> = new Map()
+  private logger: CustomLogger
+  private disposed = false
+  private cache: MemoryCache
+
+  constructor(cache: MemoryCache, logger: CustomLogger) {
+    this.cache = cache
+    this.logger = 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()
+  }
+}

package/src/deferment/deferredBase.ts

@@ -0,0 +1,29 @@
+import { Base } from '../types/types.js'
+
+export class DeferredBase {
+  private promise: Promise<Base>
+  private resolve!: (value: Base) => void
+  private reject!: (reason?: Error) => void
+
+  private readonly id: string
+
+  constructor(id: string) {
+    this.id = id
+    this.promise = new Promise<Base>((resolve, reject) => {
+      this.resolve = resolve
+      this.reject = reject
+    })
+  }
+
+  getId(): string {
+    return this.id
+  }
+
+  getPromise(): Promise<Base> {
+    return this.promise
+  }
+
+  found(value: Base): void {
+    this.resolve(value)
+  }
+}

package/src/index.ts

@@ -1,3 +1,3 @@
-export { MemoryDatabase } from './operations/databases/memoryDatabase.js'
-export { ObjectLoader2 } from './operations/objectLoader2.js'
-export { ObjectLoader2Factory } from './operations/objectLoader2Factory.js'
+export { ObjectLoader2 } from './core/objectLoader2.js'
+export { ObjectLoader2Factory } from './core/objectLoader2Factory.js'
+export { getFeatureFlag, ObjectLoader2Flags } from './types/functions.js'

package/src/{helpers → queues}/aggregateQueue.ts

@@ -8,13 +8,17 @@ export default class AggregateQueue<T> implements Queue<T> {
     this.#queue1 = queue1
     this.#queue2 = queue2
   }
+  async disposeAsync(): Promise<void> {
+    await this.#queue1.disposeAsync()
+    await this.#queue2.disposeAsync()
+  }
 
   add(value: T): void {
     this.#queue1.add(value)
     this.#queue2.add(value)
   }
 
-  values(): T[] {
+  values(): never {
     throw new Error('Not implemented')
   }
 }

package/src/{helpers → queues}/asyncGeneratorQueue.ts

@@ -29,7 +29,8 @@ export default class AsyncGeneratorQueue<T> implements Queue<T> {
       }
     }
   }
-  dispose(): void {
+  disposeAsync(): Promise<void> {
     this.#finished = true
+    return Promise.resolve()
   }
 }

package/src/{helpers → queues}/batchedPool.ts

@@ -1,4 +1,6 @@
-export default class BatchedPool<T> {
+import Queue from './queue.js'
+
+export default class BatchedPool<T> implements Queue<T> {
   #queue: T[] = []
   #concurrencyAndSizes: number[]
   #processFunction: (batch: T[]) => Promise<void>

package/src/queues/batchingQueue.dispose.test.ts

@@ -0,0 +1,74 @@
+import { describe, test, expect, vi } from 'vitest'
+import BatchingQueue from './batchingQueue.js'
+
+describe('BatchingQueue disposal', () => {
+  test('should drain the queue on dispose', async () => {
+    const processFunction = vi.fn().mockResolvedValue(undefined)
+    const queue = new BatchingQueue<{ id: string }>({
+      batchSize: 5,
+      maxWaitTime: 1000,
+      processFunction
+    })
+
+    const items = Array.from({ length: 3 }, (_, i) => ({ id: `item-${i}` }))
+    items.forEach((item) => queue.add(item.id, item))
+
+    expect(queue.count()).toBe(3)
+
+    await queue.disposeAsync()
+
+    expect(processFunction).toHaveBeenCalledWith(items)
+    expect(queue.count()).toBe(0)
+    expect(queue.isDisposed()).toBe(true)
+  })
+
+  test('should wait for processing to finish before disposing', async () => {
+    let resolveProcess: (value: void | PromiseLike<void>) => void = () => {}
+    const processPromise = new Promise<void>((resolve) => {
+      resolveProcess = resolve
+    })
+
+    const processFunction = vi.fn().mockImplementation(() => processPromise)
+
+    const queue = new BatchingQueue<{ id: string }>({
+      batchSize: 2,
+      maxWaitTime: 100,
+      processFunction
+    })
+
+    const items1 = [{ id: 'item-1' }, { id: 'item-2' }]
+    items1.forEach((item) => queue.add(item.id, item))
+
+    // First batch is processing
+    expect(processFunction).toHaveBeenCalledWith(items1)
+
+    const items2 = [{ id: 'item-3' }]
+    items2.forEach((item) => queue.add(item.id, item))
+
+    const disposePromise = queue.disposeAsync()
+
+    // Queue should be disposed now, but processing is still ongoing
+    expect(queue.isDisposed()).toBe(true)
+    resolveProcess()
+    await disposePromise
+
+    expect(processFunction).toHaveBeenCalledTimes(2)
+    expect(processFunction).toHaveBeenCalledWith(items2)
+    expect(queue.count()).toBe(0)
+    expect(queue.isDisposed()).toBe(true)
+  })
+
+  test('adding items after dispose should do nothing', async () => {
+    const processFunction = vi.fn().mockResolvedValue(undefined)
+    const queue = new BatchingQueue<string>({
+      batchSize: 5,
+      maxWaitTime: 1000,
+      processFunction
+    })
+
+    await queue.disposeAsync()
+    queue.add('key1', 'item1')
+    expect(queue.count()).toBe(0)
+    expect(processFunction).not.toHaveBeenCalled()
+  })
+})