{"id":18308686,"url":"https://github.com/ardriveapp/ardrive-core-js","last_synced_at":"2025-04-05T08:03:48.985Z","repository":{"id":38190523,"uuid":"292673288","full_name":"ardriveapp/ardrive-core-js","owner":"ardriveapp","description":"ArDrive Core contains the essential back end application features to support the ArDrive CLI and Desktop apps, such as file management, Permaweb upload/download, wallet management and other common functions.","archived":false,"fork":false,"pushed_at":"2025-03-26T12:43:02.000Z","size":245068,"stargazers_count":51,"open_issues_count":5,"forks_count":13,"subscribers_count":8,"default_branch":"dev","last_synced_at":"2025-03-29T07:05:41.441Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ardriveapp.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-09-03T20:28:53.000Z","updated_at":"2025-03-28T17:59:17.000Z","dependencies_parsed_at":"2023-01-29T22:15:43.364Z","dependency_job_id":"89f56b3a-c13c-411d-ac98-0e3e71686d12","html_url":"https://github.com/ardriveapp/ardrive-core-js","commit_stats":{"total_commits":1456,"total_committers":18,"mean_commits":80.88888888888889,"dds":0.459478021978022,"last_synced_commit":"a9729df70a55825a1d181ecc1d54a63ce8778fdb"},"previous_names":[],"tags_count":36,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ardriveapp%2Fardrive-core-js","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ardriveapp%2Fardrive-core-js/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ardriveapp%2Fardrive-core-js/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ardriveapp%2Fardrive-core-js/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ardriveapp","download_url":"https://codeload.github.com/ardriveapp/ardrive-core-js/tar.gz/refs/heads/dev","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247305932,"owners_count":20917208,"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":[],"created_at":"2024-11-05T16:08:53.206Z","updated_at":"2025-04-05T08:03:48.963Z","avatar_url":"https://github.com/ardriveapp.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ardrive-core-js\n\nArDrive Core is a TypeScript library that contains the essential back end application features to support the ArDrive CLI and Desktop apps, such as file management, Permaweb upload/download, wallet management, and other common functions.\n\nEngage with the community in [Discord](https://discord.gg/7RuTBckX) for more information.\n\n## Integrating with ArDrive Core\n\nTo add the ArDrive Core library to your project, simply add it as a dependency:\n\n```shell\nyarn add ardrive-core-js\n```\n\nThe recommended approach for integrating with ArDrive Core as a dependency in your project is to construct and use the methods provided on the `ArDrive` class. Developers can use the convenience function `arDriveFactory` to construct the `ArDrive` class.\n\nBelow are a few common examples of interacting with Core:\n\n```ts\nimport { readJWKFile, arDriveFactory } from 'ardrive-core-js';\n\n// Read wallet from file\nconst myWallet = readJWKFile('/path/to/wallet');\n\n// Construct ArDrive class\nconst arDrive = arDriveFactory({ wallet: myWallet });\n\n// Create a public drive and its root folder\nconst createDriveResult = await arDrive.createPublicDrive({ driveName: 'My-Drive' });\n```\n\n```ts\nimport { wrapFileOrFolder, EID } from 'ardrive-core-js';\n\n// Wrap file for upload\nconst wrappedEntity = wrapFileOrFolder('path/to/file');\n\n// Construct a safe Entity ID Type\nconst destFolderId = EID('10108b54a-eb5e-4134-8ae2-a3946a428ec7');\n\n// Upload a public file to destination folder\nconst uploadFileResult = await arDrive.uploadAllEntities({\n    entitiesToUpload: [{ wrappedEntity, destFolderId }]\n});\n```\n\n```ts\nimport { deriveDriveKey } from 'ardrive-core-js';\n\n// Derive a private drive key from password, wallet, and drive ID\nconst driveKey = await deriveDriveKey(\n    'mySecretPassWord',\n    '12345674a-eb5e-4134-8ae2-a3946a428ec7',\n    JSON.stringify((myWallet as JWKWallet).getPrivateKey())\n);\n\n// Create a private folder\nconst createFolderResult = await arDrive.createPrivateFolder({\n    folderName: 'My New Private Folder',\n    driveKey,\n    parentFolderId: EID('47162534a-eb5e-4134-8ae2-a3946a428ec7')\n});\n```\n\n```ts\nimport { wrapFileOrFolder, EntityKey, EID } from 'ardrive-core-js';\n\n// Derive a private drive key from raw drive key string\nconst driveKey = new EntityKey(Buffer.from('MyAwesomeDriveKeyZZZZZZZZZZZZZZZZZZZZFAKE/s', 'base64'));\n\n// Wrap folder and all of its contents for upload\nconst wrappedFolder = wrapFileOrFolder('path/to/folder');\n\n// Upload a private folder and all its contents\nconst uploadFileResult = await arDrive.uploadAllEntities({\n    entitiesToUpload: [\n        {\n            wrappedEntity: wrappedFolder,\n            destFolderId: EID('76543214a-eb5e-4134-8ae2-a3946a428ec7'),\n            driveKey\n        },\n        // And some other public file to a different destination 🤯\n        {\n          wrappedEntity: someOtherWrappedFile\n          destFolderId: EID('675489321-eb5e-4134-8ae2-a3946a428ec7')\n        }\n    ]\n});\n```\n\n```ts\n// Upload ArFS Entities To Turbo (BETA)\n// The presence of `turboSettings` in `arDriveFactory` enables sending to Turbo\nconst arDrive = arDriveFactory({ wallet: myWallet, turboSettings: {} });\n\nconst uploadFileResult = await arDrive.uploadAllEntities({\n    entitiesToUpload: [{ wrappedEntity, destFolderId }]\n});\n```\n\n## Development Environment Setup\n\nWe use nvm to manage our Node engine version and, if necessary, to install an npm version that we can then use to install Yarn.\n\nNote for Windows: **We recommend using WSL** for setting up NVM on Windows using the [instructions described here][wsl-install] then continue the steps below.\n\n1. Install nvm [using their instructions][nvm-install].\n2. We use Node 18.x -- ensure that the correct Node version is installed and activated by performing `nvm install` and then `nvm use`\n3. We use Yarn 3.x please [follow the installation guidelines here][yarn-install]\n4. We use husky 6.x to manage the git commit hooks that help to improve the quality of our commits. Please run:\n   `yarn husky install`\n   to enable git hooks for this local repository. Without doing so, you risk committing non-compliant code to the repository.\n\n5. Install all node package dependencies by running `yarn install --check-cache`\n\n### Recommended Visual Studio Code extensions\n\nTo ensure your environment is compatible, we also recommend the following VSCode extensions:\n\n-   [ES-Lint][eslint-vscode]\n-   [Editor-Config][editor-config-vscode]\n-   [Prettier][prettier-vscode]\n-   [ZipFS][zipfs-vscode]\n\n## Building the Library\n\nSimply run `yarn build`. This will clean the project and compile the TypeScript library.\n\n## Testing the Library\n\nThis library is setup for [Mocha] testing with [Chai] and [Sinon]. Configuration for Mocha can be found in `.mocharc.js`\n\nTo run all of the tests use:\n\n```shell\nyarn test\n```\n\nTo run a specific test, use Mocha's [grep] command. This will cause Mocha to only run the tests that contain the provided RegExp.\n\nThe `-g` command will **only** match the characters used in the `describe()` and `it()` title arguments. It will **not** match files names or folders.\n\nFor example:\n\n```shell\nyarn test -g 'My specific unit test'\n```\n\nWill run this test:\n\n```ts\ndescribe('My specific unit test', () =\u003e {\n    it('functions correctly', () =\u003e {\n        // ...\n    });\n});\n```\n\n### Coverage\n\n[Istanbul.js (nyc)][nyc] has been added for code coverage reporting. Configuration for the nyc package can be found in `nyc.config.js`\n\nOn each `yarn test` command, nyc will output a code coverage summary in the terminal. In addition, a more detailed HTML version will output to the `/coverage` directory. Simply run `/coverage/index.html` in your browser to view the HTML version.\n\nAlternatively, you can view a verbose coverage output in the terminal by running:\n\n```shell\nyarn coverage\n```\n\n### Adding tests\n\nThere are many different syntax options available with the Chai library, which can be found in their [documentation][chai-doc]. For examples on unit testing, visit `src/example.test.ts`, and for integration testing: `tests/example.test.ts`.\n\nUnit tests should be located adjacent (or right next to) the file they are referencing. They should also be named the same with the `.test.ts` extension. In contrast, integration tests will live in the `/tests` directory.\n\nFor example:\n\n```shell\nardrive-core-js/\n├── src\n│   ├── fileToTest.ts\n│   └── fileToTest.test.ts   \u003c-- Unit test\n└── tests\n    └── bestApi.test.ts   \u003c----- Integration test\n```\n\n### Using Sinon\n\nSinon can be used to create spies, mocks, fakes, stubs, and more. There are some basic examples of using the library shown in the example test files shared above.\n\nFor more information on what you can do with Sinon, visit their [documentation][sinon-doc].\n\n### Debugging with Power-Assert\n\n[Power-Assert] is setup as another testing tool. The library can be used to provide a very detailed output of your failing test cases. This can become super useful while debugging a test.\n\nTo use this tool, it must be imported using this syntax:\n\n```ts\nimport assert = require('assert');\n```\n\nThen use `assert` in your error throwing test case. Commenting out the Chai assertion will produce a cleaner output:\n\n```ts\n// expect(failingOutput).to.equal(expectedOutput);\nassert(failingOutput === expectedOutput);\n```\n\nAnd finally, to view the detailed error messages in your terminal:\n\n```shell\nyarn power-assert -g 'My test case'\n```\n\n### Progress Logging of Transaction Uploads\n\nProgress logging of transaction uploads to stderr can be enabled by setting the `ARDRIVE_PROGRESS_LOG` environment variable to `1`:\n\n```shell\nUploading file transaction 1 of total 2 transactions...\nTransaction _GKQasQX194a364Hph8Oe-oku1AdfHwxWOw9_JC1yjc Upload Progress: 0%\nTransaction _GKQasQX194a364Hph8Oe-oku1AdfHwxWOw9_JC1yjc Upload Progress: 35%\nTransaction _GKQasQX194a364Hph8Oe-oku1AdfHwxWOw9_JC1yjc Upload Progress: 66%\nTransaction _GKQasQX194a364Hph8Oe-oku1AdfHwxWOw9_JC1yjc Upload Progress: 100%\nUploading file transaction 2 of total 2 transactions...\nTransaction nA1stCdTkuf290k0qsqvmJ78isEC0bwgrAi3D8Cl1LU Upload Progress: 0%\nTransaction nA1stCdTkuf290k0qsqvmJ78isEC0bwgrAi3D8Cl1LU Upload Progress: 13%\nTransaction nA1stCdTkuf290k0qsqvmJ78isEC0bwgrAi3D8Cl1LU Upload Progress: 28%\nTransaction nA1stCdTkuf290k0qsqvmJ78isEC0bwgrAi3D8Cl1LU Upload Progress: 42%\nTransaction nA1stCdTkuf290k0qsqvmJ78isEC0bwgrAi3D8Cl1LU Upload Progress: 60%\nTransaction nA1stCdTkuf290k0qsqvmJ78isEC0bwgrAi3D8Cl1LU Upload Progress: 76%\nTransaction nA1stCdTkuf290k0qsqvmJ78isEC0bwgrAi3D8Cl1LU Upload Progress: 91%\nTransaction nA1stCdTkuf290k0qsqvmJ78isEC0bwgrAi3D8Cl1LU Upload Progress: 100%\n```\n\n### Persistent Caching of ArFS Entity Metadata\n\nTo avoid redundant requests to the Arweave network for immutable ArFS entity metadata, a persistent file cache is created and maintained at:\n\n```shell\nWindows: \u003cos.homedir()\u003e/ardrive-caches/metadata\nNon-Windows: \u003cos.homedir()\u003e/.ardrive/caches/metadata\n```\n\nThe `XDG_CACHE_HOME` environment variable is honored, where applicable, and will be used in place of `os.homedir()` in the scenarios described above.\n\nMetadata cache logging to stderr can be enabled by setting the `ARDRIVE_CACHE_LOG` environment variable to `1`.\n\nCache performance is UNDEFINED for multi-process scenarios, but is presumed to be generally usable.\n\nThe cache can be manually cleared safely at any time that any integrating app is not in operation.\n\n### Applying Custom MetaData to ArFS File Transactions\n\nCustom metadata can be attached to ArFS File Transactions. Metadata can be applied to either the GQL tags on the MetaData Transaction, the MetaData Transaction's Data JSON, or both.\n\nAll custom tags can be accessed by using by using `ArDrive` class read methods such as `getPublicFile`, `getPrivateFile`, `listPrivateFolder`, etc.\n\n```ts\nconst arDrive = arDriveAnonymousFactory({});\nconst fileInfo = await arDrive.getPublicFile({ fileId });\nconst myMetaDataGqlTags = fileInfo.customMetaDataGqlTags;\nconst myMetaDataJsonFields = fileInfo.customMetaDataJson;\n```\n\nWhen the custom metadata is attached to the MetaData Transaction's GQL tags, they will become visible on any Arweave GQL gateway and also third party tools that read GQL data.\n\nWhen these tags are added to the MetaData Transaction's Data JSON they can be read by downloading the JSON data directly from `https://arweave.net/\u003cmetadata tx id\u003e`.\n\nTo add this custom metadata to your file metadata transactions, users can pass an object containing custom tags when wrapping content to upload:\n\n```ts\nconst fileToUpload = wrapFileOrFolder(\n    'path/to/file/on/system', // File or Folder Path\n    'application/custom-content-type', // Custom Content Type\n    customMetaData: { // Custom MetaData\n        metaDataJson: { ['My-Custom-Tag-Name']: 'Single-Custom-Value' },\n        metaDataGqlTags: {\n            ['Another-Custom-Tag']: ['First-Custom-Value', 'Second-Custom-Value', 'Third-Custom-Value']\n        }\n    }\n);\n```\n\n[yarn-install]: https://yarnpkg.com/getting-started/install\n[nvm-install]: https://github.com/nvm-sh/nvm#installing-and-updating\n[wsl-install]: https://code.visualstudio.com/docs/remote/wsl\n[editor-config-vscode]: https://marketplace.visualstudio.com/items?itemName=EditorConfig.EditorConfig\n[prettier-vscode]: https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode\n[zipfs-vscode]: https://marketplace.visualstudio.com/items?itemName=arcanis.vscode-zipfs\n[eslint-vscode]: https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint\n[mocha]: https://github.com/mochajs/mocha\n[chai]: https://github.com/chaijs/chai\n[sinon]: https://github.com/sinonjs/sinon\n[power-assert]: https://github.com/power-assert-js/power-assert\n[nyc]: https://github.com/istanbuljs/nyc\n[grep]: https://mochajs.org/#-grep-regexp-g-regexp\n[chai-doc]: https://www.chaijs.com/api/bdd/\n[sinon-doc]: https://sinonjs.org/releases/latest\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fardriveapp%2Fardrive-core-js","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fardriveapp%2Fardrive-core-js","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fardriveapp%2Fardrive-core-js/lists"}