@acodeninja/persist 3.3.0 → 3.3.1-next.1

package/docs/storage-engines.md

@@ -23,40 +23,35 @@ export class Tag extends Persist.Model {
 await connection.put(new Tag({tag: 'documentation'}));
 ```
 
-### Versioning with S3 Buckets
+### Caching and stale reads
 
-When you use versioning with an S3 Bucket, you may have to set `pragma` header and `ResponseCacheControl` metadata on all requests. This can be done by adding middleware for both the `build` and `serialize` steps for each request:
+The engine stamps a `Cache-Control` header on every object it writes (models,
+find indexes, and search indexes). By default this is `no-cache`, which lets a
+browser store the object body but requires it to revalidate against S3 (a
+conditional GET on the ETag) before reuse — S3 answers `304 Not Modified` when
+nothing changed, or `200` with fresh data when it did.
 
-```javascript
-import Persist from "@acodeninja/persist";
-import {S3Client} from "@aws-sdk/client-s3";
-import S3StorageEngine from "@acodeninja/persist/storage/s3";
+This matters in the browser: without a stored cache directive, browsers apply
+*heuristic caching* to S3 objects and can serve a stale `_index.json` shortly
+after a write — showing missing new records or lingering deleted ones until a
+hard reload. Stamping `no-cache` on writes avoids this, and because the directive
+travels on the object itself, no read-side or client configuration is needed.
 
-const client = new S3Client();
-
-client.middlewareStack.add(
-    (next, context) => (args) => {
-        args.request.headers['pragma'] = 'no-cache';
-        return next(args);
-    },
-    {step: 'build'},
-);
-
-client.middlewareStack.add(
-    (next, context) => (args) => {
-        args.input.ResponseCacheControl = 'no-cache';
-        return next(args);
-    },
-    {step: 'serialize'},
-);
+If you knowingly serve immutable data and want to opt out (or use a different
+directive), set `cacheControl` on the engine configuration:
 
+```javascript
 const connection = Persist.registerConnection('remote', new S3StorageEngine({
     bucket: 'test-bucket',
-    client,
+    client: new S3Client(),
+    cacheControl: 'max-age=31536000, immutable',
 }));
 ```
 
-These changes will ensure that all requests are made with a `no-cache` header set for getting and putting objects to the S3 bucket.
+> Objects written before this behaviour existed keep serving without the header
+> until they are rewritten. Indexes fix themselves on the next mutation; to update
+> an entire bucket at once you can run:
+> `aws s3 cp s3://bucket s3://bucket --recursive --metadata-directive REPLACE --cache-control no-cache`
 
 ## HTTP Storage StorageEngine
 

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@acodeninja/persist",
-  "version": "3.3.0",
+  "version": "3.3.1-next.1",
   "description": "A JSON based data modelling and persistence module with alternate storage mechanisms.",
   "type": "module",
   "scripts": {
-    "test": "NODE_OPTIONS=\"$NODE_OPTIONS --experimental-vm-modules\" npx jest",
-    "test:watch": "NODE_OPTIONS=\"$NODE_OPTIONS --experimental-vm-modules\" npx jest --watch",
-    "test:coverage": "NODE_OPTIONS=\"$NODE_OPTIONS --experimental-vm-modules\" npx jest --collect-coverage",
+    "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js",
+    "test:watch": "node --experimental-vm-modules node_modules/jest/bin/jest.js --watch",
+    "test:coverage": "node --experimental-vm-modules node_modules/jest/bin/jest.js --collect-coverage",
     "lint": "eslint ./",
     "prepare": "husky"
   },
@@ -22,27 +22,27 @@
     "provenance": true
   },
   "dependencies": {
-    "ajv": "^8.17.1",
+    "ajv": "^8.20.0",
     "ajv-errors": "^3.0.0",
     "ajv-formats": "^3.0.1",
-    "fuse.js": "^7.1.0",
-    "lodash": "^4.17.21",
-    "slugify": "^1.6.6",
-    "ulid": "^2.3.0"
+    "fuse.js": "^7.5.0",
+    "lodash": "^4.18.1",
+    "slugify": "^1.6.9",
+    "ulid": "^3.0.2"
   },
   "optionalDependencies": {
-    "@aws-sdk/client-s3": "^3.735.0"
+    "@aws-sdk/client-s3": "^3.1118.0"
   },
   "devDependencies": {
-    "@commitlint/cli": "^19.6.1",
-    "@commitlint/config-conventional": "^19.6.0",
-    "@eslint/js": "^9.19.0",
-    "@jest/globals": "^29.7.0",
+    "@commitlint/cli": "^21.2.2",
+    "@commitlint/config-conventional": "^21.2.2",
+    "@eslint/js": "^10.0.1",
+    "@jest/globals": "^30.4.1",
     "@semantic-release/commit-analyzer": "^13.0.1",
-    "eslint": "^9.19.0",
-    "globals": "^15.14.0",
+    "eslint": "^10.9.1",
+    "globals": "^17.11.0",
     "husky": "^9.1.7",
-    "jest": "^29.7.0",
-    "semantic-release": "^24.2.1"
+    "jest": "^30.4.2",
+    "semantic-release": "^25.0.9"
   }
 }

package/src/engine/storage/S3StorageEngine.js

@@ -15,6 +15,7 @@ class S3StorageEngine extends StorageEngine {
      * @param {string} [configuration.bucket] - Hostname and protocol of the HTTP service to use (ie: https://example.com).
      * @param {string?} [configuration.prefix] - The prefix on the host to perform operations against.
      * @param {S3Client} [configuration.client] - The http client that implements fetch.
+     * @param {string?} [configuration.cacheControl] - Cache-Control header stamped on written objects. Defaults to 'no-cache'.
      */
     constructor(configuration) {
         super(configuration);
@@ -59,6 +60,7 @@ class S3StorageEngine extends StorageEngine {
             Body: JSON.stringify(model),
             Bucket: this.configuration.bucket,
             ContentType: 'application/json',
+            CacheControl: this.configuration.cacheControl ?? 'no-cache',
         }));
     }
 
@@ -120,6 +122,7 @@ class S3StorageEngine extends StorageEngine {
             Bucket: this.configuration.bucket,
             Body: JSON.stringify(index),
             ContentType: 'application/json',
+            CacheControl: this.configuration.cacheControl ?? 'no-cache',
         }));
     }
 
@@ -160,6 +163,7 @@ class S3StorageEngine extends StorageEngine {
             Bucket: this.configuration.bucket,
             Body: JSON.stringify(index),
             ContentType: 'application/json',
+            CacheControl: this.configuration.cacheControl ?? 'no-cache',
         }));
     }