ts-visio 1.3.0 → 1.4.0

package/README.md

@@ -24,6 +24,7 @@ Built using specific schema-level abstractions to handle the complex internal st
 - **Lookup API**: Find shapes by ID, predicate, or look up pages by name.
 - **Read-Back API**: Read custom properties, hyperlinks, and layer assignments from existing shapes.
 - **Page Size & Orientation**: Set canvas dimensions with named sizes (`Letter`, `A4`, …) or raw inches; rotate between portrait and landscape.
+- **Document Metadata**: Read and write document properties (title, author, description, keywords, company, dates) via `doc.getMetadata()` / `doc.setMetadata()`.
 
 Feature gaps are being tracked in [FEATURES.md](./FEATURES.md).
 
@@ -490,6 +491,36 @@ Available named sizes in `PageSizes`: `Letter`, `Legal`, `Tabloid`, `A3`, `A4`,
 
 ---
 
+#### 26. Document Metadata
+Set and read document-level properties that appear in Visio's Document Properties dialog.
+
+```typescript
+// Write metadata (only supplied fields are changed)
+doc.setMetadata({
+    title:          'Network Topology',
+    author:         'Alice',
+    description:    'Data-centre interconnect diagram',
+    keywords:       'network datacenter cloud',
+    lastModifiedBy: 'CI pipeline',
+    company:        'ACME Corp',
+    manager:        'Bob',
+    created:        new Date('2025-01-01T00:00:00Z'),
+    modified:       new Date(),
+});
+
+// Read back all metadata fields
+const meta = doc.getMetadata();
+console.log(meta.title);    // 'Network Topology'
+console.log(meta.author);   // 'Alice'
+console.log(meta.company);  // 'ACME Corp'
+console.log(meta.created);  // Date object
+```
+
+Fields map to OPC parts: `title`, `author`, `description`, `keywords`, `lastModifiedBy`,
+`created`, `modified` → `docProps/core.xml`; `company`, `manager` → `docProps/app.xml`.
+
+---
+
 ## Examples
 
 Check out the [examples](./examples) directory for complete scripts.

package/dist/VisioDocument.d.ts

@@ -1,9 +1,11 @@
 import { Page } from './Page';
+import { DocumentMetadata } from './types/VisioTypes';
 export declare class VisioDocument {
     private pkg;
     private pageManager;
     private _pageCache;
     private mediaManager;
+    private metadataManager;
     private constructor();
     static create(): Promise<VisioDocument>;
     static load(pathOrBuffer: string | Buffer | ArrayBuffer | Uint8Array): Promise<VisioDocument>;
@@ -27,5 +29,18 @@ export declare class VisioDocument {
      * and any BackPage references from other pages.
      */
     deletePage(page: Page): Promise<void>;
+    /**
+     * Read document metadata from `docProps/core.xml` and `docProps/app.xml`.
+     * Fields not present in the file are returned as `undefined`.
+     */
+    getMetadata(): DocumentMetadata;
+    /**
+     * Write document metadata. Only the supplied fields are changed;
+     * all other fields keep their existing values.
+     *
+     * @example
+     * doc.setMetadata({ title: 'My Diagram', author: 'Alice', company: 'ACME' });
+     */
+    setMetadata(props: Partial<DocumentMetadata>): void;
     save(filename?: string): Promise<Buffer>;
 }

package/dist/VisioDocument.js

@@ -38,12 +38,14 @@ const VisioPackage_1 = require("./VisioPackage");
 const PageManager_1 = require("./core/PageManager");
 const Page_1 = require("./Page");
 const MediaManager_1 = require("./core/MediaManager");
+const MetadataManager_1 = require("./core/MetadataManager");
 class VisioDocument {
     constructor(pkg) {
         this.pkg = pkg;
         this._pageCache = null;
         this.pageManager = new PageManager_1.PageManager(pkg);
         this.mediaManager = new MediaManager_1.MediaManager(pkg);
+        this.metadataManager = new MetadataManager_1.MetadataManager(pkg);
     }
     static async create() {
         const pkg = await VisioPackage_1.VisioPackage.create();
@@ -131,6 +133,23 @@ class VisioDocument {
         await this.pageManager.deletePage(page.id);
         this._pageCache = null;
     }
+    /**
+     * Read document metadata from `docProps/core.xml` and `docProps/app.xml`.
+     * Fields not present in the file are returned as `undefined`.
+     */
+    getMetadata() {
+        return this.metadataManager.getMetadata();
+    }
+    /**
+     * Write document metadata. Only the supplied fields are changed;
+     * all other fields keep their existing values.
+     *
+     * @example
+     * doc.setMetadata({ title: 'My Diagram', author: 'Alice', company: 'ACME' });
+     */
+    setMetadata(props) {
+        this.metadataManager.setMetadata(props);
+    }
     async save(filename) {
         return this.pkg.save(filename);
     }

package/dist/core/MetadataManager.d.ts

@@ -0,0 +1,22 @@
+import { VisioPackage } from '../VisioPackage';
+import { DocumentMetadata } from '../types/VisioTypes';
+export declare class MetadataManager {
+    private pkg;
+    private parser;
+    private builder;
+    constructor(pkg: VisioPackage);
+    /** Read document metadata from `docProps/core.xml` and `docProps/app.xml`. */
+    getMetadata(): DocumentMetadata;
+    /** Merge the supplied fields into the existing metadata and persist to the package. */
+    setMetadata(props: Partial<DocumentMetadata>): void;
+    /** Extract a string from a parsed XML node (handles plain strings and #text objects). */
+    private str;
+    /** Parse an ISO datetime string into a Date (returns undefined on failure). */
+    private date;
+    private parsedCore;
+    private parsedApp;
+    private writeCore;
+    private writeApp;
+    private blankCoreParsed;
+    private blankAppParsed;
+}

package/dist/core/MetadataManager.js

@@ -0,0 +1,154 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MetadataManager = void 0;
+const VisioConstants_1 = require("./VisioConstants");
+const XmlHelper_1 = require("../utils/XmlHelper");
+class MetadataManager {
+    constructor(pkg) {
+        this.pkg = pkg;
+        this.parser = (0, XmlHelper_1.createXmlParser)();
+        this.builder = (0, XmlHelper_1.createXmlBuilder)();
+    }
+    // ---- public API --------------------------------------------------------
+    /** Read document metadata from `docProps/core.xml` and `docProps/app.xml`. */
+    getMetadata() {
+        const core = this.parsedCore();
+        const app = this.parsedApp();
+        return {
+            title: this.str(core['dc:title']),
+            author: this.str(core['dc:creator']),
+            description: this.str(core['dc:description']),
+            keywords: this.str(core['cp:keywords']),
+            lastModifiedBy: this.str(core['cp:lastModifiedBy']),
+            created: this.date(core['dcterms:created']),
+            modified: this.date(core['dcterms:modified']),
+            company: this.str(app['Company']),
+            manager: this.str(app['Manager']),
+        };
+    }
+    /** Merge the supplied fields into the existing metadata and persist to the package. */
+    setMetadata(props) {
+        const coreKeys = [
+            'title', 'author', 'description', 'keywords', 'lastModifiedBy', 'created', 'modified',
+        ];
+        const appKeys = ['company', 'manager'];
+        if (coreKeys.some(k => k in props))
+            this.writeCore(props);
+        if (appKeys.some(k => k in props))
+            this.writeApp(props);
+    }
+    // ---- private helpers ---------------------------------------------------
+    /** Extract a string from a parsed XML node (handles plain strings and #text objects). */
+    str(val) {
+        if (val === undefined || val === null)
+            return undefined;
+        if (typeof val === 'string')
+            return val || undefined;
+        if (typeof val === 'object' && '#text' in val) {
+            const t = val['#text'];
+            const s = typeof t === 'string' ? t : String(t);
+            return s || undefined;
+        }
+        return undefined;
+    }
+    /** Parse an ISO datetime string into a Date (returns undefined on failure). */
+    date(val) {
+        const text = this.str(val);
+        if (!text)
+            return undefined;
+        const d = new Date(text);
+        return isNaN(d.getTime()) ? undefined : d;
+    }
+    parsedCore() {
+        try {
+            const xml = this.pkg.getFileText('docProps/core.xml');
+            const parsed = this.parser.parse(xml);
+            return parsed['cp:coreProperties'] ?? {};
+        }
+        catch {
+            return {};
+        }
+    }
+    parsedApp() {
+        try {
+            const xml = this.pkg.getFileText('docProps/app.xml');
+            const parsed = this.parser.parse(xml);
+            return parsed['Properties'] ?? {};
+        }
+        catch {
+            return {};
+        }
+    }
+    writeCore(props) {
+        let parsed;
+        try {
+            const xml = this.pkg.getFileText('docProps/core.xml');
+            parsed = this.parser.parse(xml);
+        }
+        catch {
+            parsed = this.blankCoreParsed();
+        }
+        const root = parsed['cp:coreProperties'];
+        if ('title' in props)
+            root['dc:title'] = props.title ?? '';
+        if ('author' in props)
+            root['dc:creator'] = props.author ?? '';
+        if ('description' in props)
+            root['dc:description'] = props.description ?? '';
+        if ('keywords' in props)
+            root['cp:keywords'] = props.keywords ?? '';
+        if ('lastModifiedBy' in props)
+            root['cp:lastModifiedBy'] = props.lastModifiedBy ?? '';
+        if ('created' in props && props.created !== undefined) {
+            root['dcterms:created'] = {
+                '@_xsi:type': 'dcterms:W3CDTF',
+                '#text': props.created.toISOString(),
+            };
+        }
+        if ('modified' in props && props.modified !== undefined) {
+            root['dcterms:modified'] = {
+                '@_xsi:type': 'dcterms:W3CDTF',
+                '#text': props.modified.toISOString(),
+            };
+        }
+        this.pkg.updateFile('docProps/core.xml', (0, XmlHelper_1.buildXml)(this.builder, parsed));
+    }
+    writeApp(props) {
+        let parsed;
+        try {
+            const xml = this.pkg.getFileText('docProps/app.xml');
+            parsed = this.parser.parse(xml);
+        }
+        catch {
+            parsed = this.blankAppParsed();
+        }
+        const root = parsed['Properties'];
+        if ('company' in props)
+            root['Company'] = props.company ?? '';
+        if ('manager' in props)
+            root['Manager'] = props.manager ?? '';
+        this.pkg.updateFile('docProps/app.xml', (0, XmlHelper_1.buildXml)(this.builder, parsed));
+    }
+    blankCoreParsed() {
+        return {
+            'cp:coreProperties': {
+                '@_xmlns:cp': VisioConstants_1.XML_NAMESPACES.CORE_PROPERTIES,
+                '@_xmlns:dc': VisioConstants_1.XML_NAMESPACES.DC_ELEMENTS,
+                '@_xmlns:dcterms': VisioConstants_1.XML_NAMESPACES.DC_TERMS,
+                '@_xmlns:dcmitype': VisioConstants_1.XML_NAMESPACES.DC_DCMITYPE,
+                '@_xmlns:xsi': VisioConstants_1.XML_NAMESPACES.XSI,
+            },
+        };
+    }
+    blankAppParsed() {
+        return {
+            'Properties': {
+                '@_xmlns': VisioConstants_1.XML_NAMESPACES.EXTENDED_PROPERTIES,
+                '@_xmlns:vt': VisioConstants_1.XML_NAMESPACES.DOC_PROPS_VTYPES,
+                'Application': 'ts-visio',
+                'Template': 'Basic',
+            },
+        };
+    }
+}
+exports.MetadataManager = MetadataManager;

package/dist/types/VisioTypes.d.ts

@@ -72,6 +72,27 @@ export declare enum VisioPropType {
     Duration = 6,
     Currency = 7
 }
+/** Document-level metadata that maps to `docProps/core.xml` and `docProps/app.xml`. */
+export interface DocumentMetadata {
+    /** Document title (`dc:title`). */
+    title?: string;
+    /** Author / creator (`dc:creator`). */
+    author?: string;
+    /** Short description (`dc:description`). */
+    description?: string;
+    /** Space-separated keywords (`cp:keywords`). */
+    keywords?: string;
+    /** Last-modified-by user (`cp:lastModifiedBy`). */
+    lastModifiedBy?: string;
+    /** Company name from `app.xml` `<Company>`. */
+    company?: string;
+    /** Manager name from `app.xml` `<Manager>`. */
+    manager?: string;
+    /** Document creation timestamp (`dcterms:created`). */
+    created?: Date;
+    /** Last-modified timestamp (`dcterms:modified`). */
+    modified?: Date;
+}
 export type PageOrientation = 'portrait' | 'landscape';
 /** Common paper sizes in inches (width × height in portrait orientation). */
 export declare const PageSizes: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ts-visio",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "scripts": {