@gencow/core 0.1.0

package/dist/retry.d.ts

@@ -0,0 +1,48 @@
+/**
+ * packages/core/src/retry.ts
+ *
+ * Retry 유틸리티 — exponential backoff + jitter
+ *
+ * 외부 API(LLM, 결제, 이메일 등) 호출 실패 시 자동 재시도.
+ * ctx.retry() 또는 독립 함수 withRetry()로 사용 가능.
+ *
+ * @example
+ * // 독립 함수
+ * import { withRetry } from "@gencow/core";
+ * const result = await withRetry(() => fetch("https://api.example.com"), {
+ *     maxAttempts: 5,
+ *     initialBackoffMs: 500,
+ * });
+ *
+ * // ctx에 내장
+ * export const charge = mutation({
+ *     handler: async (ctx, args) => {
+ *         const result = await ctx.retry(
+ *             () => stripe.charges.create({ amount: args.amount }),
+ *             { maxAttempts: 3, initialBackoffMs: 500 },
+ *         );
+ *         return result;
+ *     },
+ * });
+ */
+export interface RetryOptions {
+    /** 최대 시도 횟수 (기본 3) */
+    maxAttempts?: number;
+    /** 첫 번째 재시도 대기 시간 (ms, 기본 1000) */
+    initialBackoffMs?: number;
+    /** backoff 배수 (기본 2 → 1s, 2s, 4s, 8s, ...) */
+    base?: number;
+    /** 최대 대기 시간 (ms, 기본 30000) */
+    maxBackoffMs?: number;
+    /** 재시도할 에러인지 판단 (기본: 모든 에러 재시도) */
+    shouldRetry?: (error: unknown, attempt: number) => boolean;
+    /** 재시도 시 호출되는 콜백 (로깅용) */
+    onRetry?: (error: unknown, attempt: number, delayMs: number) => void;
+}
+/**
+ * 재시도 가능한 비동기 함수 실행
+ *
+ * Exponential backoff + jitter로 재시도.
+ * delay = min(initialBackoffMs × base^attempt × jitter, maxBackoffMs)
+ */
+export declare function withRetry<T>(fn: () => Promise<T>, options?: RetryOptions): Promise<T>;

package/dist/retry.js

@@ -0,0 +1,75 @@
+/**
+ * packages/core/src/retry.ts
+ *
+ * Retry 유틸리티 — exponential backoff + jitter
+ *
+ * 외부 API(LLM, 결제, 이메일 등) 호출 실패 시 자동 재시도.
+ * ctx.retry() 또는 독립 함수 withRetry()로 사용 가능.
+ *
+ * @example
+ * // 독립 함수
+ * import { withRetry } from "@gencow/core";
+ * const result = await withRetry(() => fetch("https://api.example.com"), {
+ *     maxAttempts: 5,
+ *     initialBackoffMs: 500,
+ * });
+ *
+ * // ctx에 내장
+ * export const charge = mutation({
+ *     handler: async (ctx, args) => {
+ *         const result = await ctx.retry(
+ *             () => stripe.charges.create({ amount: args.amount }),
+ *             { maxAttempts: 3, initialBackoffMs: 500 },
+ *         );
+ *         return result;
+ *     },
+ * });
+ */
+// ─── 기본값 ─────────────────────────────────────────────
+const DEFAULT_MAX_ATTEMPTS = 3;
+const DEFAULT_INITIAL_BACKOFF_MS = 1000;
+const DEFAULT_BASE = 2;
+const DEFAULT_MAX_BACKOFF_MS = 30_000;
+const JITTER_MIN = 0.75;
+const JITTER_MAX = 1.25;
+// ─── 핵심 함수 ──────────────────────────────────────────
+/**
+ * 재시도 가능한 비동기 함수 실행
+ *
+ * Exponential backoff + jitter로 재시도.
+ * delay = min(initialBackoffMs × base^attempt × jitter, maxBackoffMs)
+ */
+export async function withRetry(fn, options = {}) {
+    const { maxAttempts = DEFAULT_MAX_ATTEMPTS, initialBackoffMs = DEFAULT_INITIAL_BACKOFF_MS, base = DEFAULT_BASE, maxBackoffMs = DEFAULT_MAX_BACKOFF_MS, shouldRetry, onRetry, } = options;
+    if (maxAttempts < 1) {
+        throw new Error(`withRetry: maxAttempts must be >= 1, got ${maxAttempts}`);
+    }
+    for (let attempt = 0; attempt < maxAttempts; attempt++) {
+        try {
+            return await fn();
+        }
+        catch (error) {
+            const isLastAttempt = attempt === maxAttempts - 1;
+            // 마지막 시도면 에러 throw
+            if (isLastAttempt)
+                throw error;
+            // shouldRetry가 있으면 판단
+            if (shouldRetry && !shouldRetry(error, attempt))
+                throw error;
+            // 딜레이 계산: exponential backoff + jitter
+            const jitter = JITTER_MIN + Math.random() * (JITTER_MAX - JITTER_MIN);
+            const rawDelay = initialBackoffMs * Math.pow(base, attempt) * jitter;
+            const delay = Math.min(rawDelay, maxBackoffMs);
+            // 콜백 호출
+            if (onRetry)
+                onRetry(error, attempt + 1, delay);
+            await sleep(delay);
+        }
+    }
+    // TypeScript를 위한 unreachable — 실제로 여기에 도달하지 않음
+    throw new Error("withRetry: unreachable");
+}
+// ─── 내부 유틸리티 ──────────────────────────────────────
+function sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}

package/dist/scheduler.d.ts

@@ -0,0 +1,27 @@
+type ActionHandler = (args: any) => Promise<any>;
+export interface Scheduler {
+    /** Schedule a function to run after a delay — Convex의 ctx.scheduler.runAfter() */
+    runAfter(ms: number, action: string, args?: any): string;
+    /** Schedule a function at a specific time — Convex의 ctx.scheduler.runAt() */
+    runAt(timestamp: number | Date, action: string, args?: any): string;
+    /** Cancel a scheduled function */
+    cancel(jobId: string): boolean;
+    /** Register a cron job — Convex의 cronJobs() */
+    cron(name: string, pattern: string, handler: () => Promise<void>): void;
+    /** Register an action handler */
+    registerAction(name: string, handler: ActionHandler): void;
+}
+export declare function getSchedulerInfo(): {
+    crons: {
+        name: string;
+        pattern: string;
+        registeredAt: string;
+    }[];
+    pendingJobs: {
+        id: string;
+        action: string;
+        scheduledAt: string;
+    }[];
+};
+export declare function createScheduler(): Scheduler;
+export {};

package/dist/scheduler.js

@@ -0,0 +1,100 @@
+import * as cron from "node-cron";
+// ─── Implementation ─────────────────────────────────────
+/**
+ * Create a scheduler instance — Convex scheduler 패턴 재현
+ *
+ * @example
+ * const scheduler = createScheduler();
+ *
+ * // Register actions
+ * scheduler.registerAction('emails.send', async (args) => { ... });
+ *
+ * // Schedule (Convex-style)
+ * scheduler.runAfter(5 * 60 * 1000, 'emails.send', { to: 'user@test.com' });
+ *
+ * // Cron (Convex-style)
+ * scheduler.cron('daily-cleanup', '0 2 * * *', async () => { ... });
+ */
+// Module-level state for dashboard introspection
+const _cronInfo = [];
+const _pendingJobs = [];
+export function getSchedulerInfo() {
+    return {
+        crons: _cronInfo,
+        pendingJobs: _pendingJobs,
+    };
+}
+export function createScheduler() {
+    const timers = new Map();
+    const cronJobs = new Map();
+    const actions = new Map();
+    let jobCounter = 0;
+    function generateId() {
+        return `job_${++jobCounter}_${Date.now()}`;
+    }
+    async function executeAction(action, args) {
+        const handler = actions.get(action);
+        if (!handler) {
+            console.error(`[scheduler] Action "${action}" not registered`);
+            return;
+        }
+        try {
+            await handler(args);
+            console.log(`[scheduler] Action "${action}" completed`);
+        }
+        catch (error) {
+            console.error(`[scheduler] Action "${action}" failed:`, error);
+        }
+    }
+    return {
+        runAfter(ms, action, args) {
+            const id = generateId();
+            _pendingJobs.push({ id, action, scheduledAt: new Date().toISOString() });
+            const timer = setTimeout(async () => {
+                await executeAction(action, args);
+                timers.delete(id);
+                const idx = _pendingJobs.findIndex((j) => j.id === id);
+                if (idx >= 0)
+                    _pendingJobs.splice(idx, 1);
+            }, ms);
+            timers.set(id, timer);
+            console.log(`[scheduler] Scheduled "${action}" to run after ${ms}ms (id: ${id})`);
+            return id;
+        },
+        runAt(timestamp, action, args) {
+            const target = timestamp instanceof Date ? timestamp.getTime() : timestamp;
+            const ms = Math.max(0, target - Date.now());
+            return this.runAfter(ms, action, args);
+        },
+        cancel(jobId) {
+            const timer = timers.get(jobId);
+            if (timer) {
+                clearTimeout(timer);
+                timers.delete(jobId);
+                console.log(`[scheduler] Cancelled job ${jobId}`);
+                return true;
+            }
+            return false;
+        },
+        cron(name, pattern, handler) {
+            if (cronJobs.has(name)) {
+                cronJobs.get(name).stop();
+            }
+            const task = cron.schedule(pattern, async () => {
+                console.log(`[scheduler] Cron "${name}" triggered`);
+                try {
+                    await handler();
+                }
+                catch (error) {
+                    console.error(`[scheduler] Cron "${name}" failed:`, error);
+                }
+            });
+            cronJobs.set(name, task);
+            _cronInfo.push({ name, pattern, registeredAt: new Date().toISOString() });
+            console.log(`[scheduler] Registered cron "${name}" with pattern "${pattern}"`);
+        },
+        registerAction(name, handler) {
+            actions.set(name, handler);
+        },
+    };
+}

package/dist/server.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Platform Core — Server Implementations
+ *
+ * Includes Node.js specific modules (e.g. fs, path, crypto) needed for the
+ * executing server. Excluded from client-side core (`index.ts`) so they aren't
+ * bundled into user functions which run in Firecracker.
+ */
+export { createDb } from "./db";
+export { createStorage, storageRoutes } from "./storage";
+export { createScheduler, getSchedulerInfo } from "./scheduler";
+export { authMiddleware, authRoutes, getUsers } from "./auth";

package/dist/server.js

@@ -0,0 +1,11 @@
+/**
+ * Platform Core — Server Implementations
+ *
+ * Includes Node.js specific modules (e.g. fs, path, crypto) needed for the
+ * executing server. Excluded from client-side core (`index.ts`) so they aren't
+ * bundled into user functions which run in Firecracker.
+ */
+export { createDb } from "./db";
+export { createStorage, storageRoutes } from "./storage";
+export { createScheduler, getSchedulerInfo } from "./scheduler";
+export { authMiddleware, authRoutes, getUsers } from "./auth";

package/dist/storage.d.ts

@@ -0,0 +1,33 @@
+interface StorageFile {
+    id: string;
+    name: string;
+    size: number;
+    type: string;
+    path: string;
+}
+export interface Storage {
+    /** Store a file and return a storageId — Convex의 ctx.storage.store() */
+    store(file: File | Blob, filename?: string): Promise<string>;
+    /** Store from raw buffer */
+    storeBuffer(buffer: Buffer, filename: string, type?: string): Promise<string>;
+    /** Get a serving URL for the file — Convex의 ctx.storage.getUrl() */
+    getUrl(storageId: string): string;
+    /** Get file metadata */
+    getMeta(storageId: string): Promise<StorageFile | null>;
+    /** Delete a stored file — Convex의 ctx.storage.delete() */
+    delete(storageId: string): Promise<void>;
+}
+/**
+ * Create a storage instance — Convex storage 패턴 재현
+ *
+ * @example
+ * const storage = createStorage('./uploads');
+ * const id = await storage.store(file);
+ * const url = storage.getUrl(id);
+ */
+export declare function createStorage(dir?: string): Storage;
+/**
+ * Hono routes for serving stored files
+ */
+export declare function storageRoutes(storage: ReturnType<typeof createStorage>, rawSql?: (sql: string, params?: any[]) => Promise<any[]>, storageDir?: string): (c: any) => Promise<any>;
+export {};

package/dist/storage.js

@@ -0,0 +1,98 @@
+import * as fs from "fs/promises";
+import * as path from "path";
+import * as crypto from "crypto";
+// ─── Implementation ─────────────────────────────────────
+const metaStore = new Map();
+/**
+ * Create a storage instance — Convex storage 패턴 재현
+ *
+ * @example
+ * const storage = createStorage('./uploads');
+ * const id = await storage.store(file);
+ * const url = storage.getUrl(id);
+ */
+export function createStorage(dir = "./uploads") {
+    // Ensure directory exists
+    fs.mkdir(dir, { recursive: true }).catch(() => { });
+    return {
+        async store(file, filename) {
+            const id = crypto.randomUUID();
+            const name = filename || (file instanceof File ? file.name : `${id}.bin`);
+            const filePath = path.join(dir, id);
+            const arrayBuffer = await file.arrayBuffer();
+            await fs.writeFile(filePath, Buffer.from(arrayBuffer));
+            metaStore.set(id, {
+                id,
+                name,
+                size: file.size,
+                type: file.type || "application/octet-stream",
+                path: filePath,
+            });
+            return id;
+        },
+        async storeBuffer(buffer, filename, type = "application/octet-stream") {
+            const id = crypto.randomUUID();
+            const filePath = path.join(dir, id);
+            await fs.writeFile(filePath, buffer);
+            metaStore.set(id, {
+                id,
+                name: filename,
+                size: buffer.length,
+                type,
+                path: filePath,
+            });
+            return id;
+        },
+        getUrl(storageId) {
+            return `/api/storage/${storageId}`;
+        },
+        async getMeta(storageId) {
+            return metaStore.get(storageId) || null;
+        },
+        async delete(storageId) {
+            const meta = metaStore.get(storageId);
+            if (meta) {
+                await fs.unlink(meta.path).catch(() => { });
+                metaStore.delete(storageId);
+            }
+        },
+    };
+}
+/**
+ * Hono routes for serving stored files
+ */
+export function storageRoutes(storage, rawSql, storageDir) {
+    return async (c) => {
+        const id = c.req.param("id");
+        let meta = await storage.getMeta(id);
+        // Fallback: DB lookup when in-memory meta is missing (e.g. after server restart)
+        if (!meta && rawSql) {
+            try {
+                const rows = await rawSql(`SELECT storage_id, name, size, type FROM files WHERE storage_id = $1 LIMIT 1`, [id]);
+                if (rows.length > 0) {
+                    const row = rows[0];
+                    const dir = storageDir || "./uploads";
+                    meta = {
+                        id: row.storage_id,
+                        name: row.name,
+                        size: Number(row.size),
+                        type: row.type || "application/octet-stream",
+                        path: path.join(dir, row.storage_id),
+                    };
+                }
+            }
+            catch { /* fallthrough to 404 */ }
+        }
+        if (!meta) {
+            return c.json({ error: "Not found" }, 404);
+        }
+        const file = await fs.readFile(meta.path);
+        return new Response(file, {
+            headers: {
+                "Content-Type": meta.type,
+                "Content-Disposition": `attachment; filename="${encodeURIComponent(meta.name)}"; filename*=UTF-8''${encodeURIComponent(meta.name)}`,
+                "Content-Length": String(meta.size),
+            },
+        });
+    };
+}

package/dist/v.d.ts

@@ -0,0 +1,48 @@
+/**
+ * packages/core/src/v.ts
+ *
+ * Convex-style schema validator for API arguments.
+ * Provides both runtime validation and TypeScript type inference.
+ */
+/**
+ * Validation-specific error — thrown by parseArgs on invalid input.
+ * Allows the server dispatcher to safely distinguish 400 from 500
+ * without fragile string-matching on the error message.
+ */
+export declare class GencowValidationError extends Error {
+    readonly statusCode = 400;
+    constructor(message: string);
+}
+export type Validator<T = any> = {
+    parse(val: any): T;
+    _type: T;
+};
+export type Infer<T> = T extends Validator<infer U> ? U : never;
+export declare const v: {
+    string(): Validator<string>;
+    number(): Validator<number>;
+    boolean(): Validator<boolean>;
+    any(): Validator<any>;
+    optional<T>(inner: Validator<T>): Validator<T | undefined>;
+    object<T extends Record<string, Validator>>(fields: T): Validator<{ [K in keyof T]: Infer<T[K]>; }>;
+    array<T>(inner: Validator<T>): Validator<T[]>;
+};
+/**
+ * Infer TypeScript type from a validator schema or a shorthand record of validators.
+ * Correctly handles optional properties (Validator<T | undefined> → optional key).
+ */
+export type InferArgs<T> = T extends Validator<infer U> ? U : T extends Record<string, Validator> ? {
+    [K in keyof T as T[K] extends Validator<infer U> ? (undefined extends U ? never : K) : K]: T[K] extends Validator<infer U> ? U : any;
+} & {
+    [K in keyof T as T[K] extends Validator<infer U> ? (undefined extends U ? K : never) : never]?: T[K] extends Validator<infer U> ? U : any;
+} : T;
+/**
+ * Validates and parses arguments against a schema at runtime.
+ *
+ * Supports:
+ *   - Full validators: `v.object({ id: v.number() })`, `v.string()`, `v.any()`, etc.
+ *   - Shorthand record: `{ id: v.number(), title: v.string() }` (Convex style)
+ *
+ * Throws `GencowValidationError` (HTTP 400) on validation failure.
+ */
+export declare function parseArgs(schema: any, args: any): any;

package/dist/v.js

@@ -0,0 +1,137 @@
+/**
+ * packages/core/src/v.ts
+ *
+ * Convex-style schema validator for API arguments.
+ * Provides both runtime validation and TypeScript type inference.
+ */
+/**
+ * Validation-specific error — thrown by parseArgs on invalid input.
+ * Allows the server dispatcher to safely distinguish 400 from 500
+ * without fragile string-matching on the error message.
+ */
+export class GencowValidationError extends Error {
+    statusCode = 400;
+    constructor(message) {
+        super(message);
+        this.name = "GencowValidationError";
+    }
+}
+export const v = {
+    string() {
+        return {
+            parse: (val) => {
+                if (typeof val !== "string")
+                    throw new Error(`Expected string, got ${typeof val}`);
+                return val;
+            },
+            _type: "",
+        };
+    },
+    number() {
+        return {
+            parse: (val) => {
+                // Accept numeric strings (e.g. from URL params / form data)
+                const n = typeof val === "string" ? Number(val) : val;
+                if (typeof n !== "number" || isNaN(n))
+                    throw new Error(`Expected number, got ${typeof val}`);
+                return n;
+            },
+            _type: 0,
+        };
+    },
+    boolean() {
+        return {
+            parse: (val) => {
+                if (typeof val !== "boolean")
+                    throw new Error(`Expected boolean, got ${typeof val}`);
+                return val;
+            },
+            _type: false,
+        };
+    },
+    any() {
+        return {
+            parse: (val) => val,
+            _type: null,
+        };
+    },
+    optional(inner) {
+        return {
+            parse: (val) => {
+                if (val === undefined || val === null)
+                    return undefined;
+                return inner.parse(val);
+            },
+            _type: undefined,
+        };
+    },
+    object(fields) {
+        return {
+            parse: (val) => {
+                if (typeof val !== "object" || val === null)
+                    throw new Error("Expected object");
+                const result = {};
+                for (const key in fields) {
+                    result[key] = fields[key].parse(val[key]);
+                }
+                return result;
+            },
+            _type: {},
+        };
+    },
+    array(inner) {
+        return {
+            parse: (val) => {
+                if (!Array.isArray(val))
+                    throw new Error("Expected array");
+                return val.map((item) => inner.parse(item));
+            },
+            _type: [],
+        };
+    },
+};
+/**
+ * Validates and parses arguments against a schema at runtime.
+ *
+ * Supports:
+ *   - Full validators: `v.object({ id: v.number() })`, `v.string()`, `v.any()`, etc.
+ *   - Shorthand record: `{ id: v.number(), title: v.string() }` (Convex style)
+ *
+ * Throws `GencowValidationError` (HTTP 400) on validation failure.
+ */
+export function parseArgs(schema, args) {
+    if (!schema)
+        return args;
+    // Direct Validator (has a .parse method)
+    if (typeof schema.parse === "function") {
+        try {
+            return schema.parse(args);
+        }
+        catch (e) {
+            throw new GencowValidationError(e.message);
+        }
+    }
+    // Shorthand object — e.g. { id: v.number(), title: v.optional(v.string()) }
+    if (typeof schema === "object" && schema !== null) {
+        if (typeof args !== "object" || args === null) {
+            throw new GencowValidationError("Expected an object for arguments");
+        }
+        const result = {};
+        for (const key in schema) {
+            const validator = schema[key];
+            if (validator && typeof validator.parse === "function") {
+                try {
+                    result[key] = validator.parse(args[key]);
+                }
+                catch (e) {
+                    throw new GencowValidationError(`Argument "${key}": ${e.message}`);
+                }
+            }
+            else {
+                result[key] = args[key];
+            }
+        }
+        return result;
+    }
+    return args;
+}

package/package.json

@@ -0,0 +1,39 @@
+{
+    "name": "@gencow/core",
+    "version": "0.1.0",
+    "description": "Gencow core library — defineQuery, defineMutation, reactive subscriptions",
+    "type": "module",
+    "main": "dist/index.js",
+    "types": "dist/index.d.ts",
+    "exports": {
+        ".": {
+            "import": "./dist/index.js",
+            "types": "./dist/index.d.ts"
+        },
+        "./server": {
+            "import": "./dist/server.js",
+            "types": "./dist/server.d.ts"
+        }
+    },
+    "files": [
+        "dist/",
+        "src/"
+    ],
+    "scripts": {
+        "build": "tsc",
+        "typecheck": "tsc --noEmit",
+        "prepublishOnly": "npm run build"
+    },
+    "dependencies": {
+        "@electric-sql/pglite": "^0.3.15",
+        "drizzle-orm": "^0.45.1",
+        "hono": "^4.12.0",
+        "node-cron": "^4.2.1"
+    },
+    "devDependencies": {
+        "@types/bun": "^1.3.9",
+        "@types/node": "^25.3.0",
+        "@types/node-cron": "^3.0.11",
+        "typescript": "^5.9.3"
+    }
+}