@jayoncode/storage API

---

@jayoncode/storage API

Classes

StorageError

Extends

• Error

Extended by

• AdapterError
• ConfigurationError
• MigrationError
• QuotaExceededError
• SerializationError

Constructors

Constructor

new StorageError(
   message: string, 
   code: StorageErrorCode, 
   options?: StorageErrorOptions): StorageError;

Parameters

Parameter	Type
message	string
code	StorageErrorCode
options	StorageErrorOptions

Returns

StorageError

Overrides

Error.constructor

Properties

Property	Modifier	Type
code	readonly	StorageErrorCode
details	readonly	Readonly<PlainObject> | undefined

---

ConfigurationError

Extends

• StorageError

Constructors

Constructor

new ConfigurationError(message: string, options?: StorageErrorOptions): ConfigurationError;

Parameters

Parameter	Type
message	string
options	StorageErrorOptions

Returns

ConfigurationError

Overrides

StorageError.constructor

Properties

Property	Modifier	Type	Inherited from
code	readonly	StorageErrorCode	StorageError.code
details	readonly	Readonly<PlainObject> | undefined	StorageError.details

---

SerializationError

Extends

• StorageError

Constructors

Constructor

new SerializationError(message: string, options?: StorageErrorOptions): SerializationError;

Parameters

Parameter	Type
message	string
options	StorageErrorOptions

Returns

SerializationError

Overrides

StorageError.constructor

Properties

Property	Modifier	Type	Inherited from
code	readonly	StorageErrorCode	StorageError.code
details	readonly	Readonly<PlainObject> | undefined	StorageError.details

---

QuotaExceededError

Extends

• StorageError

Constructors

Constructor

new QuotaExceededError(message: string, options?: StorageErrorOptions): QuotaExceededError;

Parameters

Parameter	Type
message	string
options	StorageErrorOptions

Returns

QuotaExceededError

Overrides

StorageError.constructor

Properties

Property	Modifier	Type	Inherited from
code	readonly	StorageErrorCode	StorageError.code
details	readonly	Readonly<PlainObject> | undefined	StorageError.details

---

MigrationError

Extends

• StorageError

Constructors

Constructor

new MigrationError(message: string, options?: StorageErrorOptions): MigrationError;

Parameters

Parameter	Type
message	string
options	StorageErrorOptions

Returns

MigrationError

Overrides

StorageError.constructor

Properties

Property	Modifier	Type	Inherited from
code	readonly	StorageErrorCode	StorageError.code
details	readonly	Readonly<PlainObject> | undefined	StorageError.details

---

AdapterError

Extends

• StorageError

Constructors

Constructor

new AdapterError(message: string, options?: StorageErrorOptions): AdapterError;

Parameters

Parameter	Type
message	string
options	StorageErrorOptions

Returns

AdapterError

Overrides

StorageError.constructor

Properties

Property	Modifier	Type	Inherited from
code	readonly	StorageErrorCode	StorageError.code
details	readonly	Readonly<PlainObject> | undefined	StorageError.details

Interfaces

StorageErrorOptions

Properties

Property	Modifier	Type
cause?	readonly	unknown
details?	readonly	PlainObject

---

TtlDuration

Duration for TTL policies — convert to milliseconds at write time.

Properties

Property	Modifier	Type
milliseconds?	readonly	number
seconds?	readonly	number
minutes?	readonly	number
hours?	readonly	number
days?	readonly	number

---

StoragePolicy

Named write preset — v1 honors ttl only.

Properties

Property	Modifier	Type
ttl?	readonly	TtlDuration

---

StorageAdapter

Sync string key/value backend (browser Storage-compatible).

Methods

getItem()

getItem(key: string): string | null;

Parameters

Parameter	Type
key	string

Returns

string | null

setItem()

setItem(key: string, value: string): void;

Parameters

Parameter	Type
key	string
value	string

Returns

void

removeItem()

removeItem(key: string): void;

Parameters

Parameter	Type
key	string

Returns

void

keys()?

optional keys(): readonly string[];

Optional: list all keys (required for namespace clear).

Returns

readonly string[]

---

StorageEnvelopeV1

Type Parameters

Type Parameter	Default type
T	unknown

Properties

Property	Modifier	Type
v	readonly	1
schemaVersion	readonly	string
savedAt	readonly	number
expiresAt?	readonly	number
value	readonly	T

---

CreateStorageOptions

Type Parameters

Type Parameter	Default type
T	unknown

Properties

Property	Modifier	Type	Description
namespace	readonly	string	-
adapter	readonly	StorageAdapter	-
ttl?	readonly	TtlDuration	Default TTL when set omits per-write TTL and policy TTL.
policies?	readonly	Readonly<Record<string, StoragePolicy>>	Named write presets (copied into an instance-local map).
schemaVersion?	readonly	string	App schema id stored on envelopes (default "1").
serialize?	readonly	(value: unknown) => string	-
deserialize?	readonly	(raw: string) => unknown	-
migrate?	readonly	(envelope: StorageEnvelope<T>, fromVersion: string) => StorageEnvelope<T> | null	Called when a loaded envelope's schemaVersion differs from the configured version. Return the migrated envelope, or null to drop the entry.

---

SetStorageOptions

Properties

Property	Modifier	Type	Description
ttl?	readonly	TtlDuration	-
policy?	readonly	string	Named policy from policies / definePolicy (validated even when ttl overrides).

---

JayOnCodeStorage

Type Parameters

Type Parameter	Default type
T	unknown

Properties

Property	Modifier	Type
namespace	readonly	string
schemaVersion	readonly	string

Methods

get()

get(key: string): T | null;

Parameters

Parameter	Type
key	string

Returns

T | null

set()

set(
   key: string, 
   value: T, 
   options?: SetStorageOptions): void;

Parameters

Parameter	Type
key	string
value	T
options?	SetStorageOptions

Returns

void

remove()

remove(key: string): void;

Parameters

Parameter	Type
key	string

Returns

void

has()

has(key: string): boolean;

Whether a non-expired envelope exists. Does not migrate or persist — call get to upgrade schemaVersion.

Parameters

Parameter	Type
key	string

Returns

boolean

clear()

clear(): void;

Remove all keys in this namespace. Requires adapter.keys(); throws ConfigurationError if missing.

Returns

void

peek()

peek(key: string): StorageEnvelope<T> | null;

Read the envelope without applying migration (still drops expired).

Parameters

Parameter	Type
key	string

Returns

StorageEnvelope<T> | null

definePolicy()

definePolicy(name: string, policy: StoragePolicy): void;

Register or replace a named write preset (ttl-only in v1).

Parameters

Parameter	Type
name	string
policy	StoragePolicy

Returns

void

Type Aliases

StorageErrorCode

type StorageErrorCode = 
  | "configuration_error"
  | "serialization_error"
  | "quota_exceeded"
  | "migration_error"
  | "adapter_error";

---

StorageEnvelope

type StorageEnvelope<T> = StorageEnvelopeV1<T>;

Type Parameters

Type Parameter	Default type
T	unknown

Variables

packageId

const packageId: "storage" = "storage";

Stable package id for scaffolding / playground demos.

Functions

createMemoryAdapter()

function createMemoryAdapter(): StorageAdapter;

In-memory adapter backed by a Map. Use for tests, SSR, and ephemeral data.

Import from the package root (not a repo file path):

import { createMemoryAdapter } from "@jayoncode/storage";

Returns

StorageAdapter

---

createLocalStorageAdapter()

function createLocalStorageAdapter(): StorageAdapter;

Explicit localStorage adapter — values survive reload in the browser.

import { createLocalStorageAdapter } from "@jayoncode/storage";

Returns

StorageAdapter

---

createSessionStorageAdapter()

function createSessionStorageAdapter(): StorageAdapter;

Explicit sessionStorage adapter — values last for the tab session.

import { createSessionStorageAdapter } from "@jayoncode/storage";

Returns

StorageAdapter

---

createStorage()

function createStorage<T>(options: CreateStorageOptions<T>): JayOnCodeStorage<T>;

Type Parameters

Type Parameter	Default type
T	unknown

Parameters

Parameter	Type
options	CreateStorageOptions<T>

Returns

JayOnCodeStorage<T>

---

defaultSerialize()

function defaultSerialize(value: unknown): string;

Parameters

Parameter	Type
value	unknown

Returns

string

---

defaultDeserialize()

function defaultDeserialize(raw: string): unknown;

Parameters

Parameter	Type
raw	string

Returns

unknown

---

isQuotaExceededError()

function isQuotaExceededError(error: unknown): boolean;

Parameters

Parameter	Type
error	unknown

Returns

boolean