district.js 0.6.0 → 0.7.0

package/dist/client.d.ts

@@ -1,6 +1,7 @@
 import { EventEmitter } from "node:events";
 import http from "node:http";
 import { REST } from "./rest.js";
+import { Store } from "./store.js";
 import { ClientUser, Message, TextChannel, Interaction, User, Space, type ClientContext, type MessageContent } from "./structures.js";
 import { type EventHeaders } from "./webhook.js";
 import type { ClientOptions, ReactionEvent, DeletedMessage } from "./types.js";
@@ -17,6 +18,8 @@ export interface ClientEvents {
 }
 export declare class Client extends EventEmitter implements ClientContext {
     readonly rest: REST;
+    /** The bot's persistent document store (`client.store.collection("users")…`). */
+    readonly store: Store;
     /** The bot's own identity — populated after `login()`. */
     user: ClientUser | null;
     private signingSecret?;

package/dist/client.js

@@ -3,10 +3,13 @@
 import { EventEmitter } from "node:events";
 import http from "node:http";
 import { REST } from "./rest.js";
+import { Store } from "./store.js";
 import { ClientUser, Message, TextChannel, Interaction, User, Space } from "./structures.js";
 import { verifyAndParse } from "./webhook.js";
 export class Client extends EventEmitter {
     rest;
+    /** The bot's persistent document store (`client.store.collection("users")…`). */
+    store;
     /** The bot's own identity — populated after `login()`. */
     user = null;
     signingSecret;
@@ -15,6 +18,7 @@ export class Client extends EventEmitter {
         if (!options?.token)
             throw new Error("district.js: `token` is required");
         this.rest = new REST(options.token, options.apiBase);
+        this.store = new Store(this.rest);
         this.signingSecret = options.signingSecret;
     }
     // ── typed emitter surface ──────────────────────────────────────────────────

package/dist/index.d.ts

@@ -3,6 +3,7 @@ export { REST, DistrictAPIError, DEFAULT_API_BASE } from "./rest.js";
 export { ClientUser, Message, TextChannel, Interaction, User, Space, SpaceMember, Role, Attachment, Ban, Invite, Webhook, type ClientContext, type MessageContent, } from "./structures.js";
 export { EmbedBuilder, resolveEmbed, type EmbedData, type EmbedField, type EmbedResolvable } from "./embed.js";
 export { ButtonBuilder, ActionRowBuilder, StringSelectMenuBuilder, ModalBuilder, TextInputBuilder, resolveComponent, type ButtonStyle, type ButtonData, type SelectData, type SelectOption, type ComponentData, type ModalData, type TextInputData, type ActionRowData, type ComponentResolvable, } from "./components.js";
+export { Store, StoreCollection, type StoreDocument } from "./store.js";
 export { Collection } from "./collection.js";
 export { PermissionsBitField, type PermissionResolvable, type PermissionFlagName } from "./permissions.js";
 export { Formatters } from "./formatters.js";

package/dist/index.js

@@ -9,6 +9,7 @@ export { REST, DistrictAPIError, DEFAULT_API_BASE } from "./rest.js";
 export { ClientUser, Message, TextChannel, Interaction, User, Space, SpaceMember, Role, Attachment, Ban, Invite, Webhook, } from "./structures.js";
 export { EmbedBuilder, resolveEmbed } from "./embed.js";
 export { ButtonBuilder, ActionRowBuilder, StringSelectMenuBuilder, ModalBuilder, TextInputBuilder, resolveComponent, } from "./components.js";
+export { Store, StoreCollection } from "./store.js";
 export { Collection } from "./collection.js";
 export { PermissionsBitField } from "./permissions.js";
 export { Formatters } from "./formatters.js";

package/dist/store.d.ts

@@ -0,0 +1,41 @@
+import { REST } from "./rest.js";
+/** One stored document: its `key` and JSON `value` (+ last-updated time on reads). */
+export interface StoreDocument<T = any> {
+    key: string;
+    value: T;
+    updatedAt?: string;
+}
+/** A handle to one collection of documents (e.g. "users", "guilds"). */
+export declare class StoreCollection {
+    private readonly rest;
+    readonly name: string;
+    constructor(rest: REST, name: string);
+    /** Read one document's value, or `null` if it doesn't exist. */
+    get<T = any>(key: string): Promise<T | null>;
+    /** Create or fully replace a document. Returns the stored value. */
+    set<T = any>(key: string, value: T): Promise<T>;
+    /** Shallow-merge `partial` into an existing document (creates it if absent).
+     *  Returns the merged value. */
+    update<T = any>(key: string, partial: Partial<T>): Promise<T>;
+    /** Delete a document. No-op if it doesn't exist. */
+    delete(key: string): Promise<void>;
+    /** Atomically add `amount` to a numeric field (default field: `value`). Safe
+     *  under concurrency — two simultaneous increments never lose a write. Pass an
+     *  array for a nested path, e.g. `increment(id, ["stats", "wins"], 1)`. Returns
+     *  the whole updated document value. */
+    increment<T = any>(key: string, field?: string | string[], amount?: number): Promise<T>;
+    /** List documents in this collection (newest-updated first by default). */
+    all<T = any>(opts?: {
+        limit?: number;
+        offset?: number;
+        order?: "asc" | "desc";
+    }): Promise<StoreDocument<T>[]>;
+}
+/** The bot's persistent store. Get a collection with `.collection(name)`. */
+export declare class Store {
+    private readonly rest;
+    private readonly cache;
+    constructor(rest: REST);
+    /** A handle to a named collection (memoized). */
+    collection(name: string): StoreCollection;
+}

package/dist/store.js

@@ -0,0 +1,90 @@
+// Persistent bot storage — the district.js equivalent of "bring your own
+// database". Each bot gets an isolated document store, addressed as
+// `collection` → `key` → JSON `value`, so you can model users, balances,
+// transactions, leaderboards, config… anything a data-heavy bot needs.
+//
+//   const users = client.store.collection("users");
+//   await users.set("42", { balance: 100, streak: 0 });
+//   const me = await users.get<{ balance: number }>("42");
+//   await users.increment("42", "balance", 250);   // atomic — safe under load
+//   const leaderboard = await users.all({ limit: 10 });
+//
+// Everything is scoped to your application automatically; a bot can only ever
+// see its own data.
+import { DistrictAPIError } from "./rest.js";
+const enc = encodeURIComponent;
+/** A handle to one collection of documents (e.g. "users", "guilds"). */
+export class StoreCollection {
+    rest;
+    name;
+    constructor(rest, name) {
+        this.rest = rest;
+        this.name = name;
+    }
+    /** Read one document's value, or `null` if it doesn't exist. */
+    async get(key) {
+        try {
+            const r = await this.rest.get(`/storage/${enc(this.name)}/${enc(key)}`);
+            return r.value;
+        }
+        catch (e) {
+            if (e instanceof DistrictAPIError && e.status === 404)
+                return null;
+            throw e;
+        }
+    }
+    /** Create or fully replace a document. Returns the stored value. */
+    async set(key, value) {
+        const r = await this.rest.put(`/storage/${enc(this.name)}/${enc(key)}`, value);
+        return r.value;
+    }
+    /** Shallow-merge `partial` into an existing document (creates it if absent).
+     *  Returns the merged value. */
+    async update(key, partial) {
+        const r = await this.rest.patch(`/storage/${enc(this.name)}/${enc(key)}`, partial);
+        return r.value;
+    }
+    /** Delete a document. No-op if it doesn't exist. */
+    async delete(key) {
+        await this.rest.delete(`/storage/${enc(this.name)}/${enc(key)}`);
+    }
+    /** Atomically add `amount` to a numeric field (default field: `value`). Safe
+     *  under concurrency — two simultaneous increments never lose a write. Pass an
+     *  array for a nested path, e.g. `increment(id, ["stats", "wins"], 1)`. Returns
+     *  the whole updated document value. */
+    async increment(key, field = "value", amount = 1) {
+        const path = Array.isArray(field) ? field : [field];
+        const r = await this.rest.post(`/storage/${enc(this.name)}/${enc(key)}/increment`, { path, amount });
+        return r.value;
+    }
+    /** List documents in this collection (newest-updated first by default). */
+    async all(opts = {}) {
+        const q = new URLSearchParams();
+        if (opts.limit != null)
+            q.set("limit", String(opts.limit));
+        if (opts.offset != null)
+            q.set("offset", String(opts.offset));
+        if (opts.order)
+            q.set("order", opts.order);
+        const qs = q.toString();
+        const r = await this.rest.get(`/storage/${enc(this.name)}${qs ? `?${qs}` : ""}`);
+        return r.items ?? [];
+    }
+}
+/** The bot's persistent store. Get a collection with `.collection(name)`. */
+export class Store {
+    rest;
+    cache = new Map();
+    constructor(rest) {
+        this.rest = rest;
+    }
+    /** A handle to a named collection (memoized). */
+    collection(name) {
+        let c = this.cache.get(name);
+        if (!c) {
+            c = new StoreCollection(this.rest, name);
+            this.cache.set(name, c);
+        }
+        return c;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "district.js",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "A powerful Node.js module for building District bots — post, react, run slash commands, and receive events.",
   "type": "module",
   "main": "./dist/index.js",