gh-as-db 1.0.0 → 1.1.0

package/README.md

@@ -71,7 +71,7 @@ const db = new GitHubDB({
   accessToken: string; // GitHub PAT with 'repo' scope
   owner: string;       // Repository owner
   repo: string;        // Repository name
-  branch?: string;     // Optional: branch to use (defaults to 'main')
+  cacheTTL?: number;   // Optional: Cache TTL in ms. Default is 0 (strict consistency).
 });
 ```
 
@@ -155,7 +155,8 @@ For small projects, side-projects, or internal tools, setting up a database serv
 
 ## Performance
 
-- **Caching**: Data is fetched once and cached in memory. Subsequent reads are near-instant.
+- **Consistent Caching**: Uses **Conditional GET** (`If-None-Match`) to ensure data is always up-to-date even across multiple instances (e.g., serverless), while minimizing API costs.
+- **Write-Through**: Updates the local cache immediately after a write, preventing 404s during redirects.
 - **Indexing**: Automatic in-memory indexing on all fields makes querying fast even as data grows.
 - **Optimistic Concurrency**: Uses Git SHAs to ensure that you don't overwrite changes made by another client.
 

package/dist/core/types.d.ts

@@ -2,6 +2,7 @@ export interface GitHubDBConfig {
     accessToken: string;
     owner: string;
     repo: string;
+    cacheTTL?: number;
 }
 export type Schema = Record<string, any>;
 export type MiddlewareOperation = "create" | "update" | "read" | "delete";

package/dist/index.d.ts

@@ -1 +1,4 @@
-export declare const version = "0.1.0";
+export { GitHubDB } from "./ui/github-db.js";
+export { Collection } from "./ui/collection.js";
+export * from "./core/types.js";
+export declare const version = "1.0.1";

package/dist/index.js

@@ -1 +1,4 @@
-export const version = "0.1.0";
+export { GitHubDB } from "./ui/github-db.js";
+export { Collection } from "./ui/collection.js";
+export * from "./core/types.js";
+export const version = "1.0.1";

package/dist/infrastructure/cache-provider.js

@@ -4,14 +4,14 @@ export class MemoryCacheProvider {
         const entry = this.cache.get(key);
         if (!entry)
             return null;
-        if (entry.expiry !== null && Date.now() > entry.expiry) {
+        if (entry.expiry !== null && Date.now() >= entry.expiry) {
             this.cache.delete(key);
             return null;
         }
         return entry.data;
     }
     set(key, value, ttl) {
-        const expiry = ttl ? Date.now() + ttl : null;
+        const expiry = ttl !== undefined ? Date.now() + ttl : null;
         this.cache.set(key, { data: value, expiry });
     }
     delete(key) {

package/dist/infrastructure/github-storage.d.ts

@@ -4,6 +4,8 @@ export declare class GitHubStorageProvider implements IStorageProvider {
     private config;
     private octokit;
     private cache;
+    private staleCache;
+    private readonly DEFAULT_TTL;
     constructor(config: GitHubDBConfig, cache?: ICacheProvider);
     testConnection(): Promise<boolean>;
     exists(path: string): Promise<boolean>;

package/dist/infrastructure/github-storage.js

@@ -5,10 +5,12 @@ export class GitHubStorageProvider {
     config;
     octokit;
     cache;
+    staleCache = new Map();
+    DEFAULT_TTL = 0; // Default to 0 for consistency
     constructor(config, cache) {
         this.config = config;
         this.octokit = new Octokit({
-            auth: config.accessToken,
+            auth: this.config.accessToken,
         });
         this.cache = cache || new MemoryCacheProvider();
     }
@@ -25,6 +27,9 @@ export class GitHubStorageProvider {
         }
     }
     async exists(path) {
+        if (this.cache.get(path) || this.staleCache.has(path)) {
+            return true;
+        }
         try {
             await this.octokit.repos.getContent({
                 owner: this.config.owner,
@@ -41,45 +46,69 @@ export class GitHubStorageProvider {
         }
     }
     async readJson(path) {
-        const cached = this.cache.get(path);
-        if (cached) {
-            return cached;
+        // 1. Check fresh cache (blind trust)
+        const fresh = this.cache.get(path);
+        if (fresh) {
+            return fresh;
         }
-        const response = await this.octokit.repos.getContent({
-            owner: this.config.owner,
-            repo: this.config.repo,
-            path,
-        });
-        if (Array.isArray(response.data)) {
-            throw new Error("Path is a directory, not a file");
+        // 2. Check stale cache for conditional request
+        const stale = this.staleCache.get(path);
+        try {
+            const response = await this.octokit.repos.getContent({
+                owner: this.config.owner,
+                repo: this.config.repo,
+                path,
+                headers: stale ? { "if-none-match": `"${stale.sha}"` } : {},
+            });
+            if (Array.isArray(response.data)) {
+                throw new Error("Path is a directory, not a file");
+            }
+            if (!("content" in response.data) || !("sha" in response.data)) {
+                throw new Error("No content or SHA in response");
+            }
+            const content = Buffer.from(response.data.content, "base64").toString("utf-8");
+            const result = {
+                data: JSON.parse(content),
+                sha: response.data.sha,
+            };
+            // Update both caches
+            const ttl = this.config.cacheTTL ?? this.DEFAULT_TTL;
+            this.cache.set(path, result, ttl);
+            this.staleCache.set(path, result);
+            return result;
         }
-        if (!("content" in response.data) || !("sha" in response.data)) {
-            throw new Error("No content or SHA in response");
+        catch (error) {
+            if (error.status === 304 && stale) {
+                // Re-cache as fresh and return stale data
+                const ttl = this.config.cacheTTL ?? this.DEFAULT_TTL;
+                this.cache.set(path, stale, ttl);
+                return stale;
+            }
+            throw error;
         }
-        const content = Buffer.from(response.data.content, "base64").toString("utf-8");
-        const result = {
-            data: JSON.parse(content),
-            sha: response.data.sha,
-        };
-        this.cache.set(path, result);
-        return result;
     }
     async writeJson(path, content, message, sha) {
         let internalSha = sha;
         if (!internalSha) {
-            try {
-                const existing = await this.octokit.repos.getContent({
-                    owner: this.config.owner,
-                    repo: this.config.repo,
-                    path,
-                });
-                if (!Array.isArray(existing.data) && "sha" in existing.data) {
-                    internalSha = existing.data.sha;
-                }
+            const cached = this.cache.get(path) || this.staleCache.get(path);
+            if (cached) {
+                internalSha = cached.sha;
             }
-            catch (error) {
-                if (error.status !== 404) {
-                    throw error;
+            else {
+                try {
+                    const existing = await this.octokit.repos.getContent({
+                        owner: this.config.owner,
+                        repo: this.config.repo,
+                        path,
+                    });
+                    if (!Array.isArray(existing.data) && "sha" in existing.data) {
+                        internalSha = existing.data.sha;
+                    }
+                }
+                catch (error) {
+                    if (error.status !== 404) {
+                        throw error;
+                    }
                 }
             }
         }
@@ -93,7 +122,10 @@ export class GitHubStorageProvider {
                 sha: internalSha,
             });
             const newSha = response.data.content?.sha || "";
-            this.cache.delete(path);
+            const result = { data: content, sha: newSha };
+            const ttl = this.config.cacheTTL ?? this.DEFAULT_TTL;
+            this.cache.set(path, result, ttl);
+            this.staleCache.set(path, result);
             return newSha;
         }
         catch (error) {

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "gh-as-db",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Use a private GitHub repository as a database for your application.",
   "type": "module",
   "main": "./dist/index.js",
+  "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {