Skip to Content
ReferenceClient APIReference

Reference

Eager reference class for single object relationships. Holds a loaded model instance.

Import

import { Reference } from '@gluonic/client'

Class Signature

class Reference<T> {
  // Constructor
  constructor(value?: T)
  
  // Properties
  get value(): T | undefined
  set value(newValue: T | undefined)
  
  // Methods
  equals(other: Reference<T> | T | undefined): boolean
}

Note: Reference is eager - holds an already-loaded value. For lazy loading, use LazyReference.

Constructor

constructor(value?: T)

Create a reference with optional initial value.

Parameters:

ParameterTypeDescription
valueTOptional initial value

Example:

// Empty reference
const authorRef = new Reference<User>()
 
// With initial value
const authorRef = new Reference<User>(user)

Properties

value

get value(): T | undefined
set value(newValue: T | undefined)

Get or set the referenced object.

Returns: T | undefined - Referenced object or undefined

Reactive: Updates trigger MobX reactions

Example:

// Get
const user = issue.authorRef.value
if (user) {
  console.log(user.name)
}
 
// Set
issue.authorRef.value = newUser

Methods

equals()

equals(other: Reference<T> | T | undefined): boolean

Check equality with another reference or value.

Parameters:

ParameterTypeDescription
otherReference<T> | T | undefinedReference, value, or undefined

Returns: boolean - true if equal by identity

Comparison: Uses object identity (===), not deep equality

Example:

const ref1 = new Reference<User>(user)
const ref2 = new Reference<User>(user)
 
ref1.equals(ref2)  // true (same user)
ref1.equals(user)  // true (same user)
ref1.equals(undefined)  // false

Usage

Explicit References

Use Reference when you want explicit control (rare):

@ClientModel('issue')
export class Issue extends Model {
  @Property()
  id = crypto.randomUUID()
  
  @Property()
  authorId?: string
  
  // Explicit reference (rare)
  authorRef = new Reference<User>()
}

Typical Usage (LazyReference)

Most code uses LazyReference instead (via decorators):

@ClientModel('issue')
export class Issue extends Model {
  @Property()
  authorId?: string
  
  // Type signature is clean: User
  // Runtime type is: LazyReference<User>
  @ManyToOne('user', 'authorId', 'issues')
  author?: User
}
 
// Access
const name = issue.author?.value?.name

Recommendation: Use relationship decorators (@ManyToOne, etc.) instead of manual Reference instances. They handle lazy loading automatically.

Reference vs LazyReference

FeatureReferenceLazyReference
LoadingEager (value provided immediately)Lazy (loads when accessed)
Initial stateValue provided in constructorEmpty until accessed
NetworkNo automatic fetchingAuto-fetches on first access
FK invalidationNoYes (reloads when FK changes)
SuspenseNoYes (suspense getter)
Use caseManual controlRelationships (default)

Recommendation: Use LazyReference for relationships (default with decorators).

Examples

Manual Reference Management

const IssueEditor = observer(({ issue }) => {
  const authorRef = new Reference<User>(issue.author?.value)
  
  const handleAuthorChange = (newAuthor: User) => {
    authorRef.value = newAuthor
    issue.authorId = newAuthor.id
  }
  
  return (
    <div>
      <UserPicker 
        value={authorRef.value} 
        onChange={handleAuthorChange} 
      />
    </div>
  )
})

Equality Checking

const IssueCompare = ({ issue1, issue2 }) => {
  const sameAuthor = issue1.authorRef.equals(issue2.authorRef)
  
  return (
    <div>
      {sameAuthor ? 'Same author' : 'Different authors'}
    </div>
  )
}

See Also

Last updated on
DecoratorsLazyReference