@stll/docx-utils 0.1.5 → 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stll/docx-utils",
-  "version": "0.1.5",
+  "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",
@@ -50,7 +50,7 @@
     "test": "bun test src",
     "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 ../../packages/scripts/src/tsc-native.ts --noEmit",
+    "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 .",
@@ -65,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",