RecordType

A record type is a type that can be stored in a record store. It is created with createRecordType.

class RecordType<
  R extends UnknownRecord,
  RequiredProperties extends keyof Omit<R, 'id' | 'typeName'>,
> {}

Creates a new RecordType instance.

typeName - The unique type name for records created by this RecordType config - Configuration object for the RecordType

• createDefaultProperties - Function that returns default properties for new records
• validator - Optional validator function for record validation
• scope - Optional scope determining persistence behavior (defaults to 'document')
• ephemeralKeys - Optional mapping of property names to ephemeral status

Parameters

R['typeName']

{
  readonly createDefaultProperties: () => Exclude<
    Omit<R, 'id' | 'typeName'>,
    RequiredProperties
  >
  readonly ephemeralKeys?: {
    readonly [K in Exclude<
      keyof R,
      'id' | 'typeName'
    >]: boolean
  }
  readonly scope?: RecordScope
  readonly validator?: StoreValidator<R>
}

Properties

Factory function that creates default properties for new records.

readonly createDefaultProperties: () => Exclude<
  Omit<R, 'id' | 'typeName'>,
  RequiredProperties
>

Optional configuration specifying which record properties are ephemeral. Ephemeral properties are not included in snapshots or synchronization.

readonly ephemeralKeys?: {
  readonly [K in Exclude<keyof R, 'id' | 'typeName'>]: boolean
}

Set of property names that are marked as ephemeral for efficient lookup.

readonly ephemeralKeySet: ReadonlySet<string>

The scope that determines how records of this type are persisted and synchronized.

readonly scope: RecordScope

The unique type associated with this record.

readonly typeName: R['typeName']

Validator function used to validate records of this type.

readonly validator: StoreValidator<R>

Methods

Creates a deep copy of an existing record with a new unique id.

This method performs a deep clone of all properties while generating a fresh id, making it useful for duplicating records without id conflicts.

clone(record: R): R

Example

const originalBook = Book.create({ title: '1984', author: 'George Orwell' })
const duplicatedBook = Book.clone(originalBook)
// duplicatedBook has same properties but different id

Parameters

R

Returns

R

A new record with the same properties but a different id

Creates a new record of this type with the given properties.

Properties are merged with default properties from the RecordType configuration. If no id is provided, a unique id will be generated automatically.

create(
  properties: Expand<
    Pick<R, RequiredProperties> & Omit<Partial<R>, RequiredProperties>
  >
): R

Example

const book = Book.create({
  title: 'The Great Gatsby',
  author: 'F. Scott Fitzgerald',
})
// Result: { id: 'book:abc123', typeName: 'book', title: 'The Great Gatsby', author: 'F. Scott Fitzgerald', inStock: true }

Parameters

Expand<
  Pick<R, RequiredProperties> &
    Omit<Partial<R>, RequiredProperties>
>

Returns

R

The newly created record with generated id and typeName

Create a new ID for this record type.

createId(customUniquePart?: string): IdOf<R>

Example

const id = recordType.createId()

Parameters

string

Returns

IdOf<R>

The new ID.

Type guard that checks whether an id string belongs to this RecordType.

Validates that the id starts with this RecordType's typeName followed by a colon. This is more efficient than parsing the full id when you only need to verify the type.

isId(id?: string): id is IdOf<R>

Example

if (Book.isId(someId)) {
  // someId is now typed as IdOf<BookRecord>
  const book = store.get(someId)
}

Parameters

string

Returns

id is IdOf<R>

True if the id belongs to this record type

Type guard that checks whether a record belongs to this RecordType.

This method performs a runtime check by comparing the record's typeName against this RecordType's typeName.

isInstance(record?: UnknownRecord): record is R

Example

if (Book.isInstance(someRecord)) {
  // someRecord is now typed as a book record
  console.log(someRecord.title)
}

Parameters

UnknownRecord

Returns

record is R

True if the record is an instance of this record type

Extracts the unique identifier part from a full record id.

Record ids have the format typeName:uniquePart. This method returns just the unique part.

parseId(id: IdOf<R>): string

Example

const bookId = Book.createId() // 'book:abc123'
const uniquePart = Book.parseId(bookId) // 'abc123'

Parameters

IdOf<R>

Returns

string

The unique identifier portion after the colon

Validates a record against this RecordType's validator and returns it with proper typing.

This method runs the configured validator function and throws an error if validation fails. If a previous version of the record is provided, it may use optimized validation.

validate(record: unknown, recordBefore?: R): R

Example

try {
  const validBook = Book.validate(untrustedData)
  // validBook is now properly typed and validated
} catch (error) {
  console.log('Validation failed:', error.message)
}

Parameters

unknown

R

Returns

R

The validated and properly typed record

Create a new RecordType that has the same type name as this RecordType and includes the given default properties.

withDefaultProperties<
  DefaultProps extends Omit<Partial<R>, 'id' | 'typeName'>,
>(
  createDefaultProperties: () => DefaultProps
): RecordType<R, Exclude<RequiredProperties, keyof DefaultProps>>

Example

const authorType = createRecordType('author', () => ({ living: true }))
const deadAuthorType = authorType.withDefaultProperties({ living: false })

Parameters

() => DefaultProps

Returns

RecordType<R, Exclude<RequiredProperties, keyof DefaultProps>>

The new RecordType.