Custom Plugins

Explains how to implement Storage and Transformer and what to watch for.

Plugin interface overview

Implement plugins following the @unikvs/core types. Storages are data destinations, while Transformers handle transparent conversion.

See the @unikvs/core package reference for detailed signatures.

Implementing Storage

1. Implement the exact semantics of write, read, exists, delete, and clear.
2. Throw a key-not-found error for read and delete on missing keys.
3. If needed, implement open, close, and isOpen. Otherwise, treat the Storage as always open. Memory Storage is an always-open example.
4. If stream writes are needed, add stream acquisition for writing and reading. Decide how non-byte input is handled.
5. If file names or keys have constraints, reuse the validation functions from @unikvs/utils.

import type { IStorage } from "@unikvs/core";

export default class MyStorage implements IStorage {
  public readonly name = "MyStorage";

  public get isOpen(): boolean {
    return true;
  }

  public write(args: Pick<IStorage.WriteArgs<any>, "key" | "data">): void {
    // Implement the write logic
  }

  public read(args: Pick<IStorage.ReadArgs, "key">): unknown {
    // Implement the read logic
  }

  public exists(args: Pick<IStorage.ExistsArgs, "key">): boolean {
    // Implement the existence check
    return false;
  }

  public delete(args: Pick<IStorage.DeleteArgs, "key">): void {
    // Implement the delete logic
  }

  public clear(): void {
    // Implement the clear logic
  }
}

The above is a structural example. Follow the core type definitions for arguments and return values.

Implementing Transformers

1. Define a clear encode/decode correspondence. Verify with unit tests that round-trips restore the original.
2. Clarify whether stream conversion is supported. Throw the corresponding error when it is not supported.
3. If extra information is needed, accept it via runtime variables. The checksum hash specification is an example.
4. If needed, implement open and close.

Defining errors

Extend ErrorBase and define messages that include a description, cause, and resolution. Messages support i18n. The existing InvalidFilenameError and checksum mismatch errors are good references.

Testing

• Verify that a stored value matches the retrieved value.
• Check boundaries for missing keys, empty data, and large data.
• If stream support exists, verify multi-chunk concatenation and behavior on interruption.
• Verify behavior in multi-Storage configurations.