@prisma-next/plan 0.0.1

package/README.md

@@ -0,0 +1,91 @@
+# @prisma-next/plan
+
+Plan helpers, diagnostics, and shared errors for Prisma Next.
+
+## Overview
+
+This package is part of the **core ring** and provides target-agnostic plan error helpers and error types. These utilities are used across all target families (SQL, document, etc.) for consistent error handling during plan construction and validation.
+
+## Purpose
+
+Provide shared plan error utilities that can be used by any target family without depending on target-specific types or implementations.
+
+## Responsibilities
+
+- **Plan Error Helpers**: Functions for creating standardized plan errors (`planInvalid`, `planUnsupported`)
+- **Error Types**: TypeScript types for plan errors (`RuntimeError`)
+
+**Non-goals:**
+- Target-specific error handling (handled by target packages)
+- Runtime error handling (handled by runtime package)
+- Contract validation errors (handled by contract/emitter packages)
+
+## Architecture
+
+```mermaid
+flowchart TD
+    subgraph "Core Ring"
+        PLAN["@prisma-next/plan"]
+    end
+
+    subgraph "Consumers"
+        SQL[SQL Lanes]
+        DOC[Document Lanes]
+        RUNTIME[Runtime]
+    end
+
+    PLAN --> SQL
+    PLAN --> DOC
+    PLAN --> RUNTIME
+```
+
+## Components
+
+### Error Helpers (`errors.ts`)
+
+- **`planInvalid(message, details?, hints?, docs?)`**: Creates a `RuntimeError` with code `PLAN.INVALID` for invalid plan operations
+- **`planUnsupported(message, details?, hints?, docs?)`**: Creates a `RuntimeError` with code `PLAN.UNSUPPORTED` for unsupported plan operations
+
+### Error Types (`types.ts`)
+
+- **`RuntimeError`**: Interface for plan errors with standardized fields:
+  - `code`: Error code (e.g., `PLAN.INVALID`, `PLAN.UNSUPPORTED`)
+  - `category`: Always `'PLAN'` for plan errors
+  - `severity`: Always `'error'`
+  - `message`: Human-readable error message
+  - `details`: Optional structured details
+  - `hints`: Optional array of hints
+  - `docs`: Optional array of documentation links
+
+## Dependencies
+
+This package has **no dependencies** - it's part of the innermost core ring and provides foundational error utilities.
+
+## Package Structure
+
+This package follows the standard `exports/` directory pattern:
+
+- `src/exports/errors.ts` - Re-exports error helpers (`planInvalid`, `planUnsupported`)
+- `src/exports/types.ts` - Re-exports error types (`RuntimeError`)
+- `src/index.ts` - Main entry point that re-exports from `exports/`
+
+This enables subpath imports like `@prisma-next/plan/errors` and `@prisma-next/plan/types` if needed in the future.
+
+## Package Location
+
+This package is part of the **framework domain**, **core layer**, **shared plane**:
+- **Domain**: framework (target-agnostic)
+- **Layer**: core
+- **Plane**: shared
+- **Path**: `packages/framework/core-plan`
+
+## Related Subsystems
+
+- **[Query Lanes](../../../../docs/architecture%20docs/subsystems/3.%20Query%20Lanes.md)**: Uses plan errors during query construction
+- **[Runtime & Plugin Framework](../../../../docs/architecture%20docs/subsystems/4.%20Runtime%20&%20Plugin%20Framework.md)**: Uses plan errors for validation
+
+## Related ADRs
+
+- [ADR 140 - Package Layering & Target-Family Namespacing](../../../../docs/architecture%20docs/adrs/ADR%20140%20-%20Package%20Layering%20&%20Target-Family%20Namespacing.md)
+- [ADR 068 - Error mapping to RuntimeError](../../../../docs/architecture%20docs/adrs/ADR%20068%20-%20Error%20mapping%20to%20RuntimeError.md)
+- [ADR 027 - Error Envelope Stable Codes](../../../../docs/architecture%20docs/adrs/ADR%20027%20-%20Error%20Envelope%20Stable%20Codes.md)

package/dist/chunk-G4WYE6TI.js

@@ -0,0 +1 @@
+//# sourceMappingURL=chunk-G4WYE6TI.js.map

package/dist/chunk-G4WYE6TI.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/chunk-JG6QOQIV.js

@@ -0,0 +1,37 @@
+// src/errors.ts
+function planInvalid(message, details, hints, docs) {
+  const error = new Error(message);
+  Object.defineProperty(error, "name", {
+    value: "RuntimeError",
+    configurable: true
+  });
+  return Object.assign(error, {
+    code: "PLAN.INVALID",
+    category: "PLAN",
+    severity: "error",
+    details,
+    hints,
+    docs
+  });
+}
+function planUnsupported(message, details, hints, docs) {
+  const error = new Error(message);
+  Object.defineProperty(error, "name", {
+    value: "RuntimeError",
+    configurable: true
+  });
+  return Object.assign(error, {
+    code: "PLAN.UNSUPPORTED",
+    category: "PLAN",
+    severity: "error",
+    details,
+    hints,
+    docs
+  });
+}
+
+export {
+  planInvalid,
+  planUnsupported
+};
+//# sourceMappingURL=chunk-JG6QOQIV.js.map

package/dist/chunk-JG6QOQIV.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/errors.ts"],"sourcesContent":["import type { RuntimeError } from './types';\n\nexport function planInvalid(\n  message: string,\n  details?: Record<string, unknown>,\n  hints?: readonly string[],\n  docs?: readonly string[],\n): RuntimeError {\n  const error = new Error(message) as RuntimeError;\n\n  Object.defineProperty(error, 'name', {\n    value: 'RuntimeError',\n    configurable: true,\n  });\n\n  return Object.assign(error, {\n    code: 'PLAN.INVALID',\n    category: 'PLAN' as const,\n    severity: 'error' as const,\n    details,\n    hints,\n    docs,\n  });\n}\n\nexport function planUnsupported(\n  message: string,\n  details?: Record<string, unknown>,\n  hints?: readonly string[],\n  docs?: readonly string[],\n): RuntimeError {\n  const error = new Error(message) as RuntimeError;\n\n  Object.defineProperty(error, 'name', {\n    value: 'RuntimeError',\n    configurable: true,\n  });\n\n  return Object.assign(error, {\n    code: 'PLAN.UNSUPPORTED',\n    category: 'PLAN' as const,\n    severity: 'error' as const,\n    details,\n    hints,\n    docs,\n  });\n}\n"],"mappings":";AAEO,SAAS,YACd,SACA,SACA,OACA,MACc;AACd,QAAM,QAAQ,IAAI,MAAM,OAAO;AAE/B,SAAO,eAAe,OAAO,QAAQ;AAAA,IACnC,OAAO;AAAA,IACP,cAAc;AAAA,EAChB,CAAC;AAED,SAAO,OAAO,OAAO,OAAO;AAAA,IAC1B,MAAM;AAAA,IACN,UAAU;AAAA,IACV,UAAU;AAAA,IACV;AAAA,IACA;AAAA,IACA;AAAA,EACF,CAAC;AACH;AAEO,SAAS,gBACd,SACA,SACA,OACA,MACc;AACd,QAAM,QAAQ,IAAI,MAAM,OAAO;AAE/B,SAAO,eAAe,OAAO,QAAQ;AAAA,IACnC,OAAO;AAAA,IACP,cAAc;AAAA,EAChB,CAAC;AAED,SAAO,OAAO,OAAO,OAAO;AAAA,IAC1B,MAAM;AAAA,IACN,UAAU;AAAA,IACV,UAAU;AAAA,IACV;AAAA,IACA;AAAA,IACA;AAAA,EACF,CAAC;AACH;","names":[]}

package/dist/exports/errors.d.ts

@@ -0,0 +1,6 @@
+import { RuntimeError } from './types.js';
+
+declare function planInvalid(message: string, details?: Record<string, unknown>, hints?: readonly string[], docs?: readonly string[]): RuntimeError;
+declare function planUnsupported(message: string, details?: Record<string, unknown>, hints?: readonly string[], docs?: readonly string[]): RuntimeError;
+
+export { planInvalid, planUnsupported };

package/dist/exports/errors.js

@@ -0,0 +1,9 @@
+import {
+  planInvalid,
+  planUnsupported
+} from "../chunk-JG6QOQIV.js";
+export {
+  planInvalid,
+  planUnsupported
+};
+//# sourceMappingURL=errors.js.map

package/dist/exports/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/exports/types.d.ts

@@ -0,0 +1,11 @@
+interface RuntimeError extends Error {
+    readonly code: string;
+    readonly category: 'PLAN';
+    readonly severity: 'error';
+    readonly message: string;
+    readonly details?: Record<string, unknown>;
+    readonly hints?: readonly string[];
+    readonly docs?: readonly string[];
+}
+
+export type { RuntimeError };

package/dist/exports/types.js

@@ -0,0 +1,2 @@
+import "../chunk-G4WYE6TI.js";
+//# sourceMappingURL=types.js.map

package/dist/exports/types.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { planInvalid, planUnsupported } from './exports/errors.js';
+export { RuntimeError } from './exports/types.js';

package/dist/index.js

@@ -0,0 +1,10 @@
+import {
+  planInvalid,
+  planUnsupported
+} from "./chunk-JG6QOQIV.js";
+import "./chunk-G4WYE6TI.js";
+export {
+  planInvalid,
+  planUnsupported
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@prisma-next/plan",
+  "version": "0.0.1",
+  "type": "module",
+  "sideEffects": false,
+  "description": "Plan helpers, diagnostics, and shared errors for Prisma Next",
+  "devDependencies": {
+    "tsup": "^8.3.0",
+    "typescript": "^5.9.3",
+    "vitest": "^2.1.1"
+  },
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./errors": {
+      "types": "./dist/exports/errors.d.ts",
+      "import": "./dist/exports/errors.js"
+    },
+    "./types": {
+      "types": "./dist/exports/types.d.ts",
+      "import": "./dist/exports/types.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"
+  }
+}