polystore 0.15.13 → 0.16.1

package/index.d.ts

@@ -0,0 +1,243 @@
+type Options = {
+    expires?: number | null | string;
+};
+type StoreData<T extends Serializable = Serializable> = {
+    value: T;
+    expires: number | null;
+};
+type Serializable = string | number | boolean | null | (Serializable | null)[] | {
+    [key: string]: Serializable | null;
+};
+interface ClientExpires {
+    EXPIRES: true;
+    promise?: Promise<any>;
+    test?: (client: any) => boolean;
+    get<T extends Serializable>(key: string): Promise<T | null> | T | null;
+    set<T extends Serializable>(key: string, value: T, options?: Options): Promise<any> | any;
+    iterate<T extends Serializable>(prefix: string): AsyncGenerator<[string, T], void, unknown> | Generator<[string, T], void, unknown>;
+    add?<T extends Serializable>(prefix: string, value: T, options?: Options): Promise<string>;
+    has?(key: string): Promise<boolean> | boolean;
+    del?(key: string): Promise<any> | any;
+    keys?(prefix: string): Promise<string[]> | string[];
+    values?<T extends Serializable>(prefix: string): Promise<T[]> | T[];
+    entries?<T extends Serializable>(prefix: string): Promise<[string, T][]> | [string, T][];
+    all?<T extends Serializable>(prefix: string): Promise<Record<string, T>> | Record<string, T>;
+    clear?(prefix: string): Promise<any> | any;
+    clearAll?(): Promise<any> | any;
+    close?(): Promise<any> | any;
+}
+interface ClientNonExpires {
+    EXPIRES: false;
+    promise?: Promise<any>;
+    test?: (client: any) => boolean;
+    get<T extends Serializable>(key: string): Promise<StoreData<T> | null> | StoreData<T> | null;
+    set<T extends Serializable>(key: string, value: StoreData<T> | null, options?: Options): Promise<any> | any;
+    iterate<T extends Serializable>(prefix: string): AsyncGenerator<[string, StoreData<T>], void, unknown> | Generator<[string, StoreData<T>], void, unknown>;
+    add?<T extends Serializable>(prefix: string, value: StoreData<T>, options?: Options): Promise<string>;
+    has?(key: string): Promise<boolean> | boolean;
+    del?(key: string): Promise<any> | any;
+    keys?(prefix: string): Promise<string[]> | string[];
+    values?<T extends Serializable>(prefix: string): Promise<StoreData<T>[]> | StoreData<T>[];
+    entries?<T extends Serializable>(prefix: string): Promise<[string, StoreData<T>][]> | [string, StoreData<T>][];
+    all?<T extends Serializable>(prefix: string): Promise<Record<string, StoreData<T>>> | Record<string, StoreData<T>>;
+    clear?(prefix: string): Promise<any> | any;
+    clearAll?(): Promise<any> | any;
+    close?(): Promise<any> | any;
+}
+type Client = ClientExpires | ClientNonExpires;
+
+declare class Store<TDefault extends Serializable = Serializable> {
+    #private;
+    PREFIX: string;
+    promise: Promise<Client> | null;
+    client: Client;
+    constructor(clientPromise?: any);
+    /**
+     * Save the data on an autogenerated key, can add expiration as well:
+     *
+     * ```js
+     * const key1 = await store.add("value1");
+     * const key2 = await store.add({ hello: "world" });
+     * const key3 = await store.add("value3", { expires: "1h" });
+     * ```
+     *
+     * **[→ Full .add() Docs](https://polystore.dev/documentation#add)**
+     */
+    add(value: TDefault, options?: Options): Promise<string>;
+    add<T extends TDefault>(value: T, options?: Options): Promise<string>;
+    /**
+     * Save the data on the given key, can add expiration as well:
+     *
+     * ```js
+     * const key = await store.set("key1", "value1");
+     * await store.set("key2", { hello: "world" });
+     * await store.set("key3", "value3", { expires: "1h" });
+     * ```
+     *
+     * **[→ Full .set() Docs](https://polystore.dev/documentation#set)**
+     */
+    set(key: string, value: TDefault, options?: Options): Promise<string>;
+    set<T extends TDefault>(key: string, value: T, options?: Options): Promise<string>;
+    /**
+     * Read a single value from the KV store:
+     *
+     * ```js
+     * const value1 = await store.get("key1");
+     * // null (doesn't exist or has expired)
+     * const value2 = await store.get("key2");
+     * // "value2"
+     * const value3 = await store.get("key3");
+     * // { hello: "world" }
+     * ```
+     *
+     * **[→ Full .get() Docs](https://polystore.dev/documentation#get)**
+     */
+    get(key: string): Promise<TDefault | null>;
+    get<T extends TDefault>(key: string): Promise<T | null>;
+    /**
+     * Check whether a key exists or not:
+     *
+     * ```js
+     * if (await store.has("key1")) { ... }
+     * ```
+     *
+     * If you are going to use the value, it's better to just read it:
+     *
+     * ```js
+     * const val = await store.get("key1");
+     * if (val) { ... }
+     * ```
+     *
+     * **[→ Full .has() Docs](https://polystore.dev/documentation#has)**
+     */
+    has(key: string): Promise<boolean>;
+    /**
+     * Remove a single key and its value from the store:
+     *
+     * ```js
+     * const key = await store.del("key1");
+     * ```
+     *
+     * **[→ Full .del() Docs](https://polystore.dev/documentation#del)**
+     */
+    del(key: string): Promise<string>;
+    /**
+     * An iterator that goes through all of the key:value pairs in the client
+     *
+     * ```js
+     * for await (const [key, value] of store) {
+     *   console.log(key, value);
+     * }
+     * ```
+     *
+     * **[→ Full Iterator Docs](https://polystore.dev/documentation#iterator)**
+     */
+    [Symbol.asyncIterator](): AsyncGenerator<[string, TDefault], void, unknown>;
+    [Symbol.asyncIterator]<T extends TDefault>(): AsyncGenerator<[
+        string,
+        T
+    ], void, unknown>;
+    /**
+     * Return an array of the entries, in the [key, value] format:
+     *
+     * ```js
+     * const entries = await store.entries();
+     * // [["key1", "value1"], ["key2", { hello: "world" }], ...]
+     *
+     * // To limit it to a given prefix, use `.prefix()`:
+     * const sessions = await store.prefix("session:").entries();
+     * ```
+     *
+     * **[→ Full .entries() Docs](https://polystore.dev/documentation#entries)**
+     */
+    entries(): Promise<[string, TDefault][]>;
+    entries<T extends TDefault>(): Promise<[string, T][]>;
+    /**
+     * Return an array of the keys in the store:
+     *
+     * ```js
+     * const keys = await store.keys();
+     * // ["key1", "key2", ...]
+     *
+     * // To limit it to a given prefix, use `.prefix()`:
+     * const sessions = await store.prefix("session:").keys();
+     * ```
+     *
+     * **[→ Full .keys() Docs](https://polystore.dev/documentation#keys)**
+     */
+    keys(): Promise<string[]>;
+    /**
+     * Return an array of the values in the store:
+     *
+     * ```js
+     * const values = await store.values();
+     * // ["value1", { hello: "world" }, ...]
+     *
+     * // To limit it to a given prefix, use `.prefix()`:
+     * const sessions = await store.prefix("session:").values();
+     * ```
+     *
+     * **[→ Full .values() Docs](https://polystore.dev/documentation#values)**
+     */
+    values(): Promise<TDefault[]>;
+    values<T extends TDefault>(): Promise<T[]>;
+    /**
+     * Return an object with the keys:values in the store:
+     *
+     * ```js
+     * const obj = await store.all();
+     * // { key1: "value1", key2: { hello: "world" }, ... }
+     *
+     * // To limit it to a given prefix, use `.prefix()`:
+     * const sessions = await store.prefix("session:").all();
+     * ```
+     *
+     * **[→ Full .all() Docs](https://polystore.dev/documentation#all)**
+     */
+    all(): Promise<Record<string, TDefault>>;
+    all<T extends TDefault>(): Promise<Record<string, T>>;
+    /**
+     * Delete all of the records of the store:
+     *
+     * ```js
+     * await store.clear();
+     * ```
+     *
+     * It's useful for cache invalidation, clearing the data, and testing.
+     *
+     * **[→ Full .clear() Docs](https://polystore.dev/documentation#clear)**
+     */
+    clear(): Promise<void>;
+    /**
+     * Create a substore where all the keys are stored with
+     * the given prefix:
+     *
+     * ```js
+     * const session = store.prefix("session:");
+     * await session.set("key1", "value1");
+     * console.log(await session.entries());  // session.
+     * // [["key1", "value1"]]
+     * console.log(await store.entries());  // store.
+     * // [["session:key1", "value1"]]
+     * ```
+     *
+     * **[→ Full .prefix() Docs](https://polystore.dev/documentation#prefix)**
+     */
+    prefix(prefix?: string): Store<TDefault>;
+    /**
+     * Stop the connection to the store, if any:
+     *
+     * ```js
+     * await session.set("key1", "value1");
+     * await store.close();
+     * await session.set("key2", "value2");  // error
+     * ```
+     *
+     * **[→ Full .close() Docs](https://polystore.dev/documentation#close)**
+     */
+    close(): Promise<void>;
+}
+declare function createStore(): Store<Serializable>;
+declare function createStore<T extends Serializable = Serializable>(client?: any): Store<T>;
+
+export { type Client, type Serializable, Store, createStore as default };