@stnd/core 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# @stnd/core
+
+## 0.1.0
+
+### Minor Changes
+
+- 6d8888a: First release
+
+### Patch Changes
+
+- Updated dependencies [6d8888a]
+  - @stnd/log@0.2.0
+  - @stnd/utils@0.2.0

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@stnd/core",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "dependencies": {
+    "@stnd/log": "0.2.0",
+    "@stnd/utils": "0.2.0"
+  },
+  "devDependencies": {
+    "astro": "^5.0.0",
+    "@types/node": "^20.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  }
+}

package/src/StandardModel.ts

@@ -0,0 +1,55 @@
+
+import { StandardRoot } from "./StandardRoot.js";
+
+export abstract class StandardModel<TData, TRoot extends StandardRoot = StandardRoot> {
+    public raw: TData;
+    protected root: TRoot;
+
+    constructor(root: TRoot, data: TData) {
+        this.root = root;
+        this.raw = data;
+    }
+
+    /**
+     * SERIALIZATION
+     * Strips the circular 'root' dependency for Svelte/React
+     */
+    toJSON(): TData {
+        return this.raw;
+    }
+
+    /**
+     * AUTOMATIC CACHING (The "Standard" Way)
+     * Replaces manual KV logic
+     */
+    protected static async withCache<T>(
+        root: StandardRoot,
+        key: string,
+        fetcher: () => Promise<T | null>,
+        ttl: number = 60 // Default 60s
+    ): Promise<T | null> {
+        const { env } = root;
+
+        // 1. Try KV (Fast Path)
+        if (env.GARDEN_KV) {
+            try {
+                const hit = await env.GARDEN_KV.get(key, { type: "json" });
+                if (hit) return hit as T;
+            } catch (e) {
+                console.warn("KV Get Error", e);
+            }
+        }
+
+        // 2. Fetch Source (Slow Path)
+        const data = await fetcher();
+
+        // 3. Update KV (Background Path)
+        if (data && env.GARDEN_KV) {
+            root.waitUntil(
+                env.GARDEN_KV.put(key, JSON.stringify(data), { expirationTtl: ttl })
+            );
+        }
+
+        return data;
+    }
+}

package/src/StandardRoot.ts

@@ -0,0 +1,73 @@
+import Visitor from "./Visitor.js";
+import Log from "@stnd/log";
+
+const log = Log({ scope: "Root" });
+
+export interface RootServices {
+    db: any;
+    bucket?: any;
+    ai?: any;
+    vectorize?: any;
+    env?: any;
+    ctx?: any;
+}
+
+// Rename to StandardRoot to indicate it's the base
+export class StandardRoot {
+    public db: any;
+    public env: any;
+    public ctx?: any;
+    public url: URL;
+
+    // Visitor is universal (everyone needs auth)
+    public visitor!: Visitor;
+
+    constructor(services: RootServices, url: URL) {
+        this.db = services.db;
+        this.env = services.env;
+        this.ctx = services.ctx;
+        this.url = url;
+    }
+
+    // The Factory
+    static async enter(context: any): Promise<StandardRoot> {
+        const { locals, request } = context;
+        let env: any;
+        let ctx: any;
+
+        if ("cfContext" in locals) {
+            ctx = (locals as any).cfContext;
+        }
+        if ("env" in locals) {
+            env = (locals as any).env;
+        }
+
+        // Fallback logic
+        if (!env) {
+            try {
+                // @ts-ignore
+                const cf = await import("cloudflare:workers");
+                env = cf.env;
+            } catch (e) {
+                // Env might be missing in some contexts
+            }
+        }
+
+        const services = { db: env?.DB, env, ctx };
+        const root = new this(services, new URL(request.url));
+
+        // Initialize Visitor (Universal)
+        root.visitor = await Visitor.fromUrl(root, context);
+
+        return root;
+    }
+
+    // Helper for background tasks
+    public waitUntil(promise: Promise<any>): void {
+        if (this.ctx && typeof this.ctx.waitUntil === "function") {
+            this.ctx.waitUntil(promise);
+        } else {
+            promise.catch(err => console.error(err));
+        }
+    }
+}

package/src/Visitor.ts

@@ -0,0 +1,50 @@
+import Log from "@stnd/log";
+import type { StandardRoot } from "./StandardRoot.js";
+import type { APIContext } from "astro";
+
+const log = Log({ scope: "Visitor" });
+
+export interface VisitorData {
+    id: number;
+    username?: string;
+    email?: string;
+    role?: string;
+    tier?: string;
+    isAnonymous?: boolean;
+    preferences?: any;
+    [key: string]: any;
+}
+
+export default class Visitor {
+    public raw: VisitorData;
+    protected root?: StandardRoot;
+
+    constructor(raw: VisitorData, root?: StandardRoot) {
+        this.raw = raw;
+        this.root = root;
+    }
+
+    /**
+     * FACTORY: Create a Visitor within the Root context
+     * This is a stub implementation that should be overridden or improved
+     * by the specific app implementation if needed, but here we provide
+     * the basic "Anonymous" or "Auth" structure.
+     */
+    static async fromUrl(root: StandardRoot, context: APIContext): Promise<Visitor> {
+        // Basic implementation for now - defaulting to Anonymous
+        // The full auth logic involves DB access which we can add later
+        // or we can copy the logic from the app.
+        // For now, let's keep it simple to get the structure right.
+
+        const { cookies } = context;
+        // Real implementation would check session/jwt here.
+
+        // Return anonymous visitor
+        return new Visitor({
+            id: 1,
+            username: "anonymous",
+            tier: "anonymous",
+            isAnonymous: true
+        }, root);
+    }
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+export * from "./StandardRoot.js";
+export * from "./StandardModel.js";
+export { default as Visitor } from "./Visitor.js";
+export type { VisitorData } from "./Visitor.js";

package/tsconfig.json

@@ -0,0 +1,20 @@
+{
+    "compilerOptions": {
+        "target": "ESNext",
+        "module": "ESNext",
+        "moduleResolution": "bundler",
+        "resolveJsonModule": true,
+        "isolatedModules": true,
+        "esModuleInterop": true,
+        "forceConsistentCasingInFileNames": true,
+        "strict": true,
+        "skipLibCheck": true
+    },
+    "include": [
+        "src/**/*"
+    ],
+    "exclude": [
+        "node_modules",
+        "dist"
+    ]
+}