@prisma-next/utils 0.0.1

package/README.md

@@ -0,0 +1,88 @@
+# @prisma-next/utils
+
+Shared utility functions for Prisma Next.
+
+## Overview
+
+This package provides general-purpose utility functions used across the Prisma Next codebase. These utilities are target-agnostic and have no dependencies on other Prisma Next packages.
+
+## Utilities
+
+### `ifDefined(key, value)`
+
+Returns an object with the key/value if value is defined, otherwise an empty object. Use with spread to conditionally include optional properties while satisfying `exactOptionalPropertyTypes`.
+
+```typescript
+import { ifDefined } from '@prisma-next/utils/defined';
+
+// Instead of:
+const obj = {
+  required: 'value',
+  ...(optional ? { optional } : {}),
+};
+
+// Use:
+const obj = {
+  required: 'value',
+  ...ifDefined('optional', optional),
+};
+```
+
+**Why use this?**
+
+1. **Explicit**: You name exactly which properties are optional
+2. **Intentional**: Won't accidentally strip other properties
+3. **Type-safe**: Returns `{}` or `{ key: V }` (without undefined)
+4. **exactOptionalPropertyTypes compatible**: Properly handles TypeScript's strict optional property checking
+
+### `Result<T, F>`, `ok()`, `notOk()`, `okVoid()`
+
+Generic Result type for representing success or failure outcomes. This is the standard way to return "expected failures" as values rather than throwing exceptions.
+
+```typescript
+import { type Result, ok, notOk, okVoid } from '@prisma-next/utils/result';
+
+// Success result with value
+function divide(a: number, b: number): Result<number, string> {
+  if (b === 0) {
+    return notOk('Division by zero');
+  }
+  return ok(a / b);
+}
+
+// Using the result
+const result = divide(10, 2);
+if (result.ok) {
+  console.log(result.value); // 5
+} else {
+  console.error(result.failure); // error message
+}
+
+// Void success for validation
+function validate(value: unknown): Result<void, string> {
+  if (!value) {
+    return notOk('Value is required');
+  }
+  return okVoid();
+}
+```
+
+**Types:**
+- `Ok<T>` - Success with value: `{ ok: true, value: T }`
+- `NotOk<F>` - Failure with details: `{ ok: false, failure: F }`
+- `Result<T, F>` - Discriminated union of `Ok<T> | NotOk<F>`
+
+See `docs/Error Handling.md` for the full error taxonomy.
+
+## Package Location
+
+This package is part of the **framework domain**, **core layer**, **shared plane**:
+- **Domain**: framework (target-agnostic)
+- **Layer**: core
+- **Plane**: shared
+- **Path**: `packages/1-framework/1-core/shared/utils`
+
+## Dependencies
+
+This package has **no dependencies** - it's part of the innermost core ring and provides foundational utilities.
+

package/dist/exports/defined.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Returns an object with the key/value if value is defined, otherwise an empty object.
+ *
+ * Use with spread to conditionally include optional properties while satisfying
+ * exactOptionalPropertyTypes. This is explicit about which properties are optional
+ * and won't inadvertently strip other undefined values.
+ *
+ * @example
+ * ```typescript
+ * // Instead of:
+ * const obj = {
+ *   required: 'value',
+ *   ...(optional ? { optional } : {}),
+ * };
+ *
+ * // Use:
+ * const obj = {
+ *   required: 'value',
+ *   ...ifDefined('optional', optional),
+ * };
+ * ```
+ */
+declare function ifDefined<K extends string, V>(key: K, value: V | undefined): Record<never, never> | {
+    [P in K]: V;
+};
+
+export { ifDefined };

package/dist/exports/defined.js

@@ -0,0 +1,8 @@
+// src/defined.ts
+function ifDefined(key, value) {
+  return value !== void 0 ? { [key]: value } : {};
+}
+export {
+  ifDefined
+};
+//# sourceMappingURL=defined.js.map

package/dist/exports/defined.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/defined.ts"],"sourcesContent":["/**\n * Returns an object with the key/value if value is defined, otherwise an empty object.\n *\n * Use with spread to conditionally include optional properties while satisfying\n * exactOptionalPropertyTypes. This is explicit about which properties are optional\n * and won't inadvertently strip other undefined values.\n *\n * @example\n * ```typescript\n * // Instead of:\n * const obj = {\n *   required: 'value',\n *   ...(optional ? { optional } : {}),\n * };\n *\n * // Use:\n * const obj = {\n *   required: 'value',\n *   ...ifDefined('optional', optional),\n * };\n * ```\n */\nexport function ifDefined<K extends string, V>(\n  key: K,\n  value: V | undefined,\n): Record<never, never> | { [P in K]: V } {\n  return value !== undefined ? ({ [key]: value } as { [P in K]: V }) : {};\n}\n"],"mappings":";AAsBO,SAAS,UACd,KACA,OACwC;AACxC,SAAO,UAAU,SAAa,EAAE,CAAC,GAAG,GAAG,MAAM,IAAwB,CAAC;AACxE;","names":[]}

package/dist/exports/result.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Generic Result type for representing success or failure outcomes.
+ *
+ * This is the standard way to return "expected failures" as values rather than
+ * throwing exceptions. See docs/Error Handling.md for the full taxonomy.
+ *
+ * Naming rationale:
+ * - `Ok<T>` / `NotOk<F>` mirror the `ok: true/false` discriminator
+ * - `NotOk` avoids collision with domain types like "Failure" or "Error"
+ * - `failure` property distinguishes from JS Error semantics
+ */
+/**
+ * Represents a successful result containing a value.
+ */
+interface Ok<T> {
+    readonly ok: true;
+    readonly value: T;
+}
+/**
+ * Represents an unsuccessful result containing failure details.
+ */
+interface NotOk<F> {
+    readonly ok: false;
+    readonly failure: F;
+}
+/**
+ * A discriminated union representing either success (Ok) or failure (NotOk).
+ *
+ * @typeParam T - The success value type
+ * @typeParam F - The failure details type
+ */
+type Result<T, F> = Ok<T> | NotOk<F>;
+/**
+ * Creates a successful result.
+ */
+declare function ok<T>(value: T): Ok<T>;
+/**
+ * Creates an unsuccessful result.
+ */
+declare function notOk<F>(failure: F): NotOk<F>;
+/**
+ * Returns a successful void result.
+ * Use this for validation checks that don't produce a value.
+ */
+declare function okVoid(): Ok<void>;
+
+export { type NotOk, type Ok, type Result, notOk, ok, okVoid };

package/dist/exports/result.js

@@ -0,0 +1,17 @@
+// src/result.ts
+function ok(value) {
+  return Object.freeze({ ok: true, value });
+}
+function notOk(failure) {
+  return Object.freeze({ ok: false, failure });
+}
+var OK_VOID = Object.freeze({ ok: true, value: void 0 });
+function okVoid() {
+  return OK_VOID;
+}
+export {
+  notOk,
+  ok,
+  okVoid
+};
+//# sourceMappingURL=result.js.map

package/dist/exports/result.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/result.ts"],"sourcesContent":["/**\n * Generic Result type for representing success or failure outcomes.\n *\n * This is the standard way to return \"expected failures\" as values rather than\n * throwing exceptions. See docs/Error Handling.md for the full taxonomy.\n *\n * Naming rationale:\n * - `Ok<T>` / `NotOk<F>` mirror the `ok: true/false` discriminator\n * - `NotOk` avoids collision with domain types like \"Failure\" or \"Error\"\n * - `failure` property distinguishes from JS Error semantics\n */\n\n/**\n * Represents a successful result containing a value.\n */\nexport interface Ok<T> {\n  readonly ok: true;\n  readonly value: T;\n}\n\n/**\n * Represents an unsuccessful result containing failure details.\n */\nexport interface NotOk<F> {\n  readonly ok: false;\n  readonly failure: F;\n}\n\n/**\n * A discriminated union representing either success (Ok) or failure (NotOk).\n *\n * @typeParam T - The success value type\n * @typeParam F - The failure details type\n */\nexport type Result<T, F> = Ok<T> | NotOk<F>;\n\n/**\n * Creates a successful result.\n */\nexport function ok<T>(value: T): Ok<T> {\n  return Object.freeze({ ok: true, value });\n}\n\n/**\n * Creates an unsuccessful result.\n */\nexport function notOk<F>(failure: F): NotOk<F> {\n  return Object.freeze({ ok: false, failure });\n}\n\n/**\n * Singleton for void success results.\n * Use this for validation checks that don't produce a value.\n */\nconst OK_VOID: Ok<void> = Object.freeze({ ok: true, value: undefined });\n\n/**\n * Returns a successful void result.\n * Use this for validation checks that don't produce a value.\n */\nexport function okVoid(): Ok<void> {\n  return OK_VOID;\n}\n"],"mappings":";AAuCO,SAAS,GAAM,OAAiB;AACrC,SAAO,OAAO,OAAO,EAAE,IAAI,MAAM,MAAM,CAAC;AAC1C;AAKO,SAAS,MAAS,SAAsB;AAC7C,SAAO,OAAO,OAAO,EAAE,IAAI,OAAO,QAAQ,CAAC;AAC7C;AAMA,IAAM,UAAoB,OAAO,OAAO,EAAE,IAAI,MAAM,OAAO,OAAU,CAAC;AAM/D,SAAS,SAAmB;AACjC,SAAO;AACT;","names":[]}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@prisma-next/utils",
+  "version": "0.0.1",
+  "type": "module",
+  "sideEffects": false,
+  "description": "Shared utility functions for Prisma Next",
+  "devDependencies": {
+    "@vitest/coverage-v8": "^2.1.1",
+    "tsup": "^8.3.0",
+    "typescript": "^5.9.3",
+    "vite-tsconfig-paths": "^5.1.4",
+    "vitest": "^2.1.1"
+  },
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    "./defined": {
+      "types": "./dist/exports/defined.d.ts",
+      "import": "./dist/exports/defined.js"
+    },
+    "./result": {
+      "types": "./dist/exports/result.d.ts",
+      "import": "./dist/exports/result.js"
+    }
+  },
+  "scripts": {
+    "build": "tsup --config tsup.config.ts",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "typecheck": "tsc --project tsconfig.json --noEmit",
+    "lint": "biome check . --config-path ../../../../../biome.json --error-on-warnings",
+    "clean": "node ../../../../../scripts/clean.mjs"
+  }
+}