{"id":16672171,"url":"https://github.com/vincentdchan/node-xattr","last_synced_at":"2025-04-09T19:52:57.709Z","repository":{"id":43988695,"uuid":"242115052","full_name":"vincentdchan/node-xattr","owner":"vincentdchan","description":"A library to manipulate xattr on macOS for Node.js.","archived":false,"fork":false,"pushed_at":"2022-12-10T19:03:41.000Z","size":1485,"stargazers_count":11,"open_issues_count":6,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-23T21:51:52.711Z","etag":null,"topics":["electron","macos","nodejs","typescript","xattr","xattr-support"],"latest_commit_sha":null,"homepage":"","language":"Objective-C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vincentdchan.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-02-21T10:37:51.000Z","updated_at":"2024-12-25T15:51:53.000Z","dependencies_parsed_at":"2023-01-26T10:16:20.317Z","dependency_job_id":null,"html_url":"https://github.com/vincentdchan/node-xattr","commit_stats":{"total_commits":17,"total_committers":2,"mean_commits":8.5,"dds":"0.11764705882352944","last_synced_commit":"0701211440aacec84e78453f65f30e6c71215dd0"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vincentdchan%2Fnode-xattr","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vincentdchan%2Fnode-xattr/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vincentdchan%2Fnode-xattr/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vincentdchan%2Fnode-xattr/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vincentdchan","download_url":"https://codeload.github.com/vincentdchan/node-xattr/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248103915,"owners_count":21048244,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["electron","macos","nodejs","typescript","xattr","xattr-support"],"created_at":"2024-10-12T12:05:29.112Z","updated_at":"2025-04-09T19:52:57.671Z","avatar_url":"https://github.com/vincentdchan.png","language":"Objective-C","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![npm version](https://badge.fury.io/js/node-xattr.svg)](https://badge.fury.io/js/node-xattr)\n\n# node-xattr\n\nA library to manipulate xattr on macOS with Typescript support.\nAPIs provided by this library are similar to node's fs module.\n\n- [**Requirements**](#requirements)\n- [**Installation**](#installation)\n- [**When to use the sync version**](#when-to-use-the-sync-version)\n- [**Get xattr**](#get-xattr)\n- [**Set xattr**](#set-xattr)\n- [**List xattr**](#list-xattr)\n- [**Remove xattr**](#remove-xattr)\n- [**Set Custom Icon For File**](#set-custom-icon)\n- [**Parse FileMeta**](#parse-filemeta)\n\n# What's xattr\n\n\u003e Extended attributes are arbitrary metadata stored with a file, but separate from the filesystem attributes (such as modification time or file size). The metadata is often a null-terminated UTF-8 string, but can also be arbitrary binary data.\n\nXattr is a mechanism provided by the system.\nWith xattr, you can store your own data as attributes to file. Also, you can pass data to Finder or other apps.\n\nFor example, you can set custom icon for a file:\n\n![](./custom-icon-screenshot.png)\n\nYou can add a `com.apple.quarantine` xattr to make the system check the origin of the file you downloaded:\n\n![](./quarantine.png)\n\nOr you can remove this xattr on an existing file, and this window will not display.\n\n# Requirements\n\nRuntime\n\n- Node.js v10+ (Electron with Node.js 10+ works)\n\nDevelopment\n\n- macOS 10.14+ with XCode\n\n# Installation\n\n```sh\n$ yarn add node-xattr\n```\n\n# When to use the sync version\n\nTechnically, the sync version would be a little faster. Because the async version waits for a queue to schedule.\nAlso, The sync verion is realtime, it would be an advantage in some scenarios.\nThe disadvantage of the sync version is that it will probably block the process. So DO NOT use sync version in \nsome UI process(such as the renderer process of Electron).\nThe best scenario to use sync version is in background worker/process/thread.\n\n# Set xattr\n\n```\nsetXattrSync(path: string, name: string, value: string | Buffer): void;\n\nsetXattr(path: string, name: string, value: string | Buffer): Promise\u003cvoid\u003e;\n```\n\nSync\n```js\nconst { setXattrSync } = require('node-xattr');\nsetXattrSync('./test.txt', 'key', 'value');\n```\n\nAsync\n```js\nconst { setXattr } = require('node-xattr');\n\nsetXattr('./test.txt', 'key', 'value').catch(err =\u003e console.error(err));\n```\n\n# Get xattr\n\n```\ngetXattrSync(path: string, name: string): Buffer;\n\ngetXattrSync(path: string, name: string, encoding: string): string;\n\ngetXattr(path: string, name: string): Promise\u003cBuffer\u003e;\n\ngetXattr(path: string, name: string, encoding: string): Promise\u003cstring\u003e;\n```\n\nSync\n```js\nconst { getXattrSync } = require('node-xattr');\nconst buffer = getXattrSync('./test.txt', 'key');\nconst string = getXattrSync('./test.txt', 'key', 'utf8');\n```\n\n\nAsync\n```js\nconst { getXattr } = require('node-xattr');\n\ngetXattr('./test.txt', 'key', function (err, buffer) {\n  if (err) {\n    console.error(err);\n    return;\n  }\n  console.log(buffer);\n});\n\ngetXattr('./test.txt', 'key').then(buffer =\u003e console.log(buffer)).catch(err =\u003e console.error(err));\n\ngetXattr('./test.txt', 'key', 'utf8').then(str =\u003e console.log(str)).catch(err =\u003e console.error(err));\n```\n\n# List xattr\n\n```\nlistXattrSync(path: string): string[];\n\nlistXattr(path: string): Promise\u003cstring[]\u003e;\n```\n\nSync\n```js\nconst { listXattrSync } = require('node-xattr');\n\nconst list = listXattrSync('./test.txt');\n```\n\nAsync\n```js\nconst { listXattr } = require('node-xattr');\n\nlistXattr('./test.txt').then(list =\u003e console.log(list)).catch(err =\u003e console.error(err));\n```\n\n# Remove xattr\n\n```\nremoveXattrSync(path: string, name: string): void;\n\nremoveXattr(path: string, name: string): Promise\u003cvoid\u003e;\n```\n\nSync\n```js\nconst { removeXattrSync } = require('node-xattr');\nremoveXattrSync('./test.txt', 'key');\n```\n\nAsync\n```js\nconst { removeXattr } = require('node-xattr');\nremoveXattr('./test.txt', 'key').catch(err =\u003e console.error(err));\n```\n\n# Set Custom Icon\n\n`setCustomIcon` are in `macUtils` namespace:\n\n```\nsetCustomIcon(filePath: string, iconPath: string): Promise\u003cvoid\u003e;\nsetCustomIconSync(filePath: string, iconPath: string): void;\n```\n\nSync\n```js\nconst { macUtils } = require('node-xattr');\n\nmacUtils.setCustomIconSync(TestFile, iconPath);\n```\n\nAsync\n```js\nconst { macUtils } = require('node-xattr');\nmacUtils.setCustomIcon(TestFile, iconPath).catch(err =\u003e console.log(err));\n```\n\n# Parse FileMeta\n\nThis library provide utils to parse some content written by system:\n\n```\nserializeArrayOfString(content: string[]): Buffer;\ndeserializeArrayOfString(buffer: Buffer): string[];\n```\n\nYou can use above functions in `macUtils` to parse `com.apple.metadata:kMDItemWhereFroms`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvincentdchan%2Fnode-xattr","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvincentdchan%2Fnode-xattr","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvincentdchan%2Fnode-xattr/lists"}