From f3f7b9bd2718d8ea58be4c8aaaf3d36ea7ced0c3 Mon Sep 17 00:00:00 2001 From: eligrey <~@eligrey.com> Date: Fri, 29 Jul 2022 22:28:46 -0700 Subject: [PATCH 1/6] Add documentation and utility for importing native Files --- README.md | 31 ++++++++++++++++++++++++++++++- package.json | 2 +- src/API.ts | 15 +++++++++++++++ 3 files changed, 46 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 1de571d5..18f6dea6 100644 --- a/README.md +++ b/README.md @@ -134,6 +134,35 @@ type RemoteResource = { }; ``` +### PenumbraFile + +Encryption & decryption APIs work on PenumbraFile descriptors to that store file data and metadata. + +```ts +/** Penumbra file composition */ +export interface PenumbraFile extends Omit { + /** Backing stream */ + stream: ReadableStream; + /** File size (if backed by a ReadableStream) */ + size?: number; + /** Optional ID for tracking encryption completion */ + id?: number | string; + /** Last modified date */ + lastModified?: Date; +} +``` + +HTML File and FileList descriptors can be converted for use with penumbra APIs through `penumbra.importFile(files: File, path?: string)` and can be used to encrypt and decrypt files. + +```ts +// Automatically encrypt & save files selected in a file selector +const fileSelector = document.getElementById('file-selector'); +fileSelector.addEventListener('change', (event) => { + const file = penumbra.importFile(event.target.files[0]); + penumbra.encrypt(file).then(penumbra.save); +}); +``` + ### .get Fetch and decrypt remote files. @@ -346,7 +375,7 @@ await writer.close(); ### .setWorkerLocation -Configure the location of Penumbra's worker threads. +Configure the location of Penumbra's worker threads. This should be called before any other Penumbra methods and is not currently reconfigurable post-initialization. ```ts penumbra.setWorkerLocation(location: WorkerLocationOptions | string): Promise diff --git a/package.json b/package.json index a6627eff..ddbf999a 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@transcend-io/penumbra", - "version": "5.3.2", + "version": "5.4.0", "description": "Crypto streams for the browser.", "main": "dist/main.penumbra.js", "types": "ts-build/src/index.d.ts", diff --git a/src/API.ts b/src/API.ts index 6b20e98e..e5cf62b3 100644 --- a/src/API.ts +++ b/src/API.ts @@ -581,9 +581,24 @@ function getTextOrURI(files: PenumbraFile[]): Promise[] { }); } +/** + * Convert HTML File object to a PenumbraFile + * + * @param file - File to import + * @returns PenumbraFile + */ +async function importFile(file: File): Promise { + return { + stream: new Response(await file.arrayBuffer()).body as ReadableStream, + size: file.size, + mimetype: file.type, + }; +} + const penumbra = { preconnect, preload, + importFile, get, encrypt, decrypt, From eae8499ee87797922928758018c9e07831ef434a Mon Sep 17 00:00:00 2001 From: eligrey <~@eligrey.com> Date: Fri, 29 Jul 2022 22:32:12 -0700 Subject: [PATCH 2/6] Update README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 18f6dea6..b2a2db24 100644 --- a/README.md +++ b/README.md @@ -158,7 +158,7 @@ HTML File and FileList descriptors can be converted for use with penumbra APIs t // Automatically encrypt & save files selected in a file selector const fileSelector = document.getElementById('file-selector'); fileSelector.addEventListener('change', (event) => { - const file = penumbra.importFile(event.target.files[0]); + const file = await penumbra.importFile(event.target.files[0]); penumbra.encrypt(file).then(penumbra.save); }); ``` From 98f40205bfecc5badb9ccd819522c4c0d4a0b4ae Mon Sep 17 00:00:00 2001 From: eligrey <~@eligrey.com> Date: Sat, 30 Jul 2022 12:05:21 -0700 Subject: [PATCH 3/6] add path argument to importFile() --- README.md | 2 +- src/API.ts | 4 +++- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index b2a2db24..6ae7de4d 100644 --- a/README.md +++ b/README.md @@ -152,7 +152,7 @@ export interface PenumbraFile extends Omit { } ``` -HTML File and FileList descriptors can be converted for use with penumbra APIs through `penumbra.importFile(files: File, path?: string)` and can be used to encrypt and decrypt files. +Native File objects can be converted for use with penumbra APIs through `penumbra.importFile(file: File, path?: string)` and can be used to encrypt and decrypt files. ```ts // Automatically encrypt & save files selected in a file selector diff --git a/src/API.ts b/src/API.ts index e5cf62b3..889e3747 100644 --- a/src/API.ts +++ b/src/API.ts @@ -585,13 +585,15 @@ function getTextOrURI(files: PenumbraFile[]): Promise[] { * Convert HTML File object to a PenumbraFile * * @param file - File to import + * @param path - File path * @returns PenumbraFile */ -async function importFile(file: File): Promise { +async function importFile(file: File, path?: string): Promise { return { stream: new Response(await file.arrayBuffer()).body as ReadableStream, size: file.size, mimetype: file.type, + path, }; } From d42870c99345fec0989cad866fac1bf0ec19c57d Mon Sep 17 00:00:00 2001 From: eligrey <~@eligrey.com> Date: Mon, 1 Aug 2022 12:51:18 -0700 Subject: [PATCH 4/6] Update README.md --- README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/README.md b/README.md index 6ae7de4d..7b919cfd 100644 --- a/README.md +++ b/README.md @@ -10,6 +10,7 @@ - [With Yarn/NPM](#with-yarnnpm) - [Vanilla JS](#vanilla-js) - [RemoteResource](#remoteresource) + - [PenumbraFile](#penumbrafile) - [.get](#get) - [.encrypt](#encrypt) - [.encrypt() examples:](#encrypt-examples) From 4ab5b081f2361983c67ac48cf6c3aa5fca89013a Mon Sep 17 00:00:00 2001 From: eligrey <~@eligrey.com> Date: Mon, 1 Aug 2022 12:57:57 -0700 Subject: [PATCH 5/6] Update mock.ts --- src/mock.ts | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/src/mock.ts b/src/mock.ts index fc406bfe..90f51d97 100644 --- a/src/mock.ts +++ b/src/mock.ts @@ -9,6 +9,12 @@ const supported = (): PenumbraSupportLevel => -0; supported.levels = PenumbraSupportLevel; const MOCK_API: PenumbraAPI = { + importFile: async (file, path) => ({ + stream: new Response(await file.arrayBuffer()).body as ReadableStream, + size: file.size, + mimetype: file.type, + path, + }), get: async () => [], save: () => new AbortController(), supported, From 64298000eef91451c349eaf3aa800846f161795a Mon Sep 17 00:00:00 2001 From: eligrey <~@eligrey.com> Date: Mon, 1 Aug 2022 13:32:55 -0700 Subject: [PATCH 6/6] Update package.json --- package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/package.json b/package.json index ddbf999a..5763b8b9 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@transcend-io/penumbra", - "version": "5.4.0", + "version": "5.4.1", "description": "Crypto streams for the browser.", "main": "dist/main.penumbra.js", "types": "ts-build/src/index.d.ts",