@heyputer/puter.js 2.0.13 → 2.0.15

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.15",
     "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"
     ],
@@ -25,18 +25,21 @@
     ],
     "scripts": {
         "start-server": "npx http-server --cors -c-1",
-        "start-webpack": "webpack && webpack --output-filename puter.dev.js --watch --devtool source-map",
+        "start-webpack": "webpack --stats=errors-only && webpack --output-filename puter.dev.js --watch --devtool source-map --stats=errors-only",
         "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"
+        "test": "npx http-server --cors -c-1 -o /test",
+        "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"
     },
     "author": "Puter Technologies Inc.",
     "license": "Apache-2.0",
     "devDependencies": {
         "concurrently": "^8.2.2",
+        "http-server": "^14.1.1",
         "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,8 @@ const puterInit = (function() {
         constructor() {
 
             // Initialize the cache using kv.js
-            this._cache = new kvjs();
+            this._cache = new kvjs({dbName: 'puter_cache'});
+            this._opscache = new kvjs();
 
             // "modules" in puter.js are external interfaces for the developer
             this.modules_ = [];
@@ -493,10 +494,21 @@ const puterInit = (function() {
                     console.error('Error accessing localStorage:', error);
                 }
             }
+            // initialize loop for updating caches for major directories
+            if(this.env === 'gui'){
+                // check and update gui fs cache regularly
+                setInterval(puter.checkAndUpdateGUIFScache, 10000);
+            }
             // reinitialize submodules
             this.updateSubmodules();
+
             // rao
             this.request_rao_();
+
+            // perform whoami and cache results
+            puter.getUser().then((user) => {
+                this.whoami = user;
+            });
         };
 
         setAPIOrigin = function(APIOrigin) {
@@ -666,7 +678,12 @@ const puterInit = (function() {
                 // If we went from online to offline, purge the cache
                 if ( wasOnline && !isOnline ) {
                     console.log('Network connection lost - purging cache');
-                    this.purgeCache();
+                    try {
+                        this._cache.flushall();
+                        console.log('Cache purged successfully');
+                    } catch( error ) {
+                        console.error('Error purging cache:', error);
+                    }
                 }
 
                 // Update the previous state
@@ -688,22 +705,48 @@ const puterInit = (function() {
         };
 
         /**
-         * Purges all cached data
-         * @public
+         * Checks and updates the GUI FS cache for most-commonly used paths
+         * @private
          */
-        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');
-                }
-            } catch( error ) {
-                console.error('Error purging cache:', error);
+        checkAndUpdateGUIFScache = function(){
+            // only run in gui environment
+            if(puter.env !== 'gui') return;
+            // only run if user is authenticated
+            if(!puter.whoami) return;
+
+            let username = puter.whoami.username;
+
+            // common paths
+            let home_path = `/${username}`;
+            let desktop_path = `/${username}/Desktop`;
+            let documents_path = `/${username}/Documents`;
+            let public_path = `/${username}/Public`;
+
+            // Home
+            if(!puter._cache.get('readdir:' + home_path)){
+                console.log(`/${username} is not cached, refetching cache`);
+                // fetch home
+                puter.fs.readdir(home_path);
+            }
+            // Desktop
+            if(!puter._cache.get('readdir:' + desktop_path)){
+                console.log(`/${username}/Desktop is not cached, refetching cache`);
+                // fetch desktop
+                puter.fs.readdir(desktop_path);
+            }
+            // Documents
+            if(!puter._cache.get('readdir:' + documents_path)){
+                console.log(`/${username}/Documents is not cached, refetching cache`);
+                // fetch documents
+                puter.fs.readdir(documents_path);
+            }
+            // Public
+            if(!puter._cache.get('readdir:' + public_path)){
+                console.log(`/${username}/Public is not cached, refetching cache`);
+                // fetch public
+                puter.fs.readdir(public_path);
             }
-        };
-
+        }
     }
 
     // Create a new Puter object and return it

package/src/init.cjs

@@ -19,7 +19,7 @@ const init = (authToken) => {
         }
     });
     goodContext.globalThis = goodContext;
-    const code = readFileSync(`${resolve(__filename, '..')}/../dist/puter.js`, 'utf8');
+    const code = readFileSync(`${resolve(__filename, '..')}/../dist/puter.cjs`, 'utf8');
     const context = vm.createContext(goodContext);
     vm.runInNewContext(code, context);
     if ( authToken ) {

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,40 @@ export class PuterJSFileSystemModule extends AdvancedBase {
         });
 
         this.bindSocketEvents();
-
     }
 
     bindSocketEvents() {
+        // 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) => {
+            puter._cache.flushall();
+            console.log('Flushed cache for item.renamed');
+        });
+
+        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.removed');
+        });
+
         this.socket.on('item.added', (item) => {
-            // todo: NAIVE PURGE
             puter._cache.flushall();
+            console.log('Flushed cache for item.added');
         });
-        this.socket.on('item.renamed', (item) => {
-            // todo: NAIVE PURGE
+
+        this.socket.on('item.updated', (item) => {
             puter._cache.flushall();
+            console.log('Flushed cache for item.updated');
         });
+
         this.socket.on('item.moved', (item) => {
-            // todo: NAIVE PURGE
             puter._cache.flushall();
+            console.log('Flushed cache for item.moved');
         });
 
         this.socket.on('connect', () => {
@@ -132,10 +160,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 +207,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 +231,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

@@ -1,6 +1,14 @@
 import * as utils from '../../../lib/utils.js';
 import getAbsolutePathForApp from '../utils/getAbsolutePathForApp.js';
 
+// Track in-flight requests to avoid duplicate backend calls
+// Each entry stores: { promise, timestamp }
+const inflightRequests = new Map();
+
+// Time window (in ms) to group duplicate requests together
+// Requests made within this window will share the same backend call
+const DEDUPLICATION_WINDOW_MS = 2000; // 2 seconds
+
 const readdir = async function (...args) {
     let options;
 
@@ -31,8 +39,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'){
@@ -44,58 +50,108 @@ const readdir = async function (...args) {
             }
         }
 
-        // If auth token is not provided and we are in the web environment, 
-        // try to authenticate with Puter
-        if(!puter.authToken && puter.env === 'web'){
-            try{
-                await puter.ui.authenticateWithPuter();
-            }catch(e){
-                // if authentication fails, throw an error
-                reject('Authentication failed.');
+        // Generate deduplication key based on all request parameters
+        const deduplicationKey = JSON.stringify({
+            path: options.path,
+            uid: options.uid,
+            no_thumbs: options.no_thumbs,
+            no_assocs: options.no_assocs,
+            consistency: options.consistency,
+        });
+
+        // Check if there's already an in-flight request for the same parameters
+        const existingEntry = inflightRequests.get(deduplicationKey);
+        const now = Date.now();
+        
+        if (existingEntry) {
+            const timeSinceRequest = now - existingEntry.timestamp;
+            
+            // Only reuse the request if it's within the deduplication window
+            if (timeSinceRequest < DEDUPLICATION_WINDOW_MS) {
+                // Wait for the existing request and return its result
+                try {
+                    const result = await existingEntry.promise;
+                    resolve(result);
+                } catch (error) {
+                    reject(error);
+                }
+                return;
+            } else {
+                // Request is too old, remove it from the tracker
+                inflightRequests.delete(deduplicationKey);
             }
         }
 
-        // create xhr object
-        const xhr = utils.initXhr('/readdir', this.APIOrigin, undefined, "post", "text/plain;actually=json");
+        // Create a promise for this request and store it to deduplicate concurrent calls
+        const requestPromise = new Promise(async (resolveRequest, rejectRequest) => {
+            // If auth token is not provided and we are in the web environment, 
+            // try to authenticate with Puter
+            if(!puter.authToken && puter.env === 'web'){
+                try{
+                    await puter.ui.authenticateWithPuter();
+                }catch(e){
+                    // if authentication fails, throw an error
+                    rejectRequest('Authentication failed.');
+                    return;
+                }
+            }
 
-        // set up event handlers for load and error events
-        utils.setupXhrEventHandlers(xhr, options.success, options.error, async (result) => {
-            // Calculate the size of the result for cache eligibility check
-            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
+            // create xhr object
+            const xhr = utils.initXhr('/readdir', this.APIOrigin, undefined, "post", "text/plain;actually=json");
 
-            if(resultSize <= MAX_CACHE_SIZE){
-                // UPSERT the cache
-                await puter._cache.set(cacheKey, result, { EX: EXPIRE_TIME });
-            }
+            // set up event handlers for load and error events
+            utils.setupXhrEventHandlers(xhr, options.success, options.error, async (result) => {
+                // Calculate the size of the result for cache eligibility check
+                const resultSize = JSON.stringify(result).length;
+                
+                // Cache the result if it's not bigger than MAX_CACHE_SIZE
+                const MAX_CACHE_SIZE = 100 * 1024 * 1024;
+
+                if(resultSize <= MAX_CACHE_SIZE){
+                    // UPSERT the cache
+                    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 });
+                // set each individual item's cache
+                for(const item of result){
+                    puter._cache.set('item:' + item.path, item);
+                }
+                
+                resolveRequest(result);
+            }, rejectRequest);
+
+            // Build request payload - support both path and uid parameters
+            const payload = {
+                no_thumbs: options.no_thumbs,
+                no_assocs: options.no_assocs,
+                auth_token: this.authToken
+            };
+
+            // Add either uid or path to the payload
+            if (options.uid) {
+                payload.uid = options.uid;
+            } else if (options.path) {
+                payload.path = getAbsolutePathForApp(options.path);
             }
-            
-            resolve(result);
-        }, reject);
 
-        // Build request payload - support both path and uid parameters
-        const payload = {
-            no_thumbs: options.no_thumbs,
-            no_assocs: options.no_assocs,
-            auth_token: this.authToken
-        };
+            xhr.send(JSON.stringify(payload));
+        });
 
-        // Add either uid or path to the payload
-        if (options.uid) {
-            payload.uid = options.uid;
-        } else if (options.path) {
-            payload.path = getAbsolutePathForApp(options.path);
-        }
+        // Store the promise and timestamp in the in-flight tracker
+        inflightRequests.set(deduplicationKey, {
+            promise: requestPromise,
+            timestamp: now,
+        });
 
-        xhr.send(JSON.stringify(payload));
+        // Wait for the request to complete and clean up
+        try {
+            const result = await requestPromise;
+            inflightRequests.delete(deduplicationKey);
+            resolve(result);
+        } catch (error) {
+            inflightRequests.delete(deduplicationKey);
+            reject(error);
+        }
     })
 }
 

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();
+
     })
 }