Skip to Content
ReferenceClient APIIdentityMap

IdentityMap

Ensures same data ID always returns the same model instance.

Note: Most apps use useModel() and useCollectionModels() hooks. IdentityMap is for advanced use only.

What It Does

IdentityMap (formerly called GraphBridge) maintains an identity map cache:

const issue1 = identityMap.getModel('issue', '123')
const issue2 = identityMap.getModel('issue', '123')
 
console.log(issue1 === issue2)  // true ✓
// Exact same JavaScript object

This ensures:

  • Same ID always returns same instance
  • Efficient React rendering (=== comparison works)
  • Consistent state across components
  • Automatic garbage collection

API

class IdentityMap {
  getModel<T extends Model>(type: string, id: string): T
  modelsByType<T extends Model>(type: string): T[]
  queryByIndex<T extends Model>(
    type: string,
    indexKey: string,
    indexValue: string
  ): T[]
  invalidate(type: string, id: string): void
  clearCache(): void
}

Usage (Advanced)

Access through useIdentityMap() hook:

import { useIdentityMap } from '@gluonic/client'
 
const MyComponent = () => {
  const identityMap = useIdentityMap()
  
  // Get single model
  const issue = identityMap.getModel<Issue>('issue', '123')
  
  // Get all of a type
  const allIssues = identityMap.modelsByType<Issue>('issue')
  
  // Query by index
  const teamIssues = identityMap.queryByIndex<Issue>(
    'issue',
    'teamId',
    'team-1'
  )
  
  return <div>...</div>
}

Most apps should use hooks instead:

// ✅ Recommended
const issue = useModel<Issue>('issue', '123')
const issues = useCollectionModels<Issue>('issue')
 
// ⚠️ Advanced only
const identityMap = useIdentityMap()
const issue = identityMap.getModel('issue', '123')

How It Works

IdentityMap sits between your components and the ObjectPool:

Components
  ↓ useModel(), useCollectionModels()
IdentityMap
  ↓ getModel(), modelsByType()
ObjectPool
  ↓ Flat storage of WireRows
Storage (Drizzle)

Cache invalidation:

  • When models update: Cache entry invalidated
  • When models delete: Cache entry removed
  • Next access: Fresh instance created from pool

See Also

Last updated on
StoreOverview