docx-kit 0.0.0 → 0.2.0

package/dist/errors-c9CC63Ti.js

@@ -0,0 +1,63 @@
+//#region src/errors.ts
+/**
+* Error handling types and classes 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",
+	/** 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",
+	/** A `className` referenced a stylesheet key that doesn't exist. */
+	STYLE_UNKNOWN_CLASS: "STYLE_UNKNOWN_CLASS",
+	/** Table was created with no columns. */
+	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`.
+*
+* @example
+* ```ts
+* try {
+*   await doc.save('output.docx')
+* } catch (err) {
+*   if (err instanceof DocxKitError && err.code === ERROR_CODES.EXPORT_FAILED) {
+*     console.error('Export failed:', err.message)
+*   }
+* }
+* ```
+*/
+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;
+	}
+};
+//#endregion
+export { ERROR_CODES as n, DocxKitError as t };

package/dist/errors-c9CC63Ti.mjs

@@ -0,0 +1,63 @@
+//#region src/errors.ts
+/**
+* Error handling types and classes 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",
+	/** 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",
+	/** A `className` referenced a stylesheet key that doesn't exist. */
+	STYLE_UNKNOWN_CLASS: "STYLE_UNKNOWN_CLASS",
+	/** Table was created with no columns. */
+	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`.
+*
+* @example
+* ```ts
+* try {
+*   await doc.save('output.docx')
+* } catch (err) {
+*   if (err instanceof DocxKitError && err.code === ERROR_CODES.EXPORT_FAILED) {
+*     console.error('Export failed:', err.message)
+*   }
+* }
+* ```
+*/
+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;
+	}
+};
+//#endregion
+export { ERROR_CODES as n, DocxKitError as t };

package/dist/fs-BuKdtuxB.js

@@ -0,0 +1,30 @@
+import { Packer } from "docx";
+//#region src/node/fs.ts
+/**
+* Node.js filesystem utilities for saving documents to disk.
+*
+* @module node/fs
+*/
+/**
+* Save a compiled document to a file on disk.
+*
+* Uses `Packer.toBuffer()` to produce the .docx binary, then
+* writes via `node:fs/promises`. This function is **Node.js only**.
+*
+* @param doc - — A compiled `docx` `Document` instance
+* @param filename - — Output file path (e.g. `"report.docx"`)
+*
+* @example
+* ```ts
+* import { saveDocument } from 'docx-kit/node'
+*
+* const doc = await compileDocument({ ... })
+* await saveDocument(doc, 'report.docx')
+* ```
+*/
+async function saveDocument(doc, filename) {
+	const { writeFile } = await import("node:fs/promises");
+	await writeFile(filename, await Packer.toBuffer(doc));
+}
+//#endregion
+export { saveDocument };

package/dist/fs-DF8ug9Wi.mjs

@@ -0,0 +1,43 @@
+import { Packer } from "docx";
+//#region \0rolldown/runtime.js
+var __defProp = Object.defineProperty;
+var __exportAll = (all, no_symbols) => {
+	let target = {};
+	for (var name in all) __defProp(target, name, {
+		get: all[name],
+		enumerable: true
+	});
+	if (!no_symbols) __defProp(target, Symbol.toStringTag, { value: "Module" });
+	return target;
+};
+//#endregion
+//#region src/node/fs.ts
+/**
+* Node.js filesystem utilities for saving documents to disk.
+*
+* @module node/fs
+*/
+var fs_exports = /* @__PURE__ */ __exportAll({ saveDocument: () => saveDocument });
+/**
+* Save a compiled document to a file on disk.
+*
+* Uses `Packer.toBuffer()` to produce the .docx binary, then
+* writes via `node:fs/promises`. This function is **Node.js only**.
+*
+* @param doc - — A compiled `docx` `Document` instance
+* @param filename - — Output file path (e.g. `"report.docx"`)
+*
+* @example
+* ```ts
+* import { saveDocument } from 'docx-kit/node'
+*
+* const doc = await compileDocument({ ... })
+* await saveDocument(doc, 'report.docx')
+* ```
+*/
+async function saveDocument(doc, filename) {
+	const { writeFile } = await import("node:fs/promises");
+	await writeFile(filename, await Packer.toBuffer(doc));
+}
+//#endregion
+export { saveDocument as n, fs_exports as t };

package/dist/image-CdfLh9GO.js

@@ -0,0 +1,76 @@
+import { ImageRun } from "docx";
+//#region src/utils/dataUrl.ts
+/**
+* Cross-platform base64 data-URL decoder.
+*
+* Auto-detects the runtime environment and uses the appropriate
+* implementation:
+* - **Node.js**: `Buffer.from(base64, 'base64')`
+* - **Browser**: `atob(base64)` + manual byte population
+*
+* This is the internal shared version used by the compiler and
+* built-in plugins. For platform-specific direct access, import
+* from `'docx-kit/node'` or `'docx-kit/browser'`.
+*
+* @module utils/dataUrl
+*/
+/**
+* Decode a base64 data-URL to raw bytes (works in both browser & Node.js).
+*
+* Strips the `"data:*;base64,"` prefix and decodes using the appropriate
+* runtime API.
+*
+* @param dataUrl - — A base64 data-URI string (e.g. `"data:image/png;base64,iVBO..."`)
+* @returns Raw bytes as `Uint8Array`
+*
+* @example
+* ```ts
+* import { dataUrlToUint8Array } from 'docx-kit'
+*
+* const bytes = await dataUrlToUint8Array('data:image/png;base64,iVBORw...')
+* ```
+*/
+async function dataUrlToUint8Array(dataUrl) {
+	const base64 = dataUrl.split(",")[1];
+	if (typeof atob === "function") {
+		const binary = atob(base64);
+		const bytes = new Uint8Array(binary.length);
+		for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+		return bytes;
+	}
+	const { Buffer } = await import("node:buffer");
+	return new Uint8Array(Buffer.from(base64, "base64"));
+}
+//#endregion
+//#region src/utils/image.ts
+/**
+* Shared image utilities for internal use by compilers and plugins.
+*
+* Bridges the `docx` library's `IImageOptions` with `docx-kit`'s
+* own `CreateImageRunOptions`, confining type casts to this single module.
+*
+* @module utils/image
+*/
+/**
+* Create an `ImageRun` with type-safe defaults.
+*
+* All paths that construct an `ImageRun` should use this factory
+* instead of calling `new ImageRun(...)` directly, ensuring that
+* type casts are confined to a single audited function.
+*
+* @param options - — Image data and layout options
+* @returns A configured `ImageRun` instance
+*/
+function createImageRun(options) {
+	return new ImageRun({
+		data: options.data,
+		floating: options.floating,
+		type: options.type,
+		transformation: {
+			height: options.height ?? 180,
+			width: options.width ?? 300
+		}
+	});
+}
+//#endregion
+export { dataUrlToUint8Array as n, createImageRun as t };

package/dist/image-CdfLh9GO.mjs

@@ -0,0 +1,76 @@
+import { ImageRun } from "docx";
+//#region src/utils/dataUrl.ts
+/**
+* Cross-platform base64 data-URL decoder.
+*
+* Auto-detects the runtime environment and uses the appropriate
+* implementation:
+* - **Node.js**: `Buffer.from(base64, 'base64')`
+* - **Browser**: `atob(base64)` + manual byte population
+*
+* This is the internal shared version used by the compiler and
+* built-in plugins. For platform-specific direct access, import
+* from `'docx-kit/node'` or `'docx-kit/browser'`.
+*
+* @module utils/dataUrl
+*/
+/**
+* Decode a base64 data-URL to raw bytes (works in both browser & Node.js).
+*
+* Strips the `"data:*;base64,"` prefix and decodes using the appropriate
+* runtime API.
+*
+* @param dataUrl - — A base64 data-URI string (e.g. `"data:image/png;base64,iVBO..."`)
+* @returns Raw bytes as `Uint8Array`
+*
+* @example
+* ```ts
+* import { dataUrlToUint8Array } from 'docx-kit'
+*
+* const bytes = await dataUrlToUint8Array('data:image/png;base64,iVBORw...')
+* ```
+*/
+async function dataUrlToUint8Array(dataUrl) {
+	const base64 = dataUrl.split(",")[1];
+	if (typeof atob === "function") {
+		const binary = atob(base64);
+		const bytes = new Uint8Array(binary.length);
+		for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+		return bytes;
+	}
+	const { Buffer } = await import("node:buffer");
+	return new Uint8Array(Buffer.from(base64, "base64"));
+}
+//#endregion
+//#region src/utils/image.ts
+/**
+* Shared image utilities for internal use by compilers and plugins.
+*
+* Bridges the `docx` library's `IImageOptions` with `docx-kit`'s
+* own `CreateImageRunOptions`, confining type casts to this single module.
+*
+* @module utils/image
+*/
+/**
+* Create an `ImageRun` with type-safe defaults.
+*
+* All paths that construct an `ImageRun` should use this factory
+* instead of calling `new ImageRun(...)` directly, ensuring that
+* type casts are confined to a single audited function.
+*
+* @param options - — Image data and layout options
+* @returns A configured `ImageRun` instance
+*/
+function createImageRun(options) {
+	return new ImageRun({
+		data: options.data,
+		floating: options.floating,
+		type: options.type,
+		transformation: {
+			height: options.height ?? 180,
+			width: options.width ?? 300
+		}
+	});
+}
+//#endregion
+export { dataUrlToUint8Array as n, createImageRun as t };