Valkey OM for Node.js

Valkey OM is an object-mapping library for Valkey and Node.js, written in TypeScript. Define a schema, then save, fetch, and search your objects — stored as Valkey Hashes or JSON documents — with a clean, fluent API. Built on iovalkey.

Requires Valkey with the search and JSON modules — the easiest way is the valkey-bundle image:

docker run -d -p 6379:6379 valkey/valkey-bundle:latest

Installation

npm install valkey-om iovalkey

Quick start

import { Client, Schema, EntityId } from 'valkey-om'

// 1. connect
const client = new Client()
await client.open('valkey://localhost:6379')

// 2. define a schema
const albumSchema = new Schema('album', {
  artist: { type: 'string' },
  title:  { type: 'text' },
  year:   { type: 'number' },
}, { dataStructure: 'JSON' })

// 3. get a repository and build the search index
const albumRepository = client.fetchRepository(albumSchema)
await albumRepository.createIndex()

// 4. save an entity
const album = await albumRepository.save({
  artist: 'Mushroomhead',
  title: 'The Righteous & The Butterfly',
  year: 2014,
})

// 5. fetch it back by id
const fetched = await albumRepository.fetch(album[EntityId])

// 6. search
const byArtist = await albumRepository.search()
  .where('artist').equals('Mushroomhead')
  .return.all()

const recent = await albumRepository.search()
  .where('year').gte(2000)
  .return.all()

const byText = await albumRepository.search()
  .where('title').matches('righteous')
  .return.all()

await client.close()

Using your own iovalkey connection

You can pass an existing iovalkey client instead of letting Valkey OM open one:

import Valkey from 'iovalkey'
import { Client } from 'valkey-om'

const valkey = new Valkey({ host: 'localhost', port: 6379 })
const client = await new Client().use(valkey)

Field types

string (tag), text (full-text), number, boolean, date, point (geo), and their array variants — for both HASH and JSON data structures.

License

MIT. Valkey OM is a Valkey-native port of an upstream Node.js ODM; the original copyright is preserved in the LICENSE.