File reads are remembered for one request

1. What you'll see

   A script polls for a file another request is writing, and keeps getting the old content (or null) for the rest of the request.

2. What's actually happening

   A page that includes the same header ten times, or a script that reads the same JSON in a loop, used to ask the database each time. Docly now remembers each path it has looked up for as long as the request lives — for a service, one run of the script. Both hits and misses are remembered.

   Uses the remembered lookup	Always reads fresh
   getFile, getPage, getJson, fileExists, load, include(file), include(file, template), import, <!--#include --> and <!--#master -->	The write functions, loadExcel, getTags and the embedded-file functions

   Your own writes are always visible. Every docly.* function that changes a file or folder — saveFile, saveJson, logJson, the counters, patchFile, deleteFile, moveFile, renameFile, addTag/removeTag, saveFolderProps, createFolder, moveFolder, renameFolder, deleteFolder, saveEmbeddedFile and the rest — clears everything that was remembered, so the next read goes to the database.

   Other requests' writes are not. For the rest of the request, a file reads as it was the first time you looked. The exceptions are the two points where a script waits for something outside itself: after docly.sleep() and after every http* call (which may have reached the site's own API, saving in another request), the lookup starts over.

   This holds in every folder, also directly in the site's root and in #/: a file you create there is found by the next getFile, and a file you delete is gone (fileExists answers false).

3. What to do

   Waiting for a file another request writes

   Call docly.sleep() between the checks — that is also what makes the next check read fresh:

   for (let i = 0; i < 10; i++) {
       let status = docly.getJson("jobs/status.json");
       if (status && status.done) return status;
       docly.sleep(500);
   }

   Reading back a file you just created

   Reading it back works, but if you still have the data in a variable, use that — it saves a database call.

   Nothing to change otherwise

   Including or reading the same file many times in one page is now cheap, so there is no need to read it once into a variable just to save database calls.

Last reviewed 25 Oct 2026