@docxkit/errors 0.0.0-stage → 0.7.0-rc.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-PRESENT ntnyq <https://github.com/ntnyq>
+
+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

@@ -1,3 +1,13 @@
-# Temporary Holding Version
+# @docxkit/errors
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Shared error class and error codes for docx-kit packages. This package has no runtime dependencies, so generation and browser preview use the same `DocxKitError` class without depending on each other.
+
+```ts
+import { DocxKitError, ERROR_CODES } from '@docxkit/errors'
+import type { ErrorCode } from '@docxkit/errors'
+
+const code: ErrorCode = ERROR_CODES.EXPORT_FAILED
+throw new DocxKitError(code, 'Document export failed')
+```
+
+`@docxkit/core` and `docx-kit` re-export these APIs. Document, style, and plugin types remain in the declaration-only `@docxkit/types` package.

package/dist/index.d.ts

@@ -0,0 +1,86 @@
+/**
+ * `@docxkit/errors` — Shared error codes and error class for docx-kit.
+ *
+ * @module errors
+ */
+/**
+ * Well-known error codes used throughout the library.
+ *
+ * Consumers can match against these codes for structured error handling.
+ */
+export declare const ERROR_CODES: {
+  /**
+   * Document export failed.
+   */
+  readonly EXPORT_FAILED: "EXPORT_FAILED";
+  /**
+   * Image data is empty, corrupt, or unsupported.
+   */
+  readonly IMAGE_INVALID_DATA: "IMAGE_INVALID_DATA";
+  /**
+   * Plugin manifest JSON is missing required fields or has invalid structure.
+   */
+  readonly MANIFEST_INVALID: "MANIFEST_INVALID";
+  /**
+   * Plugin manifest file was not found at the expected path.
+   */
+  readonly MANIFEST_MISSING: "MANIFEST_MISSING";
+  /**
+   * A required plugin dependency was not found or version is incompatible.
+   */
+  readonly PLUGIN_DEPENDENCY_MISSING: "PLUGIN_DEPENDENCY_MISSING";
+  /**
+   * Plugin failed to load (import error, network error, etc.).
+   */
+  readonly PLUGIN_LOAD_FAILED: "PLUGIN_LOAD_FAILED";
+  /**
+   * A plugin node referenced an unregistered plugin.
+   */
+  readonly PLUGIN_NOT_REGISTERED: "PLUGIN_NOT_REGISTERED";
+  /**
+   * A plugin's `render()` method threw an error.
+   */
+  readonly PLUGIN_RENDER_FAILED: "PLUGIN_RENDER_FAILED";
+  /**
+   * Plugin's `docxKit` semver range is incompatible with the running version.
+   */
+  readonly PLUGIN_VERSION_MISMATCH: "PLUGIN_VERSION_MISMATCH";
+  /**
+   * A `className` referenced a stylesheet key that doesn't exist.
+   */
+  readonly STYLE_UNKNOWN_CLASS: "STYLE_UNKNOWN_CLASS";
+  /**
+   * Table has no columns, invalid spans, or overlapping cell positions.
+   */
+  readonly TABLE_INVALID_COLUMNS: "TABLE_INVALID_COLUMNS";
+  /**
+   * Encountered a node type that has no registered compiler.
+   */
+  readonly UNKNOWN_NODE_TYPE: "UNKNOWN_NODE_TYPE";
+};
+/**
+ * Union type of all known error codes.
+ */
+export type ErrorCode = (typeof ERROR_CODES)[keyof typeof ERROR_CODES];
+/**
+ * Structured error class for docx-kit.
+ *
+ * Carries a machine-readable `code`, a human-readable `message`,
+ * and optionally the underlying `cause`.
+ */
+export declare class DocxKitError extends Error {
+  /**
+   * The underlying error that caused this failure (if any).
+   */
+  readonly cause: unknown;
+  /**
+   * Machine-readable error code.
+   */
+  readonly code: string | ErrorCode;
+  /**
+   * @param code - — Known error code from {@link ERROR_CODES}
+   * @param message - — Human-readable description
+   * @param cause - — Optional underlying error
+   */
+  constructor(code: string | ErrorCode, message: string, cause?: unknown);
+}

package/dist/index.js

@@ -0,0 +1,89 @@
+// src/index.ts
+/**
+* `@docxkit/errors` — Shared error codes and error class for docx-kit.
+*
+* @module errors
+*/
+/**
+* Well-known error codes used throughout the library.
+*
+* Consumers can match against these codes for structured error handling.
+*/
+const ERROR_CODES = {
+	/**
+	* Document export failed.
+	*/
+	EXPORT_FAILED: "EXPORT_FAILED",
+	/**
+	* Image data is empty, corrupt, or unsupported.
+	*/
+	IMAGE_INVALID_DATA: "IMAGE_INVALID_DATA",
+	/**
+	* Plugin manifest JSON is missing required fields or has invalid structure.
+	*/
+	MANIFEST_INVALID: "MANIFEST_INVALID",
+	/**
+	* Plugin manifest file was not found at the expected path.
+	*/
+	MANIFEST_MISSING: "MANIFEST_MISSING",
+	/**
+	* A required plugin dependency was not found or version is incompatible.
+	*/
+	PLUGIN_DEPENDENCY_MISSING: "PLUGIN_DEPENDENCY_MISSING",
+	/**
+	* Plugin failed to load (import error, network error, etc.).
+	*/
+	PLUGIN_LOAD_FAILED: "PLUGIN_LOAD_FAILED",
+	/**
+	* A plugin node referenced an unregistered plugin.
+	*/
+	PLUGIN_NOT_REGISTERED: "PLUGIN_NOT_REGISTERED",
+	/**
+	* A plugin's `render()` method threw an error.
+	*/
+	PLUGIN_RENDER_FAILED: "PLUGIN_RENDER_FAILED",
+	/**
+	* Plugin's `docxKit` semver range is incompatible with the running version.
+	*/
+	PLUGIN_VERSION_MISMATCH: "PLUGIN_VERSION_MISMATCH",
+	/**
+	* A `className` referenced a stylesheet key that doesn't exist.
+	*/
+	STYLE_UNKNOWN_CLASS: "STYLE_UNKNOWN_CLASS",
+	/**
+	* Table has no columns, invalid spans, or overlapping cell positions.
+	*/
+	TABLE_INVALID_COLUMNS: "TABLE_INVALID_COLUMNS",
+	/**
+	* Encountered a node type that has no registered compiler.
+	*/
+	UNKNOWN_NODE_TYPE: "UNKNOWN_NODE_TYPE"
+};
+/**
+* Structured error class for docx-kit.
+*
+* Carries a machine-readable `code`, a human-readable `message`,
+* and optionally the underlying `cause`.
+*/
+var DocxKitError = class extends Error {
+	/**
+	* The underlying error that caused this failure (if any).
+	*/
+	cause;
+	/**
+	* Machine-readable error code.
+	*/
+	code;
+	/**
+	* @param code - — Known error code from {@link ERROR_CODES}
+	* @param message - — Human-readable description
+	* @param cause - — Optional underlying error
+	*/
+	constructor(code, message, cause) {
+		super(message);
+		this.name = "DocxKitError";
+		this.code = code;
+		this.cause = cause;
+	}
+};
+export { DocxKitError, ERROR_CODES };

package/package.json

@@ -1,6 +1,35 @@
 {
   "name": "@docxkit/errors",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "type": "module",
+  "version": "0.7.0-rc.0",
+  "description": "Shared error class and error codes for docx-kit packages",
+  "license": "MIT",
+  "author": {
+    "name": "ntnyq",
+    "email": "ntnyq13@gmail.com"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ntnyq/docx-kit.git",
+    "directory": "packages/errors"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch"
+  }
+}