@kokimoki/app 2.0.0 → 2.0.1

package/dist/services/kokimoki-storage.js

@@ -0,0 +1,208 @@
+/**
+ * Kokimoki Storage Service
+ *
+ * Provides file upload and management capabilities for game applications. Ideal for media files
+ * (images, videos, audio) and other data not suitable for real-time stores (JSON, text files).
+ *
+ * **Key Features:**
+ * - Upload files to cloud storage with CDN delivery
+ * - Tag-based organization and filtering
+ * - Query uploads by client, MIME type, or tags
+ * - Pagination support for large collections
+ * - Public CDN URLs for direct access
+ *
+ * **Common Use Cases:**
+ * - Player avatars and profile images
+ * - Game screenshots and replays
+ * - User-generated content
+ * - Asset uploads (levels, maps, custom skins)
+ * - JSON configuration files
+ *
+ * Access via `kmClient.storage`
+ *
+ * @example
+ * ```typescript
+ * // Upload an image
+ * const upload = await kmClient.storage.upload('avatar.jpg', imageBlob, ['profile']);
+ *
+ * // Query user's uploads
+ * const myUploads = await kmClient.storage.listUploads({
+ *   clientId: kmClient.id
+ * });
+ *
+ * // Use in store
+ * await kmClient.transact([store], (state) => {
+ *   state.playerAvatar = upload.url;
+ * });
+ * ```
+ */
+export class KokimokiStorageService {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    // Storage
+    async createUpload(name, blob, tags) {
+        const res = await fetch(`${this.client.apiUrl}/uploads`, {
+            method: "POST",
+            headers: this.client.apiHeaders,
+            body: JSON.stringify({
+                name,
+                size: blob.size,
+                mimeType: blob.type,
+                tags,
+            }),
+        });
+        return await res.json();
+    }
+    async uploadChunks(blob, chunkSize, signedUrls) {
+        return await Promise.all(signedUrls.map(async (url, index) => {
+            const start = index * chunkSize;
+            const end = Math.min(start + chunkSize, blob.size);
+            const chunk = blob.slice(start, end);
+            const res = await fetch(url, { method: "PUT", body: chunk });
+            return JSON.parse(res.headers.get("ETag") || '""');
+        }));
+    }
+    async completeUpload(id, etags) {
+        const res = await fetch(`${this.client.apiUrl}/uploads/${id}`, {
+            method: "PUT",
+            headers: this.client.apiHeaders,
+            body: JSON.stringify({ etags }),
+        });
+        return await res.json();
+    }
+    /**
+     * Upload a file to cloud storage.
+     *
+     * Uploads a file (Blob) to Kokimoki storage and returns an Upload object with a public CDN URL.
+     * Files are automatically chunked for efficient upload. The returned URL can be used directly
+     * in your application (e.g., in img tags or store state).
+     *
+     * @param name The filename for the upload
+     * @param blob The Blob object containing the file data
+     * @param tags Optional array of tags for organizing and filtering uploads (default: [])
+     * @returns A promise resolving to the Upload object with CDN URL and metadata
+     *
+     * @example
+     * ```typescript
+     * // Upload image with tags
+     * const upload = await kmClient.storage.upload(
+     *   'avatar.jpg',
+     *   imageBlob,
+     *   ['profile', 'avatar']
+     * );
+     *
+     * // Use the CDN URL
+     * console.log(upload.url); // https://cdn.kokimoki.com/...
+     *
+     * // Store in game state
+     * await kmClient.transact([store], (state) => {
+     *   state.players[kmClient.id].avatar = upload.url;
+     * });
+     * ```
+     */
+    async upload(name, blob, tags = []) {
+        const { id, chunkSize, urls } = await this.createUpload(name, blob, tags);
+        const etags = await this.uploadChunks(blob, chunkSize, urls);
+        return await this.completeUpload(id, etags);
+    }
+    /**
+     * Update metadata for an existing upload.
+     *
+     * Allows you to replace the tags associated with an upload. Useful for reorganizing
+     * or recategorizing uploaded files.
+     *
+     * @param id The upload ID to update
+     * @param update Object containing the new tags array
+     * @returns A promise resolving to the updated Upload object
+     *
+     * @example
+     * ```typescript
+     * // Update tags
+     * const updated = await kmClient.storage.updateUpload(upload.id, {
+     *   tags: ['archived', 'old-profile']
+     * });
+     * ```
+     */
+    async updateUpload(id, update) {
+        const res = await fetch(`${this.client.apiUrl}/uploads/${id}`, {
+            method: "PUT",
+            headers: this.client.apiHeaders,
+            body: JSON.stringify(update),
+        });
+        return await res.json();
+    }
+    /**
+     * Query uploaded files with filtering and pagination.
+     *
+     * Retrieves a list of uploads matching the specified criteria. Supports filtering by
+     * client (uploader), MIME types, and tags. Use pagination for large collections.
+     *
+     * @param filter Optional filter criteria
+     * @param filter.clientId Filter by uploader's client ID
+     * @param filter.mimeTypes Filter by MIME types (e.g., ['image/jpeg', 'image/png'])
+     * @param filter.tags Filter by tags (all specified tags must match)
+     * @param skip Number of results to skip for pagination (default: 0)
+     * @param limit Maximum number of results to return (default: 100)
+     * @returns A promise resolving to paginated Upload results with total count
+     *
+     * @example
+     * ```typescript
+     * // Get current user's images
+     * const myImages = await kmClient.storage.listUploads({
+     *   clientId: kmClient.id,
+     *   mimeTypes: ['image/jpeg', 'image/png']
+     * });
+     *
+     * // Get all profile avatars
+     * const avatars = await kmClient.storage.listUploads({
+     *   tags: ['profile', 'avatar']
+     * });
+     *
+     * // Pagination
+     * const page2 = await kmClient.storage.listUploads({}, 10, 10);
+     * ```
+     */
+    async listUploads(filter = {}, skip = 0, limit = 100) {
+        const url = new URL("/uploads", this.client.apiUrl);
+        url.searchParams.set("skip", skip.toString());
+        url.searchParams.set("limit", limit.toString());
+        if (filter.clientId) {
+            url.searchParams.set("clientId", filter.clientId);
+        }
+        if (filter.mimeTypes) {
+            url.searchParams.set("mimeTypes", filter.mimeTypes.join());
+        }
+        if (filter.tags) {
+            url.searchParams.set("tags", filter.tags.join());
+        }
+        const res = await fetch(url.href, {
+            headers: this.client.apiHeaders,
+        });
+        return await res.json();
+    }
+    /**
+     * Permanently delete an uploaded file.
+     *
+     * Removes the file from cloud storage and the CDN. The URL will no longer be accessible.
+     * This operation cannot be undone.
+     *
+     * @param id The upload ID to delete
+     * @returns A promise resolving to deletion confirmation
+     *
+     * @example
+     * ```typescript
+     * // Delete an upload
+     * const result = await kmClient.storage.deleteUpload(upload.id);
+     * console.log(`Deleted: ${result.deletedCount} file(s)`);
+     * ```
+     */
+    async deleteUpload(id) {
+        const res = await fetch(`${this.client.apiUrl}/uploads/${id}`, {
+            method: "DELETE",
+            headers: this.client.apiHeaders,
+        });
+        return await res.json();
+    }
+}

package/dist/stores/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./kokimoki-local-store";
+export * from "./kokimoki-store";
+export * from "./kokimoki-transaction";

package/dist/stores/index.js

@@ -0,0 +1,3 @@
+export * from "./kokimoki-local-store";
+export * from "./kokimoki-store";
+export * from "./kokimoki-transaction";

package/dist/stores/kokimoki-local-store.d.ts

@@ -0,0 +1,11 @@
+import { KokimokiStore } from "./kokimoki-store";
+export declare class KokimokiLocalStore<T extends object> extends KokimokiStore<T> {
+    private readonly localRoomName;
+    private _stateKey?;
+    private get stateKey();
+    constructor(localRoomName: string, defaultState: T);
+    getInitialUpdate(appId: string, clientId: string): {
+        roomHash: number;
+        initialUpdate: Uint8Array<ArrayBufferLike> | undefined;
+    };
+}

package/dist/stores/kokimoki-local-store.js

@@ -0,0 +1,40 @@
+import { fingerprint32 } from "farmhash-modern";
+import * as Y from "yjs";
+import { RoomSubscriptionMode } from "../core";
+import { KokimokiStore } from "./kokimoki-store";
+export class KokimokiLocalStore extends KokimokiStore {
+    localRoomName;
+    _stateKey;
+    get stateKey() {
+        if (!this._stateKey) {
+            throw new Error("Not initialized");
+        }
+        return this._stateKey;
+    }
+    constructor(localRoomName, defaultState) {
+        super(`/l/${localRoomName}`, defaultState, RoomSubscriptionMode.ReadWrite);
+        this.localRoomName = localRoomName;
+        // Synchronize doc changes to local storage
+        // TODO: maybe do not serialize full state every time
+        this.doc.on("update", () => {
+            const value = Y.encodeStateAsUpdate(this.doc);
+            const valueString = String.fromCharCode(...value);
+            const valueBase64 = btoa(valueString);
+            localStorage.setItem(this.stateKey, valueBase64);
+        });
+    }
+    getInitialUpdate(appId, clientId) {
+        this._stateKey = `${appId}/${clientId}/${this.localRoomName}`;
+        // get initial update from local storage
+        let initialUpdate = undefined;
+        const state = localStorage.getItem(this.stateKey);
+        if (state) {
+            const valueString = atob(state);
+            initialUpdate = Uint8Array.from(valueString, (c) => c.charCodeAt(0));
+        }
+        return {
+            roomHash: fingerprint32(this.roomName),
+            initialUpdate,
+        };
+    }
+}

package/dist/stores/kokimoki-store.d.ts

@@ -0,0 +1,22 @@
+import { Snapshot } from "valtio/vanilla";
+import * as Y from "yjs";
+import { type KokimokiClient, RoomSubscriptionMode } from "../core";
+export declare class KokimokiStore<T extends object> {
+    readonly roomName: string;
+    readonly defaultValue: T;
+    readonly mode: RoomSubscriptionMode;
+    readonly doc: Y.Doc;
+    readonly proxy: T;
+    readonly docRoot: Y.Map<unknown>;
+    readonly connections: {
+        connectionIds: Set<string>;
+        clientIds: Set<string>;
+    };
+    private _unsubscribeConnectionsHandler;
+    constructor(roomName: string, defaultValue: T, mode?: RoomSubscriptionMode);
+    get(): Snapshot<T>;
+    subscribe(set: (value: Snapshot<T>) => void): () => void;
+    onJoin(client: KokimokiClient<any>): Promise<void>;
+    onBeforeLeave(_client: KokimokiClient): Promise<void>;
+    onLeave(_client: KokimokiClient): Promise<void>;
+}

package/dist/stores/kokimoki-store.js

@@ -0,0 +1,117 @@
+import { bind as yjsBind } from "valtio-yjs";
+import { proxy, snapshot, subscribe } from "valtio/vanilla";
+import * as Y from "yjs";
+import { RoomSubscriptionMode } from "../core";
+export class KokimokiStore {
+    roomName;
+    defaultValue;
+    mode;
+    doc;
+    proxy;
+    docRoot;
+    connections;
+    _unsubscribeConnectionsHandler = () => { };
+    constructor(roomName, defaultValue, mode = RoomSubscriptionMode.ReadWrite) {
+        this.roomName = roomName;
+        this.defaultValue = defaultValue;
+        this.mode = mode;
+        // "_connections" is a reserved key for tracking connections
+        if ("_connections" in defaultValue) {
+            throw new Error(`"_connections" is a reserved key in KokimokiStore`);
+        }
+        // Construct Y doc
+        this.doc = new Y.Doc();
+        this.docRoot = this.doc.getMap("root");
+        // Construct proxy object
+        this.proxy = proxy();
+        // @ts-ignore
+        yjsBind(this.proxy, this.docRoot);
+        // Construct connections proxy
+        this.connections = proxy({
+            connectionIds: new Set(),
+            clientIds: new Set(),
+        });
+    }
+    get() {
+        return snapshot(this.proxy);
+    }
+    subscribe(set) {
+        const handler = () => set(this.get());
+        this.doc.on("update", handler);
+        set(this.get());
+        return () => this.doc.off("update", handler);
+    }
+    async onJoin(client) {
+        // Update connections whenever _connections changes
+        let prevConnectionIds = new Set();
+        let prevClientIds = new Set();
+        this._unsubscribeConnectionsHandler = subscribe(this.proxy, () => {
+            // @ts-ignore
+            const newConnectionIds = new Set(
+            // @ts-ignore
+            Object.keys(this.proxy._connections || {}));
+            // Update only if there are changes
+            let connectionIdsChanged = false;
+            if (newConnectionIds.size !== prevConnectionIds.size) {
+                connectionIdsChanged = true;
+            }
+            if (!connectionIdsChanged) {
+                for (const id of newConnectionIds) {
+                    if (!prevConnectionIds.has(id)) {
+                        connectionIdsChanged = true;
+                        break;
+                    }
+                }
+            }
+            if (!connectionIdsChanged) {
+                for (const id of prevConnectionIds) {
+                    if (!newConnectionIds.has(id)) {
+                        connectionIdsChanged = true;
+                        break;
+                    }
+                }
+            }
+            if (connectionIdsChanged) {
+                this.connections.connectionIds = newConnectionIds;
+                prevConnectionIds = new Set(newConnectionIds);
+            }
+            // @ts-ignore
+            const newClientIds = new Set(
+            // @ts-ignore
+            Object.values(this.proxy._connections || {}));
+            // Update only if there are changes
+            let clientIdsChanged = false;
+            if (newClientIds.size !== prevClientIds.size) {
+                clientIdsChanged = true;
+            }
+            if (!clientIdsChanged) {
+                for (const id of newClientIds) {
+                    if (!prevClientIds.has(id)) {
+                        clientIdsChanged = true;
+                        break;
+                    }
+                }
+            }
+            if (!clientIdsChanged) {
+                for (const id of prevClientIds) {
+                    if (!newClientIds.has(id)) {
+                        clientIdsChanged = true;
+                        break;
+                    }
+                }
+            }
+            if (clientIdsChanged) {
+                this.connections.clientIds = newClientIds;
+                prevClientIds = new Set(newClientIds);
+            }
+        });
+        // Add client to _connections map
+        await client.transact([this], ([state]) => {
+            state._connections[client.connectionId] = client.id;
+        });
+    }
+    async onBeforeLeave(_client) { }
+    async onLeave(_client) {
+        this._unsubscribeConnectionsHandler();
+    }
+}

package/dist/stores/kokimoki-transaction.d.ts

@@ -0,0 +1,18 @@
+import { KokimokiStore } from "./kokimoki-store";
+export declare class KokimokiTransaction<T extends object[]> {
+    private _updates;
+    private _consumeMessagesInRooms;
+    private _proxies;
+    private _unbindProxies;
+    constructor(stores: {
+        [K in keyof T]: KokimokiStore<T[K]>;
+    });
+    getProxies(): T;
+    getUpdates(): Promise<{
+        updates: {
+            roomName: string;
+            update: Uint8Array;
+        }[];
+        consumedMessages: Set<string>;
+    }>;
+}

package/dist/stores/kokimoki-transaction.js

@@ -0,0 +1,143 @@
+import { bind as yjsBind } from "valtio-yjs";
+import { proxy as yjsProxy } from "valtio/vanilla";
+import * as Y from "yjs";
+export class KokimokiTransaction {
+    // private _clones = new Map<
+    //   string,
+    //   { docClone: Y.Doc; proxyClone: any; unbindProxy: () => void }
+    // >();
+    _updates = new Map();
+    _consumeMessagesInRooms = new Set();
+    // private _queueMessageCounter = 0;
+    _proxies = [];
+    _unbindProxies = [];
+    constructor(stores) {
+        // Create a proxy for each store
+        for (const store of stores) {
+            // Clone initial state
+            const docClone = new Y.Doc();
+            const docRoot = docClone.getMap("root");
+            Y.applyUpdate(docClone, Y.encodeStateAsUpdate(store.doc));
+            // Set up proxy
+            const proxyClone = yjsProxy();
+            const unbindProxy = yjsBind(proxyClone, docRoot);
+            this._proxies.push(proxyClone);
+            this._unbindProxies.push(unbindProxy);
+            // Listen for updates
+            docClone.on("update", (update) => {
+                if (this._updates.has(store.roomName)) {
+                    const prevUpdate = this._updates.get(store.roomName);
+                    const nextUpdate = Y.mergeUpdates([prevUpdate, update]);
+                    this._updates.set(store.roomName, nextUpdate);
+                }
+                else {
+                    this._updates.set(store.roomName, update);
+                }
+            });
+            // this._clones.set(store.roomName, { docClone, proxyClone, unbindProxy });
+        }
+    }
+    getProxies() {
+        // @ts-ignore
+        return this._proxies;
+    }
+    // private _parseTarget(target: any): {
+    //   roomName: string;
+    //   doc: Y.Doc;
+    //   obj: any;
+    //   key: string;
+    //   path: string[];
+    // } {
+    //   return target();
+    // }
+    // private _parsePath(obj: any, path: string[]) {
+    //   for (let i = 0; i < path.length - 1; i++) {
+    //     if (!(path[i] in obj)) {
+    //       obj[path[i]] = {};
+    //     }
+    //     obj = obj[path[i]];
+    //   }
+    //   return { obj, key: path[path.length - 1] };
+    // }
+    // private _getClone(roomName: string, doc: Y.Doc) {
+    //   if (!this._clones.has(roomName)) {
+    //     // Clone doc
+    //     const docClone = new Y.Doc();
+    //     const docRoot = docClone.getMap("root");
+    //     Y.applyUpdate(docClone, Y.encodeStateAsUpdate(doc));
+    //     // Set up proxy
+    //     const proxyClone = yjsProxy() as any;
+    //     const unbindProxy = yjsBind(proxyClone, docRoot);
+    //     // Listen for updates
+    //     docClone.on("update", (update) => {
+    //       if (this._updates.has(roomName)) {
+    //         const prevUpdate = this._updates.get(roomName)!;
+    //         const nextUpdate = Y.mergeUpdates([prevUpdate, update]);
+    //         this._updates.set(roomName, nextUpdate);
+    //       } else {
+    //         this._updates.set(roomName, update);
+    //       }
+    //     });
+    //     this._clones.set(roomName, { docClone, proxyClone, unbindProxy });
+    //   }
+    //   return this._clones.get(roomName)!;
+    // }
+    // get<T>(target: T): T {
+    //   const { roomName, doc, path } = this._parseTarget(target);
+    //   const { proxyClone } = this._getClone(roomName, doc);
+    //   const { obj, key } = this._parsePath(proxyClone, path);
+    //   return obj[key];
+    // }
+    // set<T>(target: T, value: T) {
+    //   const { roomName, doc, path } = this._parseTarget(target);
+    //   const { proxyClone } = this._getClone(roomName, doc);
+    //   const { obj, key } = this._parsePath(proxyClone, path);
+    //   obj[key] = value;
+    // }
+    // delete<T>(target: T) {
+    //   const { roomName, doc, path } = this._parseTarget(target);
+    //   const { proxyClone } = this._getClone(roomName, doc);
+    //   const { obj, key } = this._parsePath(proxyClone, path);
+    //   delete obj[key];
+    // }
+    // push<T>(target: T[], value: T) {
+    //   const { roomName, doc, path } = this._parseTarget(target);
+    //   const { proxyClone } = this._getClone(roomName, doc);
+    //   const { obj, key } = this._parsePath(proxyClone, path);
+    //   if (!(key in obj)) {
+    //     obj[key] = [];
+    //   }
+    //   obj[key].push(value);
+    // }
+    // queueMessage<T>(queue: KokimokiQueue<S.Generic<T>>, payload: T) {
+    //   const messageId = `${this.kmClient.serverTimestamp()}/${this
+    //     ._queueMessageCounter++}/${Math.random().toString(36).slice(2)}`;
+    //   this.set(queue.root[messageId], payload);
+    //   return messageId;
+    // }
+    // consumeMessage<T>(queue: KokimokiQueue<S.Generic<T>>, messageId: string) {
+    //   if (!queue.proxy[messageId]) {
+    //     throw new Error(
+    //       `Message ${messageId} does not exist or has already been consumed`
+    //     );
+    //   }
+    //   this.delete(queue.root[messageId]);
+    //   this._consumeMessagesInRooms.add(queue.roomName);
+    // }
+    async getUpdates() {
+        // Wait for doc update handling to finish
+        return await new Promise((resolve) => setTimeout(() => {
+            // Clean up
+            for (const unbindProxy of this._unbindProxies) {
+                unbindProxy();
+            }
+            // Generates updates
+            const updates = Array.from(this._updates.entries()).map(([roomName, update]) => ({
+                roomName,
+                update,
+            }));
+            // Done
+            resolve({ updates, consumedMessages: this._consumeMessagesInRooms });
+        }));
+    }
+}

package/dist/types/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./common";
+export * from "./events";
+export * from "./upload";

package/dist/types/index.js

@@ -0,0 +1,3 @@
+export * from "./common";
+export * from "./events";
+export * from "./upload";

package/dist/utils/valtio.d.ts

@@ -0,0 +1,7 @@
+import "valtio";
+declare module "valtio" {
+    function useSnapshot<T extends object>(p: T): T;
+}
+export { proxy, ref, snapshot, subscribe, useSnapshot } from "valtio";
+export { derive, underive } from "derive-valtio";
+export { devtools, subscribeKey, useProxy, watch } from "valtio/utils";

package/dist/utils/valtio.js

@@ -0,0 +1,6 @@
+import "valtio";
+// Core Valtio exports
+export { proxy, ref, snapshot, subscribe, useSnapshot } from "valtio";
+// Valtio utilities
+export { derive, underive } from "derive-valtio";
+export { devtools, subscribeKey, useProxy, watch } from "valtio/utils";

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const KOKIMOKI_APP_VERSION = "2.0.0";
+export declare const KOKIMOKI_APP_VERSION = "2.0.1";

package/dist/version.js

@@ -1 +1,2 @@
-export const KOKIMOKI_APP_VERSION = "2.0.0";
+// Auto-generated file. Do not edit manually.
+export const KOKIMOKI_APP_VERSION = '2.0.1';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kokimoki/app",
-  "version": "2.0.0",
+  "version": "2.0.1",
   "type": "module",
   "description": "Kokimoki app",
   "main": "dist/index.js",
@@ -14,9 +14,9 @@
   },
   "scripts": {
     "test": "NODE_OPTIONS='--import tsx' mocha",
-    "prebuild": "node -p \"'export const KOKIMOKI_APP_VERSION = ' + JSON.stringify(require('./package.json').version) + ';'\" > src/version.ts",
+    "prebuild": "node scripts/generate-version.js",
     "build": "tsc",
-    "postbuild": "rollup --config && cp llms.txt dist/",
+    "postbuild": "rollup --config && cp docs/instructions.md dist/llms.txt",
     "dev": "tsc -w",
     "docs": "typedoc src/index.ts",
     "rollup": "rollup --config"
@@ -44,6 +44,7 @@
     "typescript": "^5.1.6"
   },
   "dependencies": {
+    "derive-valtio": "^0.2.0",
     "events": "^3.3.0",
     "farmhash-modern": "^1.1.0",
     "typed-emitter": "^2.1.0",