@stll/docx-utils 0.0.1-placeholder.0 → 0.1.0

package/README.md

@@ -0,0 +1,33 @@
+# @stll/docx-utils
+
+Low-level helpers for reading and writing DOCX/OOXML zip packages.
+
+The package wraps the mechanical parts of working with a DOCX file: loading and
+repacking the underlying zip, extracting text or binary parts, managing
+relationships and content types, and the OOXML namespace constants those
+operations need.
+
+```ts
+import { loadDocx, extractText, ensureRelationship } from "@stll/docx-utils";
+
+const zip = await loadDocx(bytes);
+const text = await extractText(zip, "word/document.xml");
+```
+
+## Install
+
+```sh
+bun add @stll/docx-utils
+```
+
+## Exports
+
+- `OOXML_NS` / `OoxmlPrefix` — OOXML namespace constants and prefixes.
+- `loadDocx`, `repackZip`, `extractText`, `extractBinary`, `DOCX_COMPRESSION` —
+  zip-level read and write helpers.
+- `findNextRId`, `ensureContentType`, `ensureRelationship` — relationship and
+  content-type management.
+
+## License
+
+Apache-2.0

package/dist/index.d.ts

@@ -0,0 +1,57 @@
+import JSZip from "jszip";
+
+//#region src/namespaces.d.ts
+/**
+ * Common OOXML namespace URIs.
+ *
+ * Canonical source for namespace constants shared across
+ * the editor (folio) and the backend (api).
+ */
+declare const OOXML_NS: {
+  readonly w: "http://schemas.openxmlformats.org/wordprocessingml/2006/main";
+  readonly a: "http://schemas.openxmlformats.org/drawingml/2006/main";
+  readonly r: "http://schemas.openxmlformats.org/officeDocument/2006/relationships";
+  readonly wp: "http://schemas.openxmlformats.org/drawingml/2006/wordprocessingDrawing";
+  readonly wp14: "http://schemas.microsoft.com/office/word/2010/wordprocessingDrawing";
+  readonly wps: "http://schemas.microsoft.com/office/word/2010/wordprocessingShape";
+  readonly wpc: "http://schemas.microsoft.com/office/word/2010/wordprocessingCanvas";
+  readonly wpg: "http://schemas.microsoft.com/office/word/2010/wordprocessingGroup";
+  readonly pic: "http://schemas.openxmlformats.org/drawingml/2006/picture";
+  readonly m: "http://schemas.openxmlformats.org/officeDocument/2006/math";
+  readonly mc: "http://schemas.openxmlformats.org/markup-compatibility/2006";
+  readonly v: "urn:schemas-microsoft-com:vml";
+  readonly o: "urn:schemas-microsoft-com:office:office";
+  readonly w14: "http://schemas.microsoft.com/office/word/2010/wordml";
+  readonly w15: "http://schemas.microsoft.com/office/word/2012/wordml";
+  readonly ct: "http://schemas.openxmlformats.org/package/2006/content-types";
+  readonly pr: "http://schemas.openxmlformats.org/package/2006/relationships";
+};
+type OoxmlPrefix = keyof typeof OOXML_NS;
+//#endregion
+//#region src/zip.d.ts
+/** Standard DOCX compression options */
+declare const DOCX_COMPRESSION: {
+  type: "arraybuffer";
+  compression: "DEFLATE";
+  compressionOptions: {
+    level: number;
+  };
+};
+/** Load a DOCX file (ArrayBuffer) into a JSZip instance */
+declare const loadDocx: (buffer: ArrayBuffer) => Promise<JSZip>;
+/** Extract a text file from a ZIP */
+declare const extractText: (zip: JSZip, path: string) => Promise<string | null>;
+/** Extract a binary file from a ZIP */
+declare const extractBinary: (zip: JSZip, path: string) => Promise<ArrayBuffer | null>;
+/** Repack a ZIP to ArrayBuffer with standard DOCX compression */
+declare const repackZip: (zip: JSZip) => Promise<ArrayBuffer>;
+//#endregion
+//#region src/relationships.d.ts
+/** Find the next available rId in a relationships XML string */
+declare const findNextRId: (relsXml: string) => string;
+/** Ensure a content type entry exists in [Content_Types].xml */
+declare const ensureContentType: (contentTypesXml: string, partName: string, contentType: string) => string;
+/** Ensure a relationship entry exists */
+declare const ensureRelationship: (relsXml: string, rId: string, type: string, target: string) => string;
+//#endregion
+export { DOCX_COMPRESSION, OOXML_NS, type OoxmlPrefix, ensureContentType, ensureRelationship, extractBinary, extractText, findNextRId, loadDocx, repackZip };

package/dist/index.js

@@ -0,0 +1,77 @@
+import JSZip from "jszip";
+//#region src/namespaces.ts
+/**
+* Common OOXML namespace URIs.
+*
+* Canonical source for namespace constants shared across
+* the editor (folio) and the backend (api).
+*/
+const OOXML_NS = {
+	w: "http://schemas.openxmlformats.org/wordprocessingml/2006/main",
+	a: "http://schemas.openxmlformats.org/drawingml/2006/main",
+	r: "http://schemas.openxmlformats.org/officeDocument/2006/relationships",
+	wp: "http://schemas.openxmlformats.org/drawingml/2006/wordprocessingDrawing",
+	wp14: "http://schemas.microsoft.com/office/word/2010/wordprocessingDrawing",
+	wps: "http://schemas.microsoft.com/office/word/2010/wordprocessingShape",
+	wpc: "http://schemas.microsoft.com/office/word/2010/wordprocessingCanvas",
+	wpg: "http://schemas.microsoft.com/office/word/2010/wordprocessingGroup",
+	pic: "http://schemas.openxmlformats.org/drawingml/2006/picture",
+	m: "http://schemas.openxmlformats.org/officeDocument/2006/math",
+	mc: "http://schemas.openxmlformats.org/markup-compatibility/2006",
+	v: "urn:schemas-microsoft-com:vml",
+	o: "urn:schemas-microsoft-com:office:office",
+	w14: "http://schemas.microsoft.com/office/word/2010/wordml",
+	w15: "http://schemas.microsoft.com/office/word/2012/wordml",
+	ct: "http://schemas.openxmlformats.org/package/2006/content-types",
+	pr: "http://schemas.openxmlformats.org/package/2006/relationships"
+};
+//#endregion
+//#region src/zip.ts
+/** Standard DOCX compression options */
+const DOCX_COMPRESSION = {
+	type: "arraybuffer",
+	compression: "DEFLATE",
+	compressionOptions: { level: 6 }
+};
+/** Load a DOCX file (ArrayBuffer) into a JSZip instance */
+const loadDocx = async (buffer) => await JSZip.loadAsync(buffer);
+/** Extract a text file from a ZIP */
+const extractText = async (zip, path) => {
+	const file = zip.file(path);
+	if (!file) return null;
+	return await file.async("string");
+};
+/** Extract a binary file from a ZIP */
+const extractBinary = async (zip, path) => {
+	const file = zip.file(path);
+	if (!file) return null;
+	return await file.async("arraybuffer");
+};
+/** Repack a ZIP to ArrayBuffer with standard DOCX compression */
+const repackZip = async (zip) => await zip.generateAsync(DOCX_COMPRESSION);
+//#endregion
+//#region src/relationships.ts
+/** Find the next available rId in a relationships XML string */
+const findNextRId = (relsXml) => {
+	const matches = relsXml.matchAll(/Id="rId(?<num>\d+)"/gu);
+	let max = 0;
+	for (const m of matches) {
+		const n = Number.parseInt(m.groups?.["num"] ?? "0", 10);
+		if (n > max) max = n;
+	}
+	return `rId${max + 1}`;
+};
+/** Ensure a content type entry exists in [Content_Types].xml */
+const ensureContentType = (contentTypesXml, partName, contentType) => {
+	if (contentTypesXml.includes(`PartName="${partName}"`)) return contentTypesXml;
+	const override = `<Override PartName="${partName}" ContentType="${contentType}"/>`;
+	return contentTypesXml.replace("</Types>", `${override}\n</Types>`);
+};
+/** Ensure a relationship entry exists */
+const ensureRelationship = (relsXml, rId, type, target) => {
+	if (relsXml.includes(`Id="${rId}"`)) return relsXml;
+	const rel = `<Relationship Id="${rId}" Type="${type}" Target="${target}"/>`;
+	return relsXml.replace("</Relationships>", `${rel}\n</Relationships>`);
+};
+//#endregion
+export { DOCX_COMPRESSION, OOXML_NS, ensureContentType, ensureRelationship, extractBinary, extractText, findNextRId, loadDocx, repackZip };

package/package.json

@@ -1,5 +1,59 @@
 {
   "name": "@stll/docx-utils",
-  "version": "0.0.1-placeholder.0",
-  "description": "Placeholder to bootstrap npm trusted publishing. The real package ships via the next @stll release."
-}
+  "version": "0.1.0",
+  "description": "Low-level helpers for reading and writing DOCX/OOXML zip packages: text and binary extraction, relationship and content-type management, and namespace constants.",
+  "keywords": [
+    "docx",
+    "ooxml",
+    "openxml",
+    "relationships",
+    "word",
+    "zip"
+  ],
+  "homepage": "https://github.com/stella/stella/tree/main/packages/docx-utils",
+  "bugs": {
+    "url": "https://github.com/stella/stella/issues"
+  },
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/stella/stella.git",
+    "directory": "packages/docx-utils"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "clean": "git clean -xdf dist .cache .turbo node_modules",
+    "build": "tsdown",
+    "pack:dry-run": "bun pm pack --dry-run",
+    "test": "bun test src",
+    "typecheck": "tsgo --noEmit",
+    "lint": "cd ../.. && bun --bun oxlint -c oxlint.config.ts --report-unused-disable-directives-severity=error --deny-warnings --type-aware packages/docx-utils",
+    "lint:fix": "cd ../.. && bun --bun oxlint -c oxlint.config.ts --type-aware --fix packages/docx-utils",
+    "format": "oxfmt .",
+    "prepack": "bun run build"
+  },
+  "dependencies": {
+    "jszip": "3.10.1"
+  },
+  "devDependencies": {
+    "@stll/typescript-config": "0.0.0",
+    "@types/bun": "1.3.14",
+    "tsdown": "0.22.3"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts"
+}