Keys and expiry

Look up the generic key commands, expiry commands and key scanning with their reply types.

Key commands work on any key regardless of its type: deleting, renaming, copying, sorting and setting expiry.

Example (Expiring and Inspecting a Key)

import {  } from "effect";

import {  } from "@effect-kit/redis";

const  = .(function* () {
  const  = yield* ;

  yield* .("cache:report", "payload");

  const scheduled = yield* .("cache:report", 60);          
const scheduled: boolean
  const remaining = yield* .("cache:report");          
const remaining: bigint
  const removed = yield* .(["cache:report"]);         
const removed: bigint

  return { , ,  };
});

ttl returns -2n for a missing key and -1n for a key with no expiry. Other values are the remaining time in the method's unit.

Methods

Method	Command	Reply type	Purpose
`redis.del`	`DEL`	`bigint`	Delete keys and return how many existed.
`redis.unlink`	`UNLINK`	`bigint`	Delete keys and free their memory in the background.
`redis.exists`	`EXISTS`	`bigint`	Count how many of the given keys exist.
`redis.touch`	`TOUCH`	`bigint`	Update the last access time of keys.
`redis.type`	`TYPE`	`string`	Return the type name of a key.
`redis.rename`	`RENAME`	`void`	Rename a key.
`redis.renamenx`	`RENAMENX`	`boolean`	Rename a key only if the new name is free.
`redis.copy`	`COPY`	`boolean`	Copy a key, optionally to another database.
`redis.move`	`MOVE`	`boolean`	Move a key to another database.
`redis.dump`	`DUMP`	`Option<Uint8Array>`	Serialize a key.
`redis.restore`	`RESTORE`	`void`	Create a key from a serialized value.
`redis.randomkey`	`RANDOMKEY`	`Option<Uint8Array>`	Return a random key.
`redis.keys`	`KEYS`	`readonly Uint8Array[]`	List keys matching a pattern in one command.
`redis.scan`	`SCAN`	`ScanPage<Uint8Array>`	Read one cursor page of keys.
`redis.sort`	`SORT`	`readonly Option<Uint8Array>[]`	Sort a list, set or sorted set.
`redis.sortRo`	`SORT_RO`	`readonly Option<Uint8Array>[]`	Sort without writing, so it can run against replicas.
`redis.sortStore`	`SORT`	`bigint`	Sort and store the result in a key.
`redis.expire`	`EXPIRE`	`boolean`	Set an expiry in seconds.
`redis.pexpire`	`PEXPIRE`	`boolean`	Set an expiry in milliseconds.
`redis.expireat`	`EXPIREAT`	`boolean`	Set an expiry as a Unix time in seconds.
`redis.pexpireat`	`PEXPIREAT`	`boolean`	Set an expiry as a Unix time in milliseconds.
`redis.ttl`	`TTL`	`bigint`	Read the remaining time to live in seconds.
`redis.pttl`	`PTTL`	`bigint`	Read the remaining time to live in milliseconds.
`redis.expiretime`	`EXPIRETIME`	`bigint`	Read the expiry as a Unix time in seconds.
`redis.pexpiretime`	`PEXPIRETIME`	`bigint`	Read the expiry as a Unix time in milliseconds.
`redis.persist`	`PERSIST`	`boolean`	Remove an expiry.
`redis.objectEncoding`	`OBJECT ENCODING`	`Option<Uint8Array>`	Return the internal encoding of a key.
`redis.objectFreq`	`OBJECT FREQ`	`Option<bigint>`	Return the access frequency of a key.
`redis.objectIdletime`	`OBJECT IDLETIME`	`Option<bigint>`	Return the seconds since a key was last accessed.
`redis.objectRefcount`	`OBJECT REFCOUNT`	`Option<bigint>`	Return the reference count of a key.
`redis.objectHelp`	`OBJECT HELP`	`readonly string[]`	Return the OBJECT help text.

Option types

KeyExpireCondition for expire, pexpire, expireat and pexpireat is "NX" | "XX" | "GT" | "LT".

Prop

Type

That table is CopyOptions, used by copy. SortOptions is used by sort, sortRo and sortStore.

Prop

Type

RestoreOptions for restore is { replace?: boolean; absolute?: boolean; idleTime?: number | bigint; frequency?: number }.

Scanning keys

redis.scan reads one page. redis.scanKeys streams every key. Both take KeyScanOptions, which is ScanOptions plus type.

Prop

Type

redis.keys runs KEYS as one command against the whole keyspace. It is not a cursor and not a cluster helper. See Scanning for the stream form and Cluster scanning.

MethodsCopy Anchor Link

Option typesCopy Anchor Link

Scanning keysCopy Anchor Link

On this page

Methods

Option types

Scanning keys