@heyputer/puter.js 2.0.13 → 2.0.14

package/index.d.ts

@@ -32,11 +32,19 @@ declare class Puter {
 
 // AI Module
 interface AI {
-    chat(prompt: string, options?: ChatOptions): Promise<ChatResponse>;
-    chat(prompt: string, testMode?: boolean, options?: ChatOptions): Promise<ChatResponse>;
-    chat(prompt: string, imageURL?: string, testMode?: boolean, options?: ChatOptions): Promise<ChatResponse>;
-    chat(prompt: string, imageURLArray?: string[], testMode?: boolean, options?: ChatOptions): Promise<ChatResponse>;
-    chat(messages: ChatMessage[], testMode?: boolean, options?: ChatOptions): Promise<ChatResponse>;
+    // Streaming overloads
+    chat(prompt: string, options: StreamingChatOptions): AsyncIterable<ChatResponseChunk>;
+    chat(prompt: string, testMode: boolean, options: StreamingChatOptions): AsyncIterable<ChatResponseChunk>;
+    chat(prompt: string, imageURL: string, testMode: boolean, options: StreamingChatOptions): AsyncIterable<ChatResponseChunk>;
+    chat(prompt: string, imageURLArray: string[], testMode: boolean, options: StreamingChatOptions): AsyncIterable<ChatResponseChunk>;
+    chat(messages: ChatMessage[], testMode: boolean, options: StreamingChatOptions): AsyncIterable<ChatResponseChunk>;
+
+    // Non-streaming overloads
+    chat(prompt: string, options?: NonStreamingChatOptions): Promise<ChatResponse>;
+    chat(prompt: string, testMode?: boolean, options?: NonStreamingChatOptions): Promise<ChatResponse>;
+    chat(prompt: string, imageURL?: string, testMode?: boolean, options?: NonStreamingChatOptions): Promise<ChatResponse>;
+    chat(prompt: string, imageURLArray?: string[], testMode?: boolean, options?: NonStreamingChatOptions): Promise<ChatResponse>;
+    chat(messages: ChatMessage[], testMode?: boolean, options?: NonStreamingChatOptions): Promise<ChatResponse>;
 
     img2txt(image: string | File | Blob, testMode?: boolean): Promise<string>;
 
@@ -50,6 +58,9 @@ interface AI {
     txt2speech(text: string, language?: string, voice?: string, engine?: string): Promise<HTMLAudioElement>;
 }
 
+type StreamingChatOptions = Omit<ChatOptions, "stream"> & { stream: true };
+type NonStreamingChatOptions = Omit<ChatOptions, "stream"> & { stream?: false | undefined };
+
 interface ChatOptions {
     model?: string;
     stream?: boolean;
@@ -109,6 +120,11 @@ interface Txt2SpeechOptions {
     engine?: 'standard' | 'neural' | 'generative';
 }
 
+interface ChatResponseChunk {
+    text?: string;
+    [key: string]: any;
+}
+
 // Apps Module
 interface Apps {
     create(name: string, indexURL: string): Promise<App>;
@@ -281,7 +297,9 @@ interface KV {
     set(key: string, value: string | number | boolean | object | any[]): Promise<boolean>;
     get(key: string): Promise<any>;
     del(key: string): Promise<boolean>;
+    incr(key: string, pathAndAmount: { [key: string]: number }): Promise<number>;
     incr(key: string, amount?: number): Promise<number>;
+    decr(key: string, pathAndAmount: { [key: string]: number }): Promise<number>;
     decr(key: string, amount?: number): Promise<number>;
     list(pattern?: string, returnValues?: boolean): Promise<string[] | KVPair[]>;
     list(returnValues?: boolean): Promise<string[] | KVPair[]>;

package/package.json

@@ -1,13 +1,13 @@
 {
     "name": "@heyputer/puter.js",
-    "version": "2.0.13",
+    "version": "2.0.14",
     "description": "Puter.js - A JavaScript library for interacting with Puter services.",
     "main": "src/index.js",
     "types": "index.d.ts",
     "typings": "index.d.ts",
     "type": "module",
     "files": [
-        "dist/puter.js",
+        "dist/puter.cjs",
         "src/",
         "index.d.ts"
     ],
@@ -27,7 +27,8 @@
         "start-server": "npx http-server --cors -c-1",
         "start-webpack": "webpack && webpack --output-filename puter.dev.js --watch --devtool source-map",
         "start": "concurrently \"npm run start-server\" \"npm run start-webpack\"",
-        "build": "webpack && { echo \"// Copyright 2024-present Puter Technologies Inc. All rights reserved.\"; echo \"// Generated on $(date '+%Y-%m-%d %H:%M')\n\"; cat ./dist/puter.js; } > temp && mv temp ./dist/puter.js"
+        "build": "webpack && { echo \"// Copyright 2024-present Puter Technologies Inc. All rights reserved.\"; echo \"// Generated on $(date '+%Y-%m-%d %H:%M')\n\"; cat ./dist/puter.js; } > temp && mv temp ./dist/puter.js",
+        "prepublishOnly": "npm run build && mv dist/puter.js dist/puter.cjs && npm version patch && git add package.json && git commit -m \"chore: bump puter-js version and publish \" && git push"
     },
     "author": "Puter Technologies Inc.",
     "license": "Apache-2.0",
@@ -36,7 +37,7 @@
         "webpack-cli": "^5.1.4"
     },
     "dependencies": {
-        "@heyputer/kv.js": "^0.1.92",
+        "@heyputer/kv.js": "^0.2.1",
         "@heyputer/putility": "^1.0.3"
     }
-}
+}

package/src/index.js

@@ -130,7 +130,7 @@ const puterInit = (function() {
         constructor() {
 
             // Initialize the cache using kv.js
-            this._cache = new kvjs();
+            this._cache = new kvjs({dbName: 'puter_cache'});
 
             // "modules" in puter.js are external interfaces for the developer
             this.modules_ = [];
@@ -693,12 +693,8 @@ const puterInit = (function() {
          */
         purgeCache = function() {
             try {
-                if ( this._cache && typeof this._cache.flushall === 'function' ) {
-                    this._cache.flushall();
-                    console.log('Cache purged successfully');
-                } else {
-                    console.warn('Cache purge failed: cache instance not available');
-                }
+                this._cache.flushall();
+                console.log('Cache purged successfully');
             } catch( error ) {
                 console.error('Error purging cache:', error);
             }

package/src/modules/FileSystem/index.js

@@ -1,4 +1,11 @@
 import io from '../../lib/socket.io/socket.io.esm.min.js';
+import * as utils from '../../lib/utils.js';
+import path from '../../lib/path.js';
+
+// Constants
+// 
+// The last valid time of the local cache.
+const LAST_VALID_TS = 'last_valid_ts';
 
 // Operations
 import copy from './operations/copy.js';
@@ -20,6 +27,7 @@ import FSItem from '../FSItem.js';
 import deleteFSEntry from './operations/deleteFSEntry.js';
 import getReadURL from './operations/getReadUrl.js';
 
+
 export class PuterJSFileSystemModule extends AdvancedBase {
 
     space = space;
@@ -67,6 +75,7 @@ export class PuterJSFileSystemModule extends AdvancedBase {
         this.APIOrigin = context.APIOrigin;
         this.appID = context.appID;
         this.context = context;
+        this.cacheUpdateTimer = null;
         // Connect socket.
         this.initializeSocket();
 
@@ -103,21 +112,75 @@ export class PuterJSFileSystemModule extends AdvancedBase {
         });
 
         this.bindSocketEvents();
-
     }
 
     bindSocketEvents() {
-        this.socket.on('item.added', (item) => {
-            // todo: NAIVE PURGE
+        // this.socket.on('cache.updated', (msg) => {
+        //     // check original_client_socket_id and if it matches this.socket.id, don't post update
+        //     if (msg.original_client_socket_id !== this.socket.id) {
+        //         this.invalidateCache();
+        //     }
+        // });
+
+        this.socket.on('item.renamed', (item) => {
+            // delete old item from cache
+            puter._cache.del('item:' + item.old_path);
+            // if a directory
+            if(item.is_dir){
+                // delete readdir
+                puter._cache.del('readdir:' + item.old_path);
+                // descendants items
+                const descendants = puter._cache.keys('item:' + item.old_path + '/*');
+                for(const descendant of descendants){
+                    console.log('Deleting cache for:', descendant);
+                    puter._cache.del(descendant);
+                }
+                // descendants readdirs
+                const descendants_readdir = puter._cache.keys('readdir:' + item.old_path + '/*');
+                for(const descendant of descendants_readdir){
+                    console.log('Deleting cache for:', descendant);
+                    puter._cache.del(descendant);
+                }
+            }
+            // parent readdir
+            puter._cache.del('readdir:' + path.dirname(item.old_path));
+        });
+
+        this.socket.on('item.removed', (item) => {
+            // check original_client_socket_id and if it matches this.socket.id, don't invalidate cache
             puter._cache.flushall();
+            console.log('Flushed cache for item.deleted');
         });
-        this.socket.on('item.renamed', (item) => {
-            // todo: NAIVE PURGE
+
+        this.socket.on('item.added', (item) => {
+            // delete item from cache
+            puter._cache.del('item:' + item.path);
+            // delete readdir from cache
+            puter._cache.del('readdir:' + item.path);
+            // delete descendant items from cache
+            const descendant_items = puter._cache.keys('item:' + item.path + '/*');
+            for(const descendant of descendant_items){
+                puter._cache.del(descendant);
+            }
+            // delete descendant readdirs from cache
+            const descendant_readdirs = puter._cache.keys('readdir:' + item.path + '/*');
+            for(const descendant of descendant_readdirs){
+                puter._cache.del(descendant);
+            }
+            // delete parent readdir from cache
+            puter._cache.del('readdir:' + path.dirname(item.path));
+        });
+
+        this.socket.on('item.updated', (item) => {
+            // check original_client_socket_id and if it matches this.socket.id, don't invalidate cache
             puter._cache.flushall();
+            console.log('Flushed cache for item.updated');
         });
+
         this.socket.on('item.moved', (item) => {
-            // todo: NAIVE PURGE
+            // check original_client_socket_id and if it matches this.socket.id, don't invalidate cache
             puter._cache.flushall();
+            console.log('Flushed cache for item.moved');
         });
 
         this.socket.on('connect', () => {
@@ -132,10 +195,6 @@ export class PuterJSFileSystemModule extends AdvancedBase {
             {
                 console.log('FileSystem Socket: Disconnected');
             }
-
-            // todo: NAIVE PURGE
-            // purge cache on disconnect since we may have become out of sync
-            puter._cache.flushall();
         });
 
         this.socket.on('reconnect', (attempt) => {
@@ -183,6 +242,14 @@ export class PuterJSFileSystemModule extends AdvancedBase {
      */
     setAuthToken(authToken) {
         this.authToken = authToken;
+
+        // Check cache timestamp and purge if needed (only in GUI environment)
+        if (this.context.env === 'gui') {
+            this.checkCacheAndPurge();
+            // Start background task to update LAST_VALID_TS every 1 second
+            this.startCacheUpdateTimer();
+        }
+
         // reset socket
         this.initializeSocket();
     }
@@ -199,4 +266,100 @@ export class PuterJSFileSystemModule extends AdvancedBase {
         // reset socket
         this.initializeSocket();
     }
+
+    /**
+     * The cache-related actions after local and remote updates.
+     *
+     * @memberof PuterJSFileSystemModule
+     * @returns {void}
+     */
+    invalidateCache() {
+        // Action: Update last valid time
+        // Set to 0, which means the cache is not up to date.
+        localStorage.setItem(LAST_VALID_TS, '0');
+        puter._cache.flushall();
+    }
+
+    /**
+     * Calls the cache API to get the last change timestamp from the server.
+     *
+     * @memberof PuterJSFileSystemModule
+     * @returns {Promise<number>} The timestamp from the server
+     */
+    async getCacheTimestamp() {
+        return new Promise((resolve, reject) => {
+            const xhr = utils.initXhr('/cache/last-change-timestamp', this.APIOrigin, this.authToken, 'get', 'application/json');
+            
+            // set up event handlers for load and error events
+            utils.setupXhrEventHandlers(xhr, undefined, undefined, async (result) => {
+                try {
+                    const response = typeof result === 'string' ? JSON.parse(result) : result;
+                    resolve(response.timestamp || Date.now());
+                } catch (e) {
+                    reject(new Error('Failed to parse response'));
+                }
+            }, reject);
+
+            xhr.send();
+        });
+    }
+
+    /**
+     * Checks cache timestamp and purges cache if needed.
+     * Only runs in GUI environment.
+     *
+     * @memberof PuterJSFileSystemModule
+     * @returns {void}
+     */
+    async checkCacheAndPurge() {
+        try {
+            const serverTimestamp = await this.getCacheTimestamp();
+            const localValidTs = parseInt(localStorage.getItem(LAST_VALID_TS)) || 0;
+            
+            if (serverTimestamp - localValidTs > 2000) {
+                console.log('Cache is not up to date, purging cache');
+                // Server has newer data, purge local cache
+                puter._cache.flushall();
+                localStorage.setItem(LAST_VALID_TS, '0');
+            }
+        } catch (error) {
+            // If we can't get the server timestamp, silently fail
+            // This ensures the socket initialization doesn't break
+            console.error('Error checking cache timestamp:', error);
+        }
+    }
+
+    /**
+     * Starts the background task to update LAST_VALID_TS every 1 second.
+     * Only runs in GUI environment.
+     *
+     * @memberof PuterJSFileSystemModule
+     * @returns {void}
+     */
+    startCacheUpdateTimer() {
+        if (this.context.env !== 'gui') {
+            return;
+        }
+
+        // Clear any existing timer
+        // this.stopCacheUpdateTimer();
+
+        // Start new timer
+        this.cacheUpdateTimer = setInterval(() => {
+            localStorage.setItem(LAST_VALID_TS, Date.now().toString());
+        }, 1000);
+    }
+
+    /**
+     * Stops the background cache update timer.
+     *
+     * @memberof PuterJSFileSystemModule
+     * @returns {void}
+     */
+    stopCacheUpdateTimer() {
+        if (this.cacheUpdateTimer) {
+            clearInterval(this.cacheUpdateTimer);
+            this.cacheUpdateTimer = null;
+        }
+    }
 }

package/src/modules/FileSystem/operations/copy.js

@@ -55,9 +55,6 @@ const copy = function (...args) {
             // if user is copying an item to where its source is, change the name so there is no conflict
             dedupe_name: (options.dedupe_name || options.dedupeName),
         }));
-
-        // todo: EXTREMELY NAIVE CACHE PURGE
-        puter._cache.flushall();
     })
 }
 

package/src/modules/FileSystem/operations/mkdir.js

@@ -1,6 +1,6 @@
+import path from "../../../lib/path.js";
 import * as utils from '../../../lib/utils.js';
 import getAbsolutePathForApp from '../utils/getAbsolutePathForApp.js';
-import path from "../../../lib/path.js"
 
 const mkdir = function (...args) {
     let options = {};
@@ -53,9 +53,6 @@ const mkdir = function (...args) {
             original_client_socket_id: this.socket.id,
             create_missing_parents: (options.recursive || options.createMissingParents) ?? false,
         }));
-
-        // todo: EXTREMELY NAIVE CACHE PURGE
-        puter._cache.flushall();
     })
 }
 

package/src/modules/FileSystem/operations/move.js

@@ -1,7 +1,7 @@
+import path from "../../../lib/path.js";
 import * as utils from '../../../lib/utils.js';
 import getAbsolutePathForApp from '../utils/getAbsolutePathForApp.js';
-import stat from "./stat.js"
-import path from "../../../lib/path.js"
+import stat from "./stat.js";
 
 const move = function (...args) {
     let options;
@@ -65,10 +65,6 @@ const move = function (...args) {
             new_metadata: (options.new_metadata || options.newMetadata),
             original_client_socket_id: options.excludeSocketID,
         }));
-
-        // todo: EXTREMELY NAIVE CACHE PURGE
-        puter._cache.flushall();
-
     })
 }
 

package/src/modules/FileSystem/operations/readdir.js

@@ -31,8 +31,6 @@ const readdir = async function (...args) {
         let cacheKey;
         if(options.path){
             cacheKey = 'readdir:' + options.path;
-        }else if(options.uid){
-            cacheKey = 'readdir:' + options.uid;
         }
 
         if(options.consistency === 'eventual'){
@@ -64,18 +62,16 @@ const readdir = async function (...args) {
             const resultSize = JSON.stringify(result).length;
             
             // Cache the result if it's not bigger than MAX_CACHE_SIZE
-            const MAX_CACHE_SIZE = 20 * 1024 * 1024;
-            const EXPIRE_TIME = 60 * 60; // 1 hour
+            const MAX_CACHE_SIZE = 100 * 1024 * 1024;
 
             if(resultSize <= MAX_CACHE_SIZE){
                 // UPSERT the cache
-                await puter._cache.set(cacheKey, result, { EX: EXPIRE_TIME });
+                puter._cache.set(cacheKey, result);
             }
 
             // set each individual item's cache
             for(const item of result){
-                await puter._cache.set('item:' + item.id, item, { EX: EXPIRE_TIME });
-                await puter._cache.set('item:' + item.path, item, { EX: EXPIRE_TIME });
+                puter._cache.set('item:' + item.path, item);
             }
             
             resolve(result);

package/src/modules/FileSystem/operations/rename.js

@@ -50,8 +50,7 @@ const rename = function (...args) {
         }
         
         xhr.send(JSON.stringify(dataToSend));
-        // todo: EXTREMELY NAIVE CACHE PURGE
-        puter._cache.flushall();
+
     })
 }
 

package/src/modules/FileSystem/operations/stat.js

@@ -39,8 +39,6 @@ const stat = async function (...args) {
         let cacheKey;
         if(options.path){
             cacheKey = 'item:' + options.path;
-        }else if(options.uid){
-            cacheKey = 'item:' + options.uid;
         }
 
         if(options.consistency === 'eventual' && !options.returnSubdomains && !options.returnPermissions && !options.returnVersions && !options.returnSize){
@@ -62,12 +60,10 @@ const stat = async function (...args) {
             
             // Cache the result if it's not bigger than MAX_CACHE_SIZE
             const MAX_CACHE_SIZE = 20 * 1024 * 1024;
-            const EXPIRE_TIME = 60 * 60; // 1 hour
 
             if(resultSize <= MAX_CACHE_SIZE){
                 // UPSERT the cache
-                await puter._cache.set('item:' + result.path, result, { EX: EXPIRE_TIME });
-                await puter._cache.set('item:' + result.uid, result, { EX: EXPIRE_TIME });
+                puter._cache.set(cacheKey, result);
             }
             
             resolve(result);

package/src/modules/FileSystem/operations/upload.js

@@ -1,6 +1,6 @@
+import path from "../../../lib/path.js";
 import * as utils from '../../../lib/utils.js';
 import getAbsolutePathForApp from '../utils/getAbsolutePathForApp.js';
-import path from "../../../lib/path.js"
 
 const upload = async function(items, dirPath, options = {}){
     return new Promise(async (resolve, reject) => {
@@ -429,9 +429,6 @@ const upload = async function(items, dirPath, options = {}){
             options.start();
         }
 
-        // todo: EXTREMELY NAIVE CACHE PURGE
-        puter._cache.flushall();
-
         // send request
         xhr.send(fd);
     })

package/src/modules/FileSystem/operations/write.js

@@ -1,4 +1,4 @@
-import path from "../../../lib/path.js"
+import path from "../../../lib/path.js";
 import getAbsolutePathForApp from '../utils/getAbsolutePathForApp.js';
 
 const write = async function (targetPath, data, options = {}) {
@@ -55,9 +55,6 @@ const write = async function (targetPath, data, options = {}) {
         throw new Error({ code: 'field_invalid', message: 'write() data parameter is an invalid type' });
     }
 
-    // todo: EXTREMELY NAIVE CACHE PURGE
-    puter._cache.flushall();
-
     // perform upload
     return this.upload(data, parent, options);
 }