mdls-ts

OSX's mdls from node.

A thin wrapper around mdls.

You give it a path, it runs mdls and calls a callback with the result.

This is a fork of node-mdls which adds TypeScript, native ESM, and sync support.

Install

npm install --save mdls-ts

Usage

Basic example

try {
    const data = await mdls('./index.js');
    console.log('Data', data);
} catch (err) {
    console.log('Error', err);
}

If all goes well, this will log:

{ ItemContentCreationDate: Sat May 17 2014 14:32:53 GMT-0700 (PDT),
  ItemContentModificationDate: Sat May 17 2014 15:01:52 GMT-0700 (PDT),
  ItemContentType: 'com.netscape.javascript-source',
  ItemContentTypeTree:
   [ 'com.netscape.javascript-source',
     'public.source-code',
     'public.plain-text',
     'public.text',
     'public.data',
     'public.item',
     'public.content',
     'public.executable' ],
  ItemDateAdded: Sat May 17 2014 14:32:53 GMT-0700 (PDT),
  ItemDisplayName: 'index.js',
  ItemFSContentChangeDate: Sat May 17 2014 15:01:52 GMT-0700 (PDT),
  ItemFSCreationDate: Sat May 17 2014 14:32:53 GMT-0700 (PDT),
  ItemFSCreatorCode: '',
  ItemFSFinderFlags: 0,
  ItemFSHasCustomIcon: 0,
  ItemFSInvisible: 0,
  ItemFSIsExtensionHidden: 0,
  ItemFSIsStationery: 0,
  ItemFSLabel: 0,
  ItemFSName: 'index.js',
  ItemFSNodeCount: 1554,
  ItemFSOwnerGroupID: 20,
  ItemFSOwnerUserID: 501,
  ItemFSSize: 1554,
  ItemFSTypeCode: '',
  ItemKind: 'JavaScript',
  ItemLogicalSize: 1554,
  ItemPhysicalSize: 4096 }

Each date above is a JavaScript date object. You can get the Unix timestamp out with the getTime method of each object.

Note that running mdls the command line utility would have returned:

kMDItemContentCreationDate     = 2014-05-17 21:32:53 +0000
kMDItemContentModificationDate = 2014-05-17 22:01:52 +0000
kMDItemContentType             = "com.netscape.javascript-source"
kMDItemContentTypeTree         = (
    "com.netscape.javascript-source",
    "public.source-code",
    "public.plain-text",
    "public.text",
    "public.data",
    "public.item",
    "public.content",
    "public.executable"
)
kMDItemDateAdded               = 2014-05-17 21:32:53 +0000
kMDItemDisplayName             = "index.js"
kMDItemFSContentChangeDate     = 2014-05-17 22:01:52 +0000
kMDItemFSCreationDate          = 2014-05-17 21:32:53 +0000
kMDItemFSCreatorCode           = ""
kMDItemFSFinderFlags           = 0
kMDItemFSHasCustomIcon         = 0
kMDItemFSInvisible             = 0
kMDItemFSIsExtensionHidden     = 0
kMDItemFSIsStationery          = 0
kMDItemFSLabel                 = 0
kMDItemFSName                  = "index.js"
kMDItemFSNodeCount             = 1554
kMDItemFSOwnerGroupID          = 20
kMDItemFSOwnerUserID           = 501
kMDItemFSSize                  = 1554
kMDItemFSTypeCode              = ""
kMDItemKind                    = "JavaScript"
kMDItemLogicalSize             = 1554
kMDItemPhysicalSize            = 4096

Example with arguments

You can also pass in arguments (as a string):

try {
    const data = await mdls('./index.js', '-name kMDItemContentTypeTree');
    console.log('Data', data);
} catch (err) {
    console.log('Error', err);
}

UTI (Uniform Type Identifier) Functions

Get the UTI for a file:

import {getUTI} from 'mdls-ts';

const uti = getUTI('./document.pdf');
console.log(uti); // 'com.adobe.pdf'

Get detailed UTI information including type hierarchy:

import {getUTIInfo} from 'mdls-ts';

const info = getUTIInfo('./image.jpg');
console.log(info);
// {
//   ItemContentType: 'public.jpeg',
//   ItemContentTypeTree: [
//     'public.jpeg',
//     'public.image',
//     'public.data',
//     'public.item',
//     'public.content'
//   ],
//   ItemKind: 'JPEG image'
// }

Get a localized, human-readable description for a UTI:

import {getLocalizedDescription} from 'mdls-ts';

const description = getLocalizedDescription('public.jpeg');
console.log(description); // 'JPEG image'

const pdfDesc = getLocalizedDescription('com.adobe.pdf');
console.log(pdfDesc); // 'PDF document'

API

mdls(file, [args], [callback])

Returns a promise that resolves with file metadata. Optionally accepts a callback.

• file (string): Path to the file
• args (string, optional): Additional arguments to pass to mdls
• callback (function, optional): Callback function (err, data)

mdlsSync(file, [args])

Synchronous version of mdls.

getUTI(file)

Returns the UTI (Uniform Type Identifier) string for a file.

• file (string): Path to the file
• Returns: string | null - The UTI or null if not available

getUTIInfo(file)

Returns detailed UTI information including the type hierarchy.

• file (string): Path to the file
• Returns: object with properties:
  • ItemContentType: The primary UTI
  • ItemContentTypeTree: Array of UTIs showing the type hierarchy
  • ItemKind: Human-readable description of the file type

getLocalizedDescription(uti)

Returns a localized, human-readable description for a UTI using macOS's NSWorkspace API.

• uti (string): The UTI string (e.g., 'com.adobe.pdf', 'public.jpeg')
• Returns: string | null - Localized description or null if not available
• Note: Requires native addon (macOS only)

Performance

This package now includes a native N-API addon for improved performance. The addon provides:

• Faster execution by avoiding shell overhead
• Better parsing of mdls output
• Automatic fallback to JavaScript implementation if native build is unavailable