@octane-xplat/files 0.9.0 → 0.11.0

package/src/files.ts

@@ -2,10 +2,26 @@
 // are still used for writes; picked Android SAF references may be content://
 // URIs and must be read through ContentResolver.
 import { openFilePicker } from '@nativescript-community/ui-document-picker'
-import { Application, File, knownFolders, path } from '@nativescript/core'
-import type { FileRef } from './types'
+import { Application, File, knownFolders, path, Utils } from '@nativescript/core'
+import {
+	assertSafeFileName,
+	exactBuffer,
+	exportBusy,
+	fileTooLarge,
+	throwIfAborted,
+} from './file-bytes'
+
+import type {
+	FileExportOptions,
+	FileExportResult,
+	FileReadBytesOptions,
+	FileRef,
+	Files,
+} from './types'
 
 const docs = () => knownFolders.documents()
+const READ_CHUNK = 64 * 1024
+const ANDROID_EXPORT_REQUEST_CODE = 1241
 
 function pickerTypes(accept: string): { extensions: string[]; mimeTypes: string[] } {
 	const values = accept
@@ -86,40 +102,355 @@ async function readContentUri(uri: string): Promise<string> {
 	}
 }
 
-export const files = {
-	/** Opens the platform document picker and returns its opaque native URI. */
-	async pick(accept = '*/*', opts?: { startingFolder?: string }): Promise<FileRef | null> {
-		const { extensions, mimeTypes } = pickerTypes(accept)
-		const result = await openFilePicker({
-			extensions,
-			mimeTypes,
-			multipleSelection: false,
-			permissions: { read: true, persistable: true },
-			startingFolder: opts?.startingFolder,
-		})
+async function pickFiles(
+	accept: string,
+	multiple: boolean,
+	opts?: { startingFolder?: string },
+): Promise<FileRef[]> {
+	const { extensions, mimeTypes } = pickerTypes(accept)
+	const result = await openFilePicker({
+		extensions,
+		mimeTypes,
+		multipleSelection: multiple,
+		permissions: { read: true, persistable: true },
+		startingFolder: opts?.startingFolder,
+	})
+
+	return (result.files ?? []).map((uri, index) => ({
+		name: androidDisplayName(uri, index === 0 ? result.android : undefined) ?? fallbackName(uri),
+		uri,
+	}))
+}
+
+// openInputStream accepts content:// and file:// schemes; bare paths go
+// through FileInputStream. Returns null when the resolver cannot open the URI.
+function openAndroidInput(uri: string): any {
+	const activity = Application.android?.foregroundActivity ?? Application.android?.startActivity
+	if (uri.startsWith('content://') || uri.startsWith('file://')) {
+		return activity?.getContentResolver()?.openInputStream(android.net.Uri.parse(uri))
+	}
+
+	return new java.io.FileInputStream(uri)
+}
+
+function readAndroidBytes(uri: string, opts?: FileReadBytesOptions): Uint8Array {
+	const input = openAndroidInput(uri)
+	if (!input) {
+		throw new Error(`Unable to open picked file: ${uri}`)
+	}
+
+	const out = new java.io.ByteArrayOutputStream()
+	const chunk = Array.create('byte', READ_CHUNK)
+	try {
+		let count: number
+		while ((count = input.read(chunk)) !== -1) {
+			throwIfAborted(opts?.signal)
+			out.write(chunk, 0, count)
+			if (opts?.maxBytes != null && out.size() > opts.maxBytes) {
+				throw fileTooLarge(uri, opts.maxBytes)
+			}
+		}
+	} finally {
+		input.close()
+	}
+
+	// ArrayBuffer.from is an NS Android runtime builtin that takes a
+	// java.nio.ByteBuffer — wrap the byte[] rather than marshalling per byte.
+	return new Uint8Array((ArrayBuffer as any).from(java.nio.ByteBuffer.wrap(out.toByteArray())))
+}
+
+// Picked iOS refs come from the picker's Import mode, so they are app-owned
+// copies — no security-scoped access needed. Single-pick URIs keep their
+// percent-encoding, so fall back to a decoded path when the literal misses.
+function iosFilePath(uri: string): string {
+	let p = uri.startsWith('file://') ? uri.slice('file://'.length) : uri
+	if (NSFileManager.defaultManager.fileExistsAtPath(p)) {
+		return p
+	}
+
+	try {
+		const decoded = decodeURIComponent(p)
+		if (decoded !== p && NSFileManager.defaultManager.fileExistsAtPath(decoded)) {
+			return decoded
+		}
+	} catch {}
+
+	return p
+}
+
+function readIosBytes(uri: string, opts?: FileReadBytesOptions): Uint8Array {
+	const p = iosFilePath(uri)
+	const handle = NSFileHandle.fileHandleForReadingAtPath(p)
+	if (!handle) {
+		throw new Error(`Unable to open picked file: ${uri}`)
+	}
+
+	const out = NSMutableData.new()
+	try {
+		while (true) {
+			throwIfAborted(opts?.signal)
+			const data = handle.readDataOfLength(READ_CHUNK)
+			if (!data || data.length === 0) {
+				break
+			}
+
+			out.appendData(data)
+			if (opts?.maxBytes != null && out.length > opts.maxBytes) {
+				throw fileTooLarge(uri, opts.maxBytes)
+			}
+		}
+	} finally {
+		handle.closeFile()
+	}
+
+	return new Uint8Array(interop.bufferFromData(out))
+}
+
+// ContentResolver.openOutputStream accepts content:// and file:// URIs; bare
+// paths go through FileOutputStream. The WritableByteChannel adapter writes
+// the full buffer per the OutputStream contract — no chunked short writes.
+function writeAndroidBytes(uri: string, bytes: Uint8Array): void {
+	const activity = Application.android?.foregroundActivity ?? Application.android?.startActivity
+	const out: java.io.OutputStream =
+		uri.startsWith('content://') || uri.startsWith('file://')
+			? activity?.getContentResolver()?.openOutputStream(android.net.Uri.parse(uri))
+			: new java.io.FileOutputStream(uri)
+
+	if (!out) {
+		throw new Error(`Unable to open destination: ${uri}`)
+	}
+
+	try {
+		java.nio.channels.Channels.newChannel(out).write(exactBuffer(bytes) as any)
+	} finally {
+		out.close()
+	}
+}
+
+function androidExport(
+	name: string,
+	bytes: Uint8Array,
+	opts?: FileExportOptions,
+): Promise<FileExportResult> {
+	const activity = Application.android?.foregroundActivity ?? Application.android?.startActivity
+	if (!activity) {
+		return Promise.resolve('unavailable')
+	}
+
+	const Intent = android.content.Intent
+	const intent = new Intent(Intent.ACTION_CREATE_DOCUMENT)
+	intent.addCategory(Intent.CATEGORY_OPENABLE)
+	intent.setType(opts?.mimeType ?? '*/*')
+	intent.putExtra(Intent.EXTRA_TITLE, name)
+	intent.addFlags(Intent.FLAG_GRANT_WRITE_URI_PERMISSION | Intent.FLAG_GRANT_READ_URI_PERMISSION)
+
+	return new Promise<FileExportResult>((resolve, reject) => {
+		const onEvent = (event: any) => {
+			if (event.requestCode !== ANDROID_EXPORT_REQUEST_CODE) {
+				return
+			}
+
+			Application.android.off(Application.android.activityResultEvent, onEvent)
+			const uri = event.intent?.getData?.()
+			if (event.resultCode !== android.app.Activity.RESULT_OK || !uri) {
+				resolve('cancelled')
+				return
+			}
+
+			try {
+				writeAndroidBytes(uri.toString(), bytes)
+				resolve('saved')
+			} catch (error) {
+				reject(error)
+			}
+		}
+
+		Application.android.on(Application.android.activityResultEvent, onEvent)
+		try {
+			activity.startActivityForResult(intent, ANDROID_EXPORT_REQUEST_CODE)
+		} catch (error) {
+			Application.android.off(Application.android.activityResultEvent, onEvent)
+			reject(error)
+		}
+	})
+}
+
+// One export UI at a time: Android listeners share the activity-result event,
+// and the iOS picker delegate below is kept alive in this slot (the
+// controller's `delegate` property is weak). A second concurrent export would
+// corrupt the first, so `files.export` fails fast instead.
+let activeExport: { delegate?: any; controller?: any } | null = null
+
+// Per-call delegate — defined lazily because NSObject and the picker symbols
+// only exist on iOS, while this module also loads on Android.
+let IosExportDelegate: any = null
+
+function iosExportDelegateClass(): any {
+	if (IosExportDelegate) {
+		return IosExportDelegate
+	}
 
-		const uri = result.files?.[0]
+	IosExportDelegate = class extends NSObject {
+		static ObjCProtocols = [UIDocumentPickerDelegate]
+		finish: ((saved: boolean) => void) | null = null
 
-		if (!uri) {
-			return null
+		documentPickerDidPickDocumentAtURL(controller: any, _url: any): void {
+			this.settle(controller, true)
 		}
+		documentPickerDidPickDocumentsAtURLs(controller: any, urls: any): void {
+			this.settle(controller, urls.count > 0)
+		}
+		documentPickerWasCancelled(controller: any): void {
+			this.settle(controller, false)
+		}
+		private settle(controller: any, saved: boolean): void {
+			const finish = this.finish
+			this.finish = null
+			controller.delegate = null
+			finish?.(saved)
+		}
+	}
+
+	return IosExportDelegate
+}
+
+function iosVisibleViewController(): any {
+	const app = UIApplication.sharedApplication
+	const keyWindow = app.keyWindow || (app.windows.count > 0 && app.windows[0])
+	// Utils.ios is only populated on iOS — typed as an empty bag elsewhere.
+	const getVisible = (Utils.ios as any)?.getVisibleViewController
+	return keyWindow && typeof getVisible === 'function'
+		? getVisible(keyWindow.rootViewController)
+		: null
+}
+
+// Own export picker rather than the upstream plugin's saveFile: that helper
+// runs an async promise executor (a failed temp write or a missing visible
+// controller leaves the promise unsettled) and holds the picker delegate in
+// one weak module slot, so overlapping calls drop the earlier request.
+async function iosExport(
+	name: string,
+	bytes: Uint8Array,
+	slot: { delegate?: any; controller?: any },
+): Promise<FileExportResult> {
+	const tempPath = path.join(knownFolders.temp().path, name)
+	const staged = NSData.dataWithBytesLength(bytes as any, bytes.byteLength).writeToFileAtomically(
+		tempPath,
+		true,
+	)
 
-		const name = androidDisplayName(uri, result.android) ?? fallbackName(uri)
-		return { name, uri }
+	const removeTemp = () => {
+		try {
+			File.fromPath(tempPath).removeSync()
+		} catch {}
+	}
+
+	if (!staged) {
+		throw new Error(`Failed to stage export file: ${name}`)
+	}
+
+	const visibleVC = iosVisibleViewController()
+	if (!visibleVC) {
+		removeTemp()
+		throw new Error('No visible view controller to present the export picker')
+	}
+
+	return new Promise<FileExportResult>((resolve, reject) => {
+		try {
+			const controller = UIDocumentPickerViewController.alloc().initForExportingURLsAsCopy(
+				[NSURL.fileURLWithPath(tempPath)] as any,
+				true,
+			)
+
+			const delegate = iosExportDelegateClass().new()
+			// `saved` only after the system commits the export-as-copy to the
+			// chosen destination; dismissal settles as 'cancelled'.
+			delegate.finish = (saved: boolean) => {
+				removeTemp()
+				resolve(saved ? 'saved' : 'cancelled')
+			}
+
+			slot.delegate = delegate
+			slot.controller = controller
+			controller.delegate = delegate
+			controller.shouldShowFileExtensions = true
+			visibleVC.presentViewControllerAnimatedCompletion(controller, true, null)
+		} catch (error) {
+			removeTemp()
+			reject(error)
+		}
+	})
+}
+
+export const files: Files = {
+	async pickMultiple(accept = '*/*', opts?: { startingFolder?: string }): Promise<FileRef[]> {
+		return pickFiles(accept, true, opts)
+	},
+	async pick(accept = '*/*', opts?: { startingFolder?: string }): Promise<FileRef | null> {
+		return (await pickFiles(accept, false, opts))[0] ?? null
 	},
 	async readText(ref: FileRef): Promise<string> {
 		if (ref.uri.startsWith('content://')) {
 			return readContentUri(ref.uri)
 		}
 
-		return File.fromPath(ref.uri).readText()
+		return File.fromPath(Application.android ? ref.uri : iosFilePath(ref.uri)).readText()
+	},
+	async readBytes(ref: FileRef, opts?: FileReadBytesOptions): Promise<Uint8Array> {
+		throwIfAborted(opts?.signal)
+		return Application.android ? readAndroidBytes(ref.uri, opts) : readIosBytes(ref.uri, opts)
 	},
 	async writeText(name: string, text: string): Promise<FileRef> {
+		assertSafeFileName(name)
 		const p = path.join(docs().path, name)
 		const f = File.fromPath(p)
 		f.writeTextSync(text)
 		return { name, uri: p }
 	},
+	async writeBytes(name: string, bytes: Uint8Array): Promise<FileRef> {
+		assertSafeFileName(name)
+		const p = path.join(docs().path, name)
+		if (Application.android) {
+			writeAndroidBytes(p, bytes)
+		} else {
+			// FileSystemAccess.writeBufferSync drops the writeToFileAtomically
+			// result and swallows errors without an onError callback, so a
+			// failed write would resolve with a ref to a missing file. Check
+			// the BOOL — it is the platform's overwrite confirmation.
+			const written = NSData.dataWithBytesLength(
+				bytes as any,
+				bytes.byteLength,
+			).writeToFileAtomically(p, true)
+
+			if (!written) {
+				throw new Error(`Failed to write file: ${p}`)
+			}
+		}
+
+		return { name, uri: p }
+	},
+	async export(
+		name: string,
+		bytes: Uint8Array,
+		opts?: FileExportOptions,
+	): Promise<FileExportResult> {
+		assertSafeFileName(name)
+		if (activeExport) {
+			throw exportBusy()
+		}
+
+		const slot: { delegate?: any; controller?: any } = {}
+		activeExport = slot
+		try {
+			return Application.android
+				? await androidExport(name, bytes, opts)
+				: await iosExport(name, bytes, slot)
+		} finally {
+			if (activeExport === slot) {
+				activeExport = null
+			}
+		}
+	},
 	release(ref: FileRef): void {
 		const cachePrefix = knownFolders.temp().path + '/'
 		if (!ref.uri.startsWith(cachePrefix)) {

package/src/files.web.test.ts

@@ -0,0 +1,117 @@
+// @vitest-environment jsdom
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { files } from './files.web'
+
+beforeEach(() => {
+	let counter = 0
+	vi.stubGlobal('URL', {
+		...URL,
+		createObjectURL: (_blob: Blob) => `blob:mock/${counter++}`,
+		revokeObjectURL: vi.fn(),
+	})
+})
+
+afterEach(() => {
+	vi.unstubAllGlobals()
+	vi.restoreAllMocks()
+	delete (window as any).showSaveFilePicker
+})
+
+describe('files.writeBytes (web)', () => {
+	it('starts a download and returns a readable ref', async () => {
+		const ref = await files.writeBytes('report.bin', new Uint8Array([1, 2, 3, 255]))
+		expect(ref.name).toBe('report.bin')
+		expect(ref.uri).toMatch(/^blob:/)
+
+		const back = await files.readBytes(ref)
+		expect([...back]).toEqual([1, 2, 3, 255])
+	})
+
+	it('rejects path-traversal names', async () => {
+		await expect(files.writeBytes('../escape.bin', new Uint8Array(1))).rejects.toThrow(
+			/Unsafe file name/,
+		)
+	})
+})
+
+describe('files.readBytes (web)', () => {
+	it('enforces maxBytes without returning truncated data', async () => {
+		const ref = await files.writeBytes('big.bin', new Uint8Array(1024))
+		await expect(files.readBytes(ref, { maxBytes: 512 })).rejects.toThrow(/exceeds/)
+	})
+
+	it('rejects on an aborted signal', async () => {
+		const ref = await files.writeBytes('a.bin', new Uint8Array([1]))
+		const controller = new AbortController()
+		controller.abort()
+		await expect(files.readBytes(ref, { signal: controller.signal })).rejects.toThrowError(
+			expect.objectContaining({ name: 'AbortError' }),
+		)
+	})
+
+	it('rejects when the signal aborts during blob.arrayBuffer()', async () => {
+		const controller = new AbortController()
+		vi.spyOn(Blob.prototype, 'arrayBuffer').mockImplementation(async () => {
+			controller.abort()
+			return new Uint8Array([1]).buffer
+		})
+
+		const ref = await files.writeBytes('a.bin', new Uint8Array([1]))
+		await expect(files.readBytes(ref, { signal: controller.signal })).rejects.toThrowError(
+			expect.objectContaining({ name: 'AbortError' }),
+		)
+	})
+
+	it('reads foreign URLs through fetch with the cap applied', async () => {
+		const body = new Uint8Array([1, 2, 3, 4])
+		vi.stubGlobal(
+			'fetch',
+			vi.fn(async () => new Response(body)),
+		)
+
+		const back = await files.readBytes({ name: 'remote.bin', uri: 'https://x/remote.bin' })
+		expect([...back]).toEqual([1, 2, 3, 4])
+		expect(fetch).toHaveBeenCalledWith('https://x/remote.bin', { signal: undefined })
+
+		await expect(
+			files.readBytes({ name: 'remote.bin', uri: 'https://x/remote.bin' }, { maxBytes: 2 }),
+		).rejects.toThrow(/exceeds/)
+	})
+
+	it('revokes the object URL on release', async () => {
+		const ref = await files.writeBytes('gone.bin', new Uint8Array([1]))
+		files.release(ref)
+		expect(URL.revokeObjectURL).toHaveBeenCalledWith(ref.uri)
+	})
+})
+
+describe('files.export (web)', () => {
+	it('returns unavailable without the File System Access API', async () => {
+		expect(await files.export('a.bin', new Uint8Array([1]))).toBe('unavailable')
+	})
+
+	it('writes bytes through a save picker and reports saved', async () => {
+		const write = vi.fn()
+		const close = vi.fn(async () => {})
+		const showSaveFilePicker = vi.fn(async () => ({
+			createWritable: async () => ({ write, close }),
+		}))
+
+		;(window as any).showSaveFilePicker = showSaveFilePicker
+
+		const result = await files.export('dump.bin', new Uint8Array([7, 8]))
+		expect(result).toBe('saved')
+		expect(write).toHaveBeenCalledWith(new Uint8Array([7, 8]))
+		expect(close).toHaveBeenCalled()
+	})
+
+	it('maps picker dismissal to cancelled', async () => {
+		const showSaveFilePicker = vi.fn(async () => {
+			throw new DOMException('dismissed', 'AbortError')
+		})
+
+		;(window as any).showSaveFilePicker = showSaveFilePicker
+
+		expect(await files.export('dump.bin', new Uint8Array([7]))).toBe('cancelled')
+	})
+})