@raideno/convex-kv 0.1.0

package/README.md

@@ -0,0 +1,73 @@
+# Convex KV
+
+Use a Convex table as a key-value store with optional expiration.
+
+```bash
+npm install @raideno/convex-kv
+```
+
+`convex/schema.ts`
+```ts
+import { defineSchema } from "convex/server";
+import { kvTables } from "@raideno/convex-kv/server";
+
+export default defineSchema({
+  ...kvTables,
+  /*
+   * Your app tables...
+   */
+});
+```
+
+`convex/kv.ts`
+```ts
+import { internalConvexKv } from "@raideno/convex-kv/server";
+
+export const { store, kv } = internalConvexKv();
+```
+
+`convex/actions.ts`
+```ts
+import { action } from "./_generated/server";
+import { v } from "convex/values";
+
+import { kv } from "./kv";
+
+export const save = action({
+  args: {
+    key: v.string(),
+    value: v.any(),
+    ttlMs: v.optional(v.number()),
+  },
+  handler: async (context, args) => {
+    await kv.setWithExpiration(context, {
+      key: args.key,
+      value: args.value,
+      expiresInMs: args.ttlMs,
+    });
+  },
+});
+
+export const load = action({
+  args: {
+    key: v.string(),
+  },
+  handler: async (context, args) => {
+    return await kv.getOrDefault(context, {
+      key: args.key,
+      defaultValue: "not_found",
+    });
+  },
+});
+```
+
+## API
+
+- `kv.set(context, { key, value })`
+- `kv.setWithExpiration(context, { key, value, expiresInMs? | expiresAt? })`
+- `kv.get(context, { key })`
+- `kv.getOrDefault(context, { key, defaultValue })`
+- `kv.has(context, { key })`
+- `kv.delete(context, { key })`
+
+Expired keys are treated as missing and cleaned up lazily on reads.

package/dist/index.d.ts

@@ -0,0 +1,148 @@
+import { AnyDataModel } from 'convex/server';
+import { GenericActionCtx } from 'convex/server';
+import { GenericMutationCtx } from 'convex/server';
+import { RegisteredMutation } from 'convex/server';
+import { TableDefinition } from 'convex/server';
+import { VAny } from 'convex/values';
+import { VFloat64 } from 'convex/values';
+import { VNull } from 'convex/values';
+import { VObject } from 'convex/values';
+import { VString } from 'convex/values';
+import { VUnion } from 'convex/values';
+
+declare type DeleteArgs = {
+    key: string;
+};
+
+declare const DeleteImplementation: (context: GenericActionCtx<AnyDataModel> | GenericMutationCtx<AnyDataModel>, args: DeleteArgs, execution: Execution_2, configuration: InternalConfiguration, options: InternalOptions) => Promise<boolean>;
+
+declare type Execution = {
+    blocking: boolean;
+};
+
+declare type Execution_2 = {
+    blocking: boolean;
+};
+
+declare type GetArgs = {
+    key: string;
+};
+
+declare const GetImplementation: (context: GenericActionCtx<AnyDataModel> | GenericMutationCtx<AnyDataModel>, args: GetArgs, configuration: InternalConfiguration, options: InternalOptions) => Promise<any | null>;
+
+declare const HasImplementation: (context: GenericActionCtx<AnyDataModel> | GenericMutationCtx<AnyDataModel>, args: GetArgs, configuration: InternalConfiguration, options: InternalOptions) => Promise<boolean>;
+
+export declare type InputConfiguration = WithOptional<InternalConfiguration, "execution">;
+
+export declare type InputOptions = WithOptional<InternalOptions, "store" | "debug" | "logger" | "base">;
+
+declare interface InternalConfiguration {
+    execution: Execution;
+}
+
+export declare const internalConvexKv: (configuration_?: InputConfiguration, options_?: InputOptions) => {
+    kv: {
+        /**
+         * Stores a value for the provided key.
+         * @param context the context, can be either an action or mutation context.
+         * @param args the arguments for the set function.
+         * @param execution execution options.
+         * @returns void
+         */
+        set: (context: GenericActionCtx<AnyDataModel> | GenericMutationCtx<AnyDataModel>, args: Parameters<typeof SetImplementation>[1], execution?: {
+            blocking?: boolean;
+        }) => Promise<void>;
+        /**
+         * Stores a value with expiration metadata.
+         * @param context the context, can be either an action or mutation context.
+         * @param args the arguments for the setWithExpiration function.
+         * @param execution execution options.
+         * @returns void
+         */
+        setWithExpiration: (context: GenericActionCtx<AnyDataModel> | GenericMutationCtx<AnyDataModel>, args: {
+            key: string;
+            value: any;
+            expiresAt?: number | null;
+            expiresInMs?: number | null;
+        }, execution?: {
+            blocking?: boolean;
+        }) => Promise<void>;
+        /**
+         * Retrieves a value by key.
+         * Expired values are automatically treated as missing.
+         */
+        get: (context: GenericActionCtx<AnyDataModel> | GenericMutationCtx<AnyDataModel>, args: Parameters<typeof GetImplementation>[1]) => Promise<any>;
+        /**
+         * Retrieves a value by key and falls back to defaultValue if missing.
+         */
+        getOrDefault: <T = any>(context: GenericActionCtx<AnyDataModel> | GenericMutationCtx<AnyDataModel>, args: {
+            key: string;
+            defaultValue: T;
+        }) => Promise<T>;
+        /**
+         * Checks whether a non-expired value exists for a key.
+         */
+        has: (context: GenericActionCtx<AnyDataModel> | GenericMutationCtx<AnyDataModel>, args: Parameters<typeof HasImplementation>[1]) => Promise<boolean>;
+        /**
+         * Deletes a key from the store.
+         * @returns true when at least one entry was deleted.
+         */
+        delete: (context: GenericActionCtx<AnyDataModel> | GenericMutationCtx<AnyDataModel>, args: Parameters<typeof DeleteImplementation>[1], execution?: {
+            blocking?: boolean;
+        }) => Promise<boolean>;
+    };
+    store: RegisteredMutation<"internal", {
+    operation: string;
+    args: any;
+    }, Promise<boolean | void | {
+    found: boolean;
+    value: any;
+    expiresAt: number | null;
+    }>>;
+};
+
+declare interface InternalOptions {
+    store: string;
+    debug: boolean;
+    logger: Logger;
+    base: string;
+}
+
+export declare const kvTables: {
+    kvEntries: TableDefinition<VObject<    {
+    key: string;
+    value: any;
+    expiresAt: number | null;
+    updatedAt: number;
+    }, {
+    key: VString<string, "required">;
+    value: VAny<any, "required", string>;
+    expiresAt: VUnion<number | null, [VNull<null, "required">, VFloat64<number, "required">], "required", never>;
+    updatedAt: VFloat64<number, "required">;
+    }, "required", "key" | "value" | "expiresAt" | "updatedAt" | `value.${string}`>, {
+    byKey: ["key", "_creationTime"];
+    byExpiresAt: ["expiresAt", "_creationTime"];
+    }, {}, {}>;
+};
+
+export declare class Logger {
+    debug_: boolean;
+    constructor(debug: boolean);
+    log(message: string): void;
+    error(message: string): void;
+    warn(message: string): void;
+    debug(message: string): void;
+}
+
+declare type SetArgs = {
+    key: string;
+    value: any;
+    expiresAt?: number | null;
+    expiresInMs?: number | null;
+};
+
+declare const SetImplementation: (context: GenericActionCtx<AnyDataModel> | GenericMutationCtx<AnyDataModel>, args: SetArgs, execution: Execution_2, configuration: InternalConfiguration, options: InternalOptions) => Promise<void>;
+
+declare type WithOptional<T, K extends keyof T = never> = Omit<T, K> & Partial<Pick<T, K>>;
+
+export { }