@vllnt/convex-helpers 0.1.0-canary.df58580

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 bntvllnt
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,92 @@
+<!-- Badges -->
+[![npm version](https://img.shields.io/npm/v/@vllnt/convex-helpers.svg)](https://www.npmjs.com/package/@vllnt/convex-helpers)
+[![CI](https://github.com/vllnt/convex-helpers/actions/workflows/ci.yml/badge.svg)](https://github.com/vllnt/convex-helpers/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/npm/l/@vllnt/convex-helpers.svg)](./LICENSE)
+
+# @vllnt/convex-helpers
+
+Typed host-side helpers for Convex backends — builders, errors, validators, relationships,
+pagination, HTTP, env, and observability.
+
+```ts
+import { asyncMap, pruneNull, nullThrows } from "@vllnt/convex-helpers";
+
+const docs = pruneNull(await asyncMap(ids, (id) => ctx.db.get(id)));
+const doc = nullThrows(await ctx.db.get(id), `Document ${id} not found`);
+```
+
+A helpers library (not a sandboxed Convex component): pure functions and host-`ctx` glue that run with
+the host's `ctx` — no own tables, no `app.use()` mounting. Stateful concerns (rate limiting,
+idempotency, flags) belong in `@convex-dev/*` or `@vllnt/convex-*` components.
+
+See [ROADMAP.md](./ROADMAP.md) for the planned module surface.
+
+## Features
+
+- `asyncMap` — parallel async map that preserves order
+- `pruneNull` — filter null/undefined from arrays
+- `nullThrows` — non-null assertion with typed `NullDocumentError`
+- [planned] `./builders` — `customQuery`/`customMutation`/`customAction`/`customCtx`
+- [planned] `./errors` — typed `AppError` + HTTP-status map
+- [planned] `./auth` — provider-agnostic `requireIdentity`/`getCurrentSubject`
+- [planned] `./env` — `defineEnv(zodSchema)` cold-start validation
+- [planned] `./tracing` — span emit + `traceparent` propagation via `@vllnt/logger`
+- [planned] `./testing` — fixture factories + `withIdentity`
+- [planned] `./relationships`, `./validators`, `./pagination`, `./rls`, `./triggers`, `./http`
+- [planned] `./react` — optional tree-shakeable front-end hooks layer
+
+## Installation
+
+```bash
+pnpm add @vllnt/convex-helpers
+```
+
+`convex` is a peer dependency:
+
+```bash
+pnpm add convex
+```
+
+## Usage
+
+```ts
+import { asyncMap, pruneNull, nullThrows } from "@vllnt/convex-helpers";
+
+// Parallel fetch with null filtering
+const docs = pruneNull(await asyncMap(ids, (id) => ctx.db.get(id)));
+
+// Non-null assertion
+const doc = nullThrows(await ctx.db.get(id), `Document ${id} not found`);
+```
+
+## API Reference
+
+See [docs/API.md](./docs/API.md) for full API reference with signatures and examples.
+
+## Testing
+
+```bash
+pnpm test
+pnpm test:coverage   # must reach 100%
+```
+
+Tests use [vitest](https://vitest.dev) with the node environment. 100% coverage is enforced via
+`vitest.config.mts` thresholds.
+
+## Contributing
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for development setup, code style, and PR guidelines.
+
+## Author
+
+Built by [bntvllnt](https://github.com/bntvllnt) · [bntvllnt.com](https://bntvllnt.com) · [X
+@bntvllnt](https://x.com/bntvllnt)
+
+Part of the [@vllnt](https://github.com/vllnt) Convex component fleet —
+[vllnt.com](https://vllnt.com)
+
+If this is useful, [sponsor the work](https://github.com/sponsors/bntvllnt).
+
+## License
+
+[MIT](./LICENSE)

package/dist/index.d.ts

@@ -0,0 +1,41 @@
+/**
+ * @module @vllnt/convex-helpers
+ * Pure host-side helpers for Convex backends.
+ */
+/**
+ * Applies an async function to every element of an array, returning results in order.
+ *
+ * @param list - Input array
+ * @param fn - Async mapper function
+ * @returns Promise resolving to mapped array in original order
+ * @example
+ * const docs = await asyncMap(ids, (id) => ctx.db.get(id));
+ */
+export declare function asyncMap<T, TResult>(list: T[], fn: (item: T, index: number) => Promise<TResult>): Promise<TResult[]>;
+/**
+ * Filters null and undefined values from an array.
+ *
+ * @param list - Input array potentially containing null/undefined
+ * @returns Array with all null and undefined values removed
+ * @example
+ * const docs = pruneNull(await asyncMap(ids, (id) => ctx.db.get(id)));
+ */
+export declare function pruneNull<T>(list: (null | T | undefined)[]): T[];
+/**
+ * Error thrown when a required document is null or undefined.
+ */
+export declare class NullDocumentError extends Error {
+    constructor(message?: string);
+}
+/**
+ * Asserts a value is non-null and non-undefined, throwing NullDocumentError when absent.
+ *
+ * @param value - Value to check
+ * @param message - Optional custom error message
+ * @returns The value, narrowed to exclude null and undefined
+ * @throws {NullDocumentError} When value is null or undefined
+ * @example
+ * const doc = nullThrows(await ctx.db.get(id), `Document ${id} not found`);
+ */
+export declare function nullThrows<T>(value: null | T | undefined, message?: string): T;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;GAQG;AACH,wBAAsB,QAAQ,CAAC,CAAC,EAAE,OAAO,EACvC,IAAI,EAAE,CAAC,EAAE,EACT,EAAE,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,GAC/C,OAAO,CAAC,OAAO,EAAE,CAAC,CAEpB;AAED;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,IAAI,GAAG,CAAC,GAAG,SAAS,CAAC,EAAE,GAAG,CAAC,EAAE,CAEhE;AAED;;GAEG;AACH,qBAAa,iBAAkB,SAAQ,KAAK;gBAC9B,OAAO,SAAiC;CAIrD;AAED;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAC1B,KAAK,EAAE,IAAI,GAAG,CAAC,GAAG,SAAS,EAC3B,OAAO,CAAC,EAAE,MAAM,GACf,CAAC,CAKH"}

package/dist/index.js

@@ -0,0 +1,53 @@
+/**
+ * @module @vllnt/convex-helpers
+ * Pure host-side helpers for Convex backends.
+ */
+/**
+ * Applies an async function to every element of an array, returning results in order.
+ *
+ * @param list - Input array
+ * @param fn - Async mapper function
+ * @returns Promise resolving to mapped array in original order
+ * @example
+ * const docs = await asyncMap(ids, (id) => ctx.db.get(id));
+ */
+export async function asyncMap(list, fn) {
+    return Promise.all(list.map(fn));
+}
+/**
+ * Filters null and undefined values from an array.
+ *
+ * @param list - Input array potentially containing null/undefined
+ * @returns Array with all null and undefined values removed
+ * @example
+ * const docs = pruneNull(await asyncMap(ids, (id) => ctx.db.get(id)));
+ */
+export function pruneNull(list) {
+    return list.filter((item) => item !== null && item !== undefined);
+}
+/**
+ * Error thrown when a required document is null or undefined.
+ */
+export class NullDocumentError extends Error {
+    constructor(message = "Expected a non-null document") {
+        super(message);
+        this.name = "NullDocumentError";
+    }
+}
+/**
+ * Asserts a value is non-null and non-undefined, throwing NullDocumentError when absent.
+ *
+ * @param value - Value to check
+ * @param message - Optional custom error message
+ * @returns The value, narrowed to exclude null and undefined
+ * @throws {NullDocumentError} When value is null or undefined
+ * @example
+ * const doc = nullThrows(await ctx.db.get(id), `Document ${id} not found`);
+ */
+export function nullThrows(value, message) {
+    if (value === null || value === undefined) {
+        throw new NullDocumentError(message);
+    }
+    return value;
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAC5B,IAAS,EACT,EAAgD;IAEhD,OAAO,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC;AACnC,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,SAAS,CAAI,IAA8B;IACzD,OAAO,IAAI,CAAC,MAAM,CAAC,CAAC,IAAI,EAAa,EAAE,CAAC,IAAI,KAAK,IAAI,IAAI,IAAI,KAAK,SAAS,CAAC,CAAC;AAC/E,CAAC;AAED;;GAEG;AACH,MAAM,OAAO,iBAAkB,SAAQ,KAAK;IAC1C,YAAY,OAAO,GAAG,8BAA8B;QAClD,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;IAClC,CAAC;CACF;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,UAAU,CACxB,KAA2B,EAC3B,OAAgB;IAEhB,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QAC1C,MAAM,IAAI,iBAAiB,CAAC,OAAO,CAAC,CAAC;IACvC,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/package.json

@@ -0,0 +1,75 @@
+{
+  "name": "@vllnt/convex-helpers",
+  "version": "0.1.0-canary.df58580",
+  "description": "Typed host-side helpers for Convex backends — builders, errors, validators, relationships, pagination, HTTP, env, and observability.",
+  "license": "MIT",
+  "type": "module",
+  "packageManager": "pnpm@9.15.4",
+  "files": [
+    "dist",
+    "src"
+  ],
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "types": "./dist/index.d.ts",
+  "module": "./dist/index.js",
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc --project ./tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "typecheck:ci": "tsc --noEmit --project tsconfig.ci.json",
+    "lint": "eslint .",
+    "test": "vitest run --passWithNoTests",
+    "test:watch": "vitest --typecheck --clearScreen false",
+    "test:coverage": "vitest run --coverage --coverage.reporter=text",
+    "generate:llms": "node scripts/generate-llms.mjs",
+    "preversion": "pnpm install --frozen-lockfile && pnpm build && pnpm test && pnpm typecheck && pnpm generate:llms"
+  },
+  "peerDependencies": {
+    "convex": "^1.36.1"
+  },
+  "devDependencies": {
+    "@vllnt/eslint-config": "^1.0.0",
+    "@vllnt/typescript": "^1.0.0",
+    "convex": "^1.36.1",
+    "eslint": "^9.0.0",
+    "prettier": "^3.4.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0",
+    "@vitest/coverage-v8": "^3.0.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "homepage": "https://github.com/vllnt/convex-helpers#readme",
+  "bugs": {
+    "url": "https://github.com/vllnt/convex-helpers/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/vllnt/convex-helpers"
+  },
+  "author": {
+    "name": "bntvllnt",
+    "url": "https://bntvllnt.com"
+  },
+  "funding": {
+    "type": "github",
+    "url": "https://github.com/sponsors/bntvllnt"
+  },
+  "keywords": [
+    "convex",
+    "convex-helpers",
+    "typescript",
+    "backend",
+    "utils"
+  ]
+}

package/src/index.test.ts

@@ -0,0 +1,164 @@
+import { describe, expect, it } from "vitest";
+
+import { asyncMap, NullDocumentError, nullThrows, pruneNull } from "./index.js";
+
+describe("asyncMap", () => {
+  it("returns empty array for empty input", async () => {
+    const result = await asyncMap([], (x: number) => Promise.resolve(x * 2));
+    expect(result).toEqual([]);
+  });
+
+  it("maps a single element", async () => {
+    const result = await asyncMap([1], (x) => Promise.resolve(x * 2));
+    expect(result).toEqual([2]);
+  });
+
+  it("maps multiple elements in order", async () => {
+    const result = await asyncMap([1, 2, 3], (x) => Promise.resolve(x * 2));
+    expect(result).toEqual([2, 4, 6]);
+  });
+
+  it("passes index to mapper", async () => {
+    const result = await asyncMap(
+      ["a", "b", "c"],
+      async (item, index) => `${String(index)}:${item}`,
+    );
+    expect(result).toEqual(["0:a", "1:b", "2:c"]);
+  });
+
+  it("resolves all promises and returns results in order", async () => {
+    const result = await asyncMap([10, 20, 30], (x) => Promise.resolve(x * 3));
+    expect(result).toEqual([30, 60, 90]);
+  });
+});
+
+describe("pruneNull", () => {
+  it("returns empty array for empty input", () => {
+    expect(pruneNull([])).toEqual([]);
+  });
+
+  it("removes all nulls", () => {
+    const nullValue: null = null;
+    expect(pruneNull([nullValue, nullValue])).toEqual([]);
+  });
+
+  it("removes all undefineds", () => {
+    expect(pruneNull([undefined, undefined])).toEqual([]);
+  });
+
+  it("removes mixed null and undefined", () => {
+    const nullValue: null = null;
+    expect(pruneNull([nullValue, undefined, nullValue])).toEqual([]);
+  });
+
+  it("keeps all non-null values", () => {
+    expect(pruneNull([1, 2, 3])).toEqual([1, 2, 3]);
+  });
+
+  it("filters mixed array of values and nulls", () => {
+    const nullValue: null = null;
+    expect(pruneNull([1, nullValue, 2, undefined, 3])).toEqual([1, 2, 3]);
+  });
+
+  it("works with strings", () => {
+    const nullValue: null = null;
+    expect(pruneNull(["a", nullValue, "b"])).toEqual(["a", "b"]);
+  });
+
+  it("works with objects", () => {
+    const object = { id: 1 };
+    const nullValue: null = null;
+    expect(pruneNull([object, nullValue])).toEqual([object]);
+  });
+
+  it("preserves falsy non-null values (0, false, empty string)", () => {
+    const nullValue: null = null;
+    expect(pruneNull([0, false, "", nullValue, undefined])).toEqual([
+      0,
+      false,
+      "",
+    ]);
+  });
+});
+
+describe("NullDocumentError", () => {
+  it("is an instance of Error", () => {
+    const error = new NullDocumentError();
+    expect(error).toBeInstanceOf(Error);
+  });
+
+  it("has name NullDocumentError", () => {
+    const error = new NullDocumentError();
+    expect(error.name).toBe("NullDocumentError");
+  });
+
+  it("uses default message when none provided", () => {
+    const error = new NullDocumentError();
+    expect(error.message).toBe("Expected a non-null document");
+  });
+
+  it("uses custom message when provided", () => {
+    const error = new NullDocumentError("custom message");
+    expect(error.message).toBe("custom message");
+  });
+});
+
+describe("nullThrows", () => {
+  it("returns the value when non-null", () => {
+    expect(nullThrows(42)).toBe(42);
+  });
+
+  it("returns the value when truthy string", () => {
+    expect(nullThrows("hello")).toBe("hello");
+  });
+
+  it("returns 0 (falsy but non-null)", () => {
+    expect(nullThrows(0)).toBe(0);
+  });
+
+  it("returns false (falsy but non-null)", () => {
+    expect(nullThrows(false)).toBe(false);
+  });
+
+  it("returns empty string (falsy but non-null)", () => {
+    expect(nullThrows("")).toBe("");
+  });
+
+  it("returns objects", () => {
+    const object = { id: 1 };
+    expect(nullThrows(object)).toBe(object);
+  });
+
+  it("throws NullDocumentError when value is null", () => {
+    const nullValue: null = null;
+    expect(() => {
+      nullThrows(nullValue);
+    }).toThrow(NullDocumentError);
+  });
+
+  it("throws NullDocumentError when value is undefined", () => {
+    expect(() => {
+      nullThrows(undefined);
+    }).toThrow(NullDocumentError);
+  });
+
+  it("throws with default message when no message supplied", () => {
+    const nullValue: null = null;
+    expect(() => {
+      nullThrows(nullValue);
+    }).toThrow("Expected a non-null document");
+  });
+
+  it("throws with custom message when supplied", () => {
+    const nullValue: null = null;
+    expect(() => {
+      nullThrows(nullValue, "doc 123 not found");
+    }).toThrow("doc 123 not found");
+  });
+
+  it("throws with custom message for undefined", () => {
+    expect(() => {
+      nullThrows(undefined, "missing doc");
+    }).toThrow("missing doc");
+  });
+});

package/src/index.ts

@@ -0,0 +1,62 @@
+/**
+ * @module @vllnt/convex-helpers
+ * Pure host-side helpers for Convex backends.
+ */
+
+/**
+ * Applies an async function to every element of an array, returning results in order.
+ *
+ * @param list - Input array
+ * @param fn - Async mapper function
+ * @returns Promise resolving to mapped array in original order
+ * @example
+ * const docs = await asyncMap(ids, (id) => ctx.db.get(id));
+ */
+export async function asyncMap<T, TResult>(
+  list: T[],
+  fn: (item: T, index: number) => Promise<TResult>,
+): Promise<TResult[]> {
+  return Promise.all(list.map(fn));
+}
+
+/**
+ * Filters null and undefined values from an array.
+ *
+ * @param list - Input array potentially containing null/undefined
+ * @returns Array with all null and undefined values removed
+ * @example
+ * const docs = pruneNull(await asyncMap(ids, (id) => ctx.db.get(id)));
+ */
+export function pruneNull<T>(list: (null | T | undefined)[]): T[] {
+  return list.filter((item): item is T => item !== null && item !== undefined);
+}
+
+/**
+ * Error thrown when a required document is null or undefined.
+ */
+export class NullDocumentError extends Error {
+  constructor(message = "Expected a non-null document") {
+    super(message);
+    this.name = "NullDocumentError";
+  }
+}
+
+/**
+ * Asserts a value is non-null and non-undefined, throwing NullDocumentError when absent.
+ *
+ * @param value - Value to check
+ * @param message - Optional custom error message
+ * @returns The value, narrowed to exclude null and undefined
+ * @throws {NullDocumentError} When value is null or undefined
+ * @example
+ * const doc = nullThrows(await ctx.db.get(id), `Document ${id} not found`);
+ */
+export function nullThrows<T>(
+  value: null | T | undefined,
+  message?: string,
+): T {
+  if (value === null || value === undefined) {
+    throw new NullDocumentError(message);
+  }
+  return value;
+}