@stll/docx-utils 0.1.4 → 0.2.0

package/dist/index.d.ts

@@ -51,9 +51,9 @@ type ArchiveOptions = {
 };
 type DocxArchive = {
   /**
-   * The underlying JSZip instance. Safe for write operations
-   * (`zip.file(path, value)`, `zip.generateAsync(...)`); for reads,
-   * prefer the bounded helpers on this object.
+   * The underlying JSZip instance. Write entries with `writeZipEntry`
+   * and repack with `zip.generateAsync(...)`; for reads, prefer the
+   * bounded helpers on this object.
    */
   zip: JSZip;
   /**
@@ -85,6 +85,18 @@ export declare const extractBinary: (zip: JSZip, path: string) => Promise<ArrayB
 /** Repack a ZIP to ArrayBuffer with standard DOCX compression */
 export declare const repackZip: (zip: JSZip) => Promise<ArrayBuffer>;
 //#endregion
+//#region src/zip-entry.d.ts
+/** Text or bytes to store as one archive entry. */
+type ZipEntryContent = string | Uint8Array | ArrayBuffer;
+/**
+ * Write `content` to `path` in `zip`. Text is UTF-8 encoded here, in one
+ * pass over the whole string, before JSZip sees it: JSZip encodes string
+ * input in 16 KiB pieces, which splits a surrogate pair that straddles a
+ * piece boundary into two U+FFFD characters. Returns `zip`, like
+ * `JSZip#file`, so writes can be chained.
+ */
+export declare const writeZipEntry: (zip: JSZip, path: string, content: ZipEntryContent, options?: JSZip.JSZipFileOptions) => JSZip;
+//#endregion
 //#region src/relationships.d.ts
 /** Find the next available rId in a relationships XML string */
 export declare const findNextRId: (relsXml: string) => string;
@@ -132,4 +144,4 @@ export declare const sanitizeAttachedTemplateRelationships: (xml: string, relati
 /** Remove WordprocessingML references to the relationships removed above. */
 export declare const sanitizeAttachedTemplateSource: (xml: string, removedRelationshipIds: readonly string[]) => SanitizedAttachedTemplateSource;
 //#endregion
-export type { ArchiveOptions, AttachedTemplateRelationshipFinding, AttachedTemplateTargetKind, DocxArchive, OoxmlPrefix };
+export type { ArchiveOptions, AttachedTemplateRelationshipFinding, AttachedTemplateTargetKind, DocxArchive, OoxmlPrefix, ZipEntryContent };

package/dist/index.js

@@ -395,6 +395,20 @@ const extractBinary = async (zip, path) => {
 /** Repack a ZIP to ArrayBuffer with standard DOCX compression */
 const repackZip = async (zip) => await zip.generateAsync(DOCX_COMPRESSION);
 //#endregion
+//#region src/zip-entry.ts
+const utf8 = new TextEncoder();
+/**
+* Write `content` to `path` in `zip`. Text is UTF-8 encoded here, in one
+* pass over the whole string, before JSZip sees it: JSZip encodes string
+* input in 16 KiB pieces, which splits a surrogate pair that straddles a
+* piece boundary into two U+FFFD characters. Returns `zip`, like
+* `JSZip#file`, so writes can be chained.
+*/
+const writeZipEntry = (zip, path, content, options) => {
+	const data = typeof content === "string" ? utf8.encode(content) : content;
+	return zip.file(path, data, options);
+};
+//#endregion
 //#region src/relationships.ts
 /**
 * Escape a string for safe use inside a double-quoted XML attribute value.
@@ -559,4 +573,4 @@ const sanitizeAttachedTemplateSource = (xml, removedRelationshipIds) => {
 	};
 };
 //#endregion
-export { ATTACHED_TEMPLATE_SECURITY_RULE, ATTACHED_TEMPLATE_TARGET_KIND, DOCX_COMPRESSION, DOCX_MAX_ENTRIES, DOCX_MAX_ENTRY_BYTES, DOCX_MAX_TOTAL_BYTES, DocxArchiveError, OOXML_NS, classifyAttachedTemplateTarget, ensureContentType, ensureRelationship, extractBinary, extractText, findNextRId, isOpcRelationshipPartPath, loadDocx, loadDocxArchive, relationshipSourcePartPath, repackZip, sanitizeAttachedTemplateRelationships, sanitizeAttachedTemplateSource };
+export { ATTACHED_TEMPLATE_SECURITY_RULE, ATTACHED_TEMPLATE_TARGET_KIND, DOCX_COMPRESSION, DOCX_MAX_ENTRIES, DOCX_MAX_ENTRY_BYTES, DOCX_MAX_TOTAL_BYTES, DocxArchiveError, OOXML_NS, classifyAttachedTemplateTarget, ensureContentType, ensureRelationship, extractBinary, extractText, findNextRId, isOpcRelationshipPartPath, loadDocx, loadDocxArchive, relationshipSourcePartPath, repackZip, sanitizeAttachedTemplateRelationships, sanitizeAttachedTemplateSource, writeZipEntry };

package/dist/office-formats.d.ts

@@ -0,0 +1,89 @@
+//#region src/office-formats.d.ts
+/** ZIP-based office formats; legacy binary formats are not XML containers. */
+export declare const OFFICE_ARCHIVE_FORMATS: {
+  readonly docx: {
+    readonly family: "word";
+    readonly mimeType: "application/vnd.openxmlformats-officedocument.wordprocessingml.document";
+  };
+  readonly docm: {
+    readonly family: "word";
+    readonly mimeType: "application/vnd.ms-word.document.macroEnabled.12";
+  };
+  readonly dotx: {
+    readonly family: "word";
+    readonly mimeType: "application/vnd.openxmlformats-officedocument.wordprocessingml.template";
+  };
+  readonly dotm: {
+    readonly family: "word";
+    readonly mimeType: "application/vnd.ms-word.template.macroEnabled.12";
+  };
+  readonly xlsx: {
+    readonly family: "sheet";
+    readonly mimeType: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet";
+  };
+  readonly xlsm: {
+    readonly family: "sheet";
+    readonly mimeType: "application/vnd.ms-excel.sheet.macroEnabled.12";
+  };
+  readonly xlsb: {
+    readonly family: "sheet";
+    readonly mimeType: "application/vnd.ms-excel.sheet.binary.macroEnabled.12";
+  };
+  readonly xltx: {
+    readonly family: "sheet";
+    readonly mimeType: "application/vnd.openxmlformats-officedocument.spreadsheetml.template";
+  };
+  readonly xltm: {
+    readonly family: "sheet";
+    readonly mimeType: "application/vnd.ms-excel.template.macroEnabled.12";
+  };
+  readonly pptx: {
+    readonly family: "presentation";
+    readonly mimeType: "application/vnd.openxmlformats-officedocument.presentationml.presentation";
+  };
+  readonly pptm: {
+    readonly family: "presentation";
+    readonly mimeType: "application/vnd.ms-powerpoint.presentation.macroEnabled.12";
+  };
+  readonly ppsx: {
+    readonly family: "presentation";
+    readonly mimeType: "application/vnd.openxmlformats-officedocument.presentationml.slideshow";
+  };
+  readonly ppsm: {
+    readonly family: "presentation";
+    readonly mimeType: "application/vnd.ms-powerpoint.slideshow.macroEnabled.12";
+  };
+  readonly potx: {
+    readonly family: "presentation";
+    readonly mimeType: "application/vnd.openxmlformats-officedocument.presentationml.template";
+  };
+  readonly potm: {
+    readonly family: "presentation";
+    readonly mimeType: "application/vnd.ms-powerpoint.template.macroEnabled.12";
+  };
+  readonly odt: {
+    readonly family: "odf";
+    readonly mimeType: "application/vnd.oasis.opendocument.text";
+  };
+  readonly ods: {
+    readonly family: "odf";
+    readonly mimeType: "application/vnd.oasis.opendocument.spreadsheet";
+  };
+  readonly odp: {
+    readonly family: "odf";
+    readonly mimeType: "application/vnd.oasis.opendocument.presentation";
+  };
+  readonly ott: {
+    readonly family: "odf";
+    readonly mimeType: "application/vnd.oasis.opendocument.text-template";
+  };
+  readonly ots: {
+    readonly family: "odf";
+    readonly mimeType: "application/vnd.oasis.opendocument.spreadsheet-template";
+  };
+  readonly otp: {
+    readonly family: "odf";
+    readonly mimeType: "application/vnd.oasis.opendocument.presentation-template";
+  };
+};
+//#endregion

package/dist/office-formats.js

@@ -0,0 +1,90 @@
+//#region src/office-formats.ts
+/** ZIP-based office formats; legacy binary formats are not XML containers. */
+const OFFICE_ARCHIVE_FORMATS = {
+	docx: {
+		family: "word",
+		mimeType: "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
+	},
+	docm: {
+		family: "word",
+		mimeType: "application/vnd.ms-word.document.macroEnabled.12"
+	},
+	dotx: {
+		family: "word",
+		mimeType: "application/vnd.openxmlformats-officedocument.wordprocessingml.template"
+	},
+	dotm: {
+		family: "word",
+		mimeType: "application/vnd.ms-word.template.macroEnabled.12"
+	},
+	xlsx: {
+		family: "sheet",
+		mimeType: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
+	},
+	xlsm: {
+		family: "sheet",
+		mimeType: "application/vnd.ms-excel.sheet.macroEnabled.12"
+	},
+	xlsb: {
+		family: "sheet",
+		mimeType: "application/vnd.ms-excel.sheet.binary.macroEnabled.12"
+	},
+	xltx: {
+		family: "sheet",
+		mimeType: "application/vnd.openxmlformats-officedocument.spreadsheetml.template"
+	},
+	xltm: {
+		family: "sheet",
+		mimeType: "application/vnd.ms-excel.template.macroEnabled.12"
+	},
+	pptx: {
+		family: "presentation",
+		mimeType: "application/vnd.openxmlformats-officedocument.presentationml.presentation"
+	},
+	pptm: {
+		family: "presentation",
+		mimeType: "application/vnd.ms-powerpoint.presentation.macroEnabled.12"
+	},
+	ppsx: {
+		family: "presentation",
+		mimeType: "application/vnd.openxmlformats-officedocument.presentationml.slideshow"
+	},
+	ppsm: {
+		family: "presentation",
+		mimeType: "application/vnd.ms-powerpoint.slideshow.macroEnabled.12"
+	},
+	potx: {
+		family: "presentation",
+		mimeType: "application/vnd.openxmlformats-officedocument.presentationml.template"
+	},
+	potm: {
+		family: "presentation",
+		mimeType: "application/vnd.ms-powerpoint.template.macroEnabled.12"
+	},
+	odt: {
+		family: "odf",
+		mimeType: "application/vnd.oasis.opendocument.text"
+	},
+	ods: {
+		family: "odf",
+		mimeType: "application/vnd.oasis.opendocument.spreadsheet"
+	},
+	odp: {
+		family: "odf",
+		mimeType: "application/vnd.oasis.opendocument.presentation"
+	},
+	ott: {
+		family: "odf",
+		mimeType: "application/vnd.oasis.opendocument.text-template"
+	},
+	ots: {
+		family: "odf",
+		mimeType: "application/vnd.oasis.opendocument.spreadsheet-template"
+	},
+	otp: {
+		family: "odf",
+		mimeType: "application/vnd.oasis.opendocument.presentation-template"
+	}
+};
+//#endregion
+export { OFFICE_ARCHIVE_FORMATS };

package/dist/office-metadata.d.ts

@@ -0,0 +1,38 @@
+import { Attr, Document, Element } from "slimdom";
+//#region src/office-metadata.d.ts
+export declare const officeIdentityAttributePolicy: (name: string) => {
+  readonly type: "replace";
+  readonly replacement: "Author";
+} | {
+  readonly type: "replace";
+  readonly replacement: "A";
+} | {
+  readonly type: "remove";
+} | {
+  readonly type: "remove";
+} | {
+  readonly type: "replace";
+  readonly replacement: "Author";
+} | {
+  readonly type: "remove";
+} | {
+  readonly type: "remove";
+} | {
+  readonly type: "replace";
+  readonly replacement: "Author";
+} | undefined;
+export declare const isOfficeCollaborationPart: (part: string) => boolean;
+/** All XML parts in which office producers store properties or collaboration identities. */
+export declare const isOfficeIdentityPart: (part: string) => boolean;
+export type OfficeIdentityField = {
+  type: "text";
+  node: Element;
+  field: string;
+} | {
+  type: "attribute";
+  node: Attr;
+  field: string;
+};
+/** Internal reference IDs and document/comment body text are deliberately excluded. */
+export declare const officeIdentityFields: (document: Document, part: string) => OfficeIdentityField[];
+//#endregion

package/dist/office-metadata.js

@@ -0,0 +1,88 @@
+//#region src/office-metadata.ts
+const PROPERTY_FIELDS = /* @__PURE__ */ new Set([
+	"creator",
+	"lastmodifiedby",
+	"company",
+	"manager",
+	"template",
+	"title",
+	"subject",
+	"keywords",
+	"keyword",
+	"description",
+	"initial-creator",
+	"printed-by",
+	"user-defined",
+	"category",
+	"contentstatus"
+]);
+const PROPERTY_ATTRIBUTES = /* @__PURE__ */ new Set([
+	"href",
+	"name",
+	"title"
+]);
+const OFFICE_IDENTITY_ATTRIBUTE_POLICIES = {
+	author: {
+		type: "replace",
+		replacement: "Author"
+	},
+	initials: {
+		type: "replace",
+		replacement: "A"
+	},
+	userid: { type: "remove" },
+	providerid: { type: "remove" },
+	displayname: {
+		type: "replace",
+		replacement: "Author"
+	},
+	email: { type: "remove" },
+	emailaddress: { type: "remove" },
+	name: {
+		type: "replace",
+		replacement: "Author"
+	}
+};
+const IDENTITY_ATTRIBUTES = new Set(Object.keys(OFFICE_IDENTITY_ATTRIBUTE_POLICIES).filter((name) => name !== "name"));
+const officeIdentityAttributePolicy = (name) => Object.entries(OFFICE_IDENTITY_ATTRIBUTE_POLICIES).find(([key]) => key === name.toLowerCase())?.[1];
+const isOfficeCollaborationPart = (part) => /^(?:content\.xml|(?:word|xl|ppt)\/.*\.xml)$/iu.test(part);
+const NAMED_IDENTITIES = /* @__PURE__ */ new Set([
+	"person",
+	"author",
+	"cmauthor",
+	"commentauthor",
+	"mention"
+]);
+const DC_NAMESPACE = "http://purl.org/dc/elements/1.1/";
+/** All XML parts in which office producers store properties or collaboration identities. */
+const isOfficeIdentityPart = (part) => /^(?:docProps\/(?:core|app|custom)\.xml|meta\.xml)$/iu.test(part) || isOfficeCollaborationPart(part);
+/** Internal reference IDs and document/comment body text are deliberately excluded. */
+const officeIdentityFields = (document, part) => {
+	const result = [];
+	const propertyPart = /^(?:docProps\/(?:core|app)\.xml|meta\.xml)$/iu.test(part);
+	const customPart = /^docProps\/custom\.xml$/iu.test(part);
+	for (const element of document.getElementsByTagNameNS("*", "*")) {
+		const name = element.localName.toLowerCase();
+		const propertyField = propertyPart && PROPERTY_FIELDS.has(name);
+		const customField = customPart && name === "property";
+		const authorText = /^xl\/comments[^/]*\.xml$/iu.test(part) && name === "author";
+		const odfCreator = part === "content.xml" && element.namespaceURI === DC_NAMESPACE && name === "creator";
+		if (propertyField || customField || authorText || odfCreator) result.push({
+			type: "text",
+			node: element,
+			field: element.localName
+		});
+		for (const attribute of element.attributes) {
+			const attr = attribute.localName.toLowerCase();
+			if (!(propertyField && PROPERTY_ATTRIBUTES.has(attr) || customField && attr === "name" || !propertyPart && !customPart && (IDENTITY_ATTRIBUTES.has(attr) || attr === "name" && NAMED_IDENTITIES.has(name)))) continue;
+			result.push({
+				type: "attribute",
+				node: attribute,
+				field: `${element.localName}@${attribute.localName}`
+			});
+		}
+	}
+	return result;
+};
+//#endregion
+export { isOfficeCollaborationPart, isOfficeIdentityPart, officeIdentityAttributePolicy, officeIdentityFields };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stll/docx-utils",
-  "version": "0.1.4",
+  "version": "0.2.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",
@@ -30,6 +30,14 @@
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
+    },
+    "./office-formats": {
+      "types": "./dist/office-formats.d.ts",
+      "import": "./dist/office-formats.js"
+    },
+    "./office-metadata": {
+      "types": "./dist/office-metadata.d.ts",
+      "import": "./dist/office-metadata.js"
     }
   },
   "publishConfig": {
@@ -40,12 +48,14 @@
     "build": "tsdown",
     "pack:dry-run": "bun pm pack --dry-run",
     "test": "bun test src",
-    "typecheck": "bun ../../packages/scripts/src/tsc-native.ts --noEmit",
+    "check:office-fixture-metadata": "bun scripts/check-office-fixture-metadata.ts",
+    "test:office-fixture-metadata": "bun test scripts/check-office-fixture-metadata.test.ts",
+    "typecheck": "bun check --no-pretty --all --project=tsconfig.json",
     "lint": "cd ../.. && bun --bun oxlint -c oxlint.config.ts --report-unused-disable-directives-severity=error --type-aware --type-check packages/docx-utils",
     "lint:fix": "cd ../.. && bun --bun oxlint -c oxlint.config.ts --type-aware --fix packages/docx-utils",
     "format": "bun ../../scripts/run-oxfmt.ts .",
     "prepack": "bun run build",
-    "test:property": "bun test --preload @stll/property-testing/preload $(grep -rlF 'fc.assert' src --include='*.test.ts')"
+    "test:property": "bun test --preload @stll/property-testing/preload $(grep -rlE 'fc\\.assert|assertProperty' src --include='*.test.ts')"
   },
   "dependencies": {
     "better-result": "3.0.1",
@@ -55,8 +65,8 @@
   "devDependencies": {
     "@stll/property-testing": "0.0.0",
     "@stll/typescript-config": "0.0.0",
-    "bun-types": "1.4.2",
-    "fast-check": "^4.10.1",
+    "bun-types": "1.4.3",
+    "fast-check": "^4.10.2",
     "tsdown": "0.23.0"
   },
   "main": "./dist/index.js",