Storages

These are some kind of data stores. Their main use is in plugins (for example, sessions).

Adapters

GramIO has many ready-made adapters, but you can also write your own!

• In Memory (@gramio/storage)

• Redis (@gramio/storage-redis)

• Cloudflare KV (@gramio/storage-cloudflare)

How to write my own storage adapters

It is very simple to write your adapter!

It is enough to return the object with the required methods and use the methods of the solution you have chosen for the adapter. (for example, ioredis)

import type { Storage } from "@gramio/storage";
import ThirdPartyStorage, { type ThirdPartyStorageOptions } from "some-library";

export interface MyOwnStorageOptions extends ThirdPartyStorageOptions {
    /** add new property to options */
    some?: number;
}

export function myOwnStorage(options: MyOwnStorageOptions = {}): Storage {
    const storage = new ThirdPartyStorage(options);

    return {
        async get(key) {
            const data = await storage.get(key);

            return data ? JSON.parse(data) : undefined;
        },
        async has(key) {
            return storage.has(key);
        },
        async set(key, value) {
            await storage.set(key, JSON.stringify(value));
        },
        async delete(key) {
            return storage.delete(key);
        },
    };
}

IMPORTANT

If you want to publish your adapter, we recommend that you follow the convention and name it starting with gramio-storage and add gramio + gramio-storage keywords in your package.json

How to use storage adapters in my own plugin

It is also very easy to work with storage adapters in your plugin!

Everything we need is already in @gramio/storage.

import { Plugin } from "gramio";
import { type Storage, inMemoryStorage } from "@gramio/storage";

export interface MyOwnPluginOptions {
    storage?: Storage;
}

export function myOwnPlugin(options: MyOwnPluginOptions = {}) {
    // use in memory storage by default
    const storage = options.storage ?? inMemoryStorage();

    return new Plugin("gramio-example");
}

IMPORTANT

You can scaffold this example by create-gramio-plugin

List

In Memory

Installation

npm

npm install @gramio/storage

yarn

yarn add @gramio/storage

pnpm

pnpm add @gramio/storage

bun

bun install @gramio/storage

Usage

1. With default Map

import { inMemoryStorage } from "@gramio/storage";

const storage = inMemoryStorage();

2. Provide your own Map

import { inMemoryStorage, type InMemoryStorageMap } from "@gramio/storage";

const map: InMemoryStorageMap = new Map();

const storage = inMemoryStorage(map);

Redis

Installation

npm

npm install @gramio/storage-redis

yarn

yarn add @gramio/storage-redis

pnpm

pnpm add @gramio/storage-redis

bun

bun install @gramio/storage-redis

Usage

1. Provide ioredis options to the redisStorage function

import { redisStorage } from "@gramio/storage-redis";

const storage = redisStorage({
    host: process.env.REDIS_HOST,
});

2. Provide ioredis instance to the redisStorage function

import { redisStorage } from "@gramio/storage-redis";
import { Redis } from "ioredis";

const redis = new Redis({
    host: process.env.REDIS_HOST,
});

const storage = redisStorage(redis);

Tips

• You can set the DEBUG env to ioredis:* to print debug info:

DEBUG=ioredis:* npm run start

and it will looks like this:

  ioredis:redis write command[::1:6379]: 0 -> get([ '@gramio/scenes:617580375' ]) +187ms
  ioredis:redis write command[::1:6379]: 0 -> set([ '@gramio/scenes:617580375', '{"name":"scene-name","state":{},"stepId":0,"previousStepId":0,"firstTime":false}' ]) +1ms

• For inspecting which data is stored in Redis, we recommend you to use GUI clients like AnotherRedisDesktopManager.

Cloudflare KV

Installation

npm

npm install @gramio/storage-cloudflare

yarn

yarn add @gramio/storage-cloudflare

pnpm

pnpm add @gramio/storage-cloudflare

bun

bun install @gramio/storage-cloudflare

Usage

1. Configure Cloudflare KV namespace

2. Provide Cloudflare KV namespace to the cloudflareStorage function

import { cloudflareStorage } from "@gramio/storage-cloudflare";

const storage = cloudflareStorage(Env.CLOUDFLARE_KV_NAMESPACE);