From 5ee4b74636a6eebdfe6d1ee84555983682bd40f0 Mon Sep 17 00:00:00 2001 From: Gregor MacLennan Date: Mon, 10 Jul 2023 22:14:48 +0100 Subject: [PATCH] initial commit --- README.md | 21 +++ package-lock.json | 32 +++++ package.json | 20 +++ tsconfig.json | 11 ++ vendor/b4a.d.ts | 4 + vendor/hypercore.d.ts | 200 ++++++++++++++++++++++++++ vendor/random-access-file.d.ts | 33 +++++ vendor/random-access-memory.d.ts | 18 +++ vendor/random-access-storage.d.ts | 224 ++++++++++++++++++++++++++++++ 9 files changed, 563 insertions(+) create mode 100644 README.md create mode 100644 package-lock.json create mode 100644 package.json create mode 100644 tsconfig.json create mode 100644 vendor/b4a.d.ts create mode 100644 vendor/hypercore.d.ts create mode 100644 vendor/random-access-file.d.ts create mode 100644 vendor/random-access-memory.d.ts create mode 100644 vendor/random-access-storage.d.ts diff --git a/README.md b/README.md new file mode 100644 index 0000000..3c5841c --- /dev/null +++ b/README.md @@ -0,0 +1,21 @@ +## @digidem/types + +Typescript type definitions for untyped modules, for internal use prior to +publishing on DefinitelyTyped + +## Usage + +```sh +npm install @digidem/types +``` + +Then edit `tsconfig.json` to point `typeRoots` to +`node_modules/@digidem/types/vendor` e.g. + +```json +{ + "compilerOptions": { + "typeRoots": ["node_modules/@digidem/types/vendor", "node_modules/@types"] + } +} +``` diff --git a/package-lock.json b/package-lock.json new file mode 100644 index 0000000..b5e1c5e --- /dev/null +++ b/package-lock.json @@ -0,0 +1,32 @@ +{ + "name": "@digidem/types", + "version": "1.0.0", + "lockfileVersion": 1, + "requires": true, + "dependencies": { + "@types/node": { + "version": "18.16.19", + "resolved": "https://registry.npmjs.org/@types/node/-/node-18.16.19.tgz", + "integrity": "sha512-IXl7o+R9iti9eBW4Wg2hx1xQDig183jj7YLn8F7udNceyfkbn1ZxmzZXuak20gR40D7pIkIY1kYGx5VIGbaHKA==" + }, + "@types/streamx": { + "version": "2.9.1", + "resolved": "https://registry.npmjs.org/@types/streamx/-/streamx-2.9.1.tgz", + "integrity": "sha512-9bywzhouyedmci7WCIPFwJ8zASDnxt2gaVUy52X0p0Tt085IJSAEP0L6j4SSNeDMSLzpYu6cPz0GrJZ7kPJ6Bg==", + "requires": { + "@types/node": "*" + } + }, + "tiny-typed-emitter": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/tiny-typed-emitter/-/tiny-typed-emitter-2.1.0.tgz", + "integrity": "sha512-qVtvMxeXbVej0cQWKqVSSAHmKZEHAvxdF8HEUBFWts8h+xEo5m/lEiPakuyZ3BnCBjOD8i24kzNOiOLLgsSxhA==" + }, + "typescript": { + "version": "5.1.6", + "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.1.6.tgz", + "integrity": "sha512-zaWCozRZ6DLEWAWFrVDz1H6FVXzUSfTy5FUMWsQlU8Ym5JP9eO4xkTIROFCQvhQf61z6O/G6ugw3SgAnvvm+HA==", + "dev": true + } + } +} diff --git a/package.json b/package.json new file mode 100644 index 0000000..bbb616e --- /dev/null +++ b/package.json @@ -0,0 +1,20 @@ +{ + "name": "@digidem/types", + "version": "1.0.0", + "description": "Typescript type definitions for untyped modules used by Digidem, prior to DefinitelyTyped publishing", + "main": "index.js", + "scripts": { + "test": "echo \"Error: no test specified\" && exit 1" + }, + "keywords": [], + "author": "", + "license": "ISC", + "devDependencies": { + "typescript": "^5.1.6" + }, + "dependencies": { + "@types/node": "^18.16.19", + "@types/streamx": "^2.9.1", + "tiny-typed-emitter": "^2.1.0" + } +} diff --git a/tsconfig.json b/tsconfig.json new file mode 100644 index 0000000..7310b21 --- /dev/null +++ b/tsconfig.json @@ -0,0 +1,11 @@ +{ + "compilerOptions": { + "target": "es2021", + "lib": ["es2021", "dom"], + "strict": true, + "esModuleInterop": true, + "module": "CommonJS", + "moduleResolution": "Node", + "typeRoots": ["vendor", "node_modules/@types"] + } +} diff --git a/vendor/b4a.d.ts b/vendor/b4a.d.ts new file mode 100644 index 0000000..0595423 --- /dev/null +++ b/vendor/b4a.d.ts @@ -0,0 +1,4 @@ +import { Buffer } from 'node:buffer' +interface b4a extends Buffer {} +declare var b4a: BufferConstructor +export = b4a diff --git a/vendor/hypercore.d.ts b/vendor/hypercore.d.ts new file mode 100644 index 0000000..5f557d5 --- /dev/null +++ b/vendor/hypercore.d.ts @@ -0,0 +1,200 @@ +import { TypedEmitter } from 'tiny-typed-emitter' +import RandomAccessStorage from 'random-access-storage' +import RandomAccessMemory from 'random-access-memory' +import RandomAccessFile from 'random-access-file' +import { type Duplex, type Readable } from 'streamx' + +interface RemoteBitfield { + get(index: number): boolean +} + +interface HypercoreExtension { + name: string + encoding: any + send(data: Buffer | Uint8Array, peer: any): void + broadcast(data: Buffer | Uint8Array): void + destroy(): void +} + +interface PeerOnRangeOptions { + drop?: boolean + start: number + length: number +} + +interface HypercorePeer { + remotePublicKey: Buffer + remoteBitfield: RemoteBitfield + onrange(options: PeerOnRangeOptions): void +} + +interface DownloadingRange { + destroy(): void + done(): Promise +} + +type HypercoreStorageName = 'oplog' | 'tree' | 'bitfield' | 'data' + +interface HypercoreInfo { + key: Buffer + discoveryKey: Buffer + length: number + contiguousLength: number + byteLength: number + fork: number + padding: number + storage: { + oplog: number + tree: number + blocks: number + bitfield: number + } +} + +interface KeyPair { + publicKey: Buffer + secretKey: Buffer +} + +declare namespace Hypercore { + interface HypercoreEvents { + 'peer-add'(peer: any): void + 'peer-remove'(peer: any): void + download(index: number, byteLength: number, from: any): void + ready(): void + close(allClosed: boolean): void + upload(index: number, byteLength: number, to: any): void + truncate(index: number, fork: number): void + append(): void + } + + type ValueEncoding = 'json' | 'utf-8' | 'binary' + + interface HypercoreOptions< + TValueEncoding extends Hypercore.ValueEncoding = 'binary' + > { + createIfMissing?: boolean // create a new Hypercore key pair if none was present in storage + overwrite?: boolean // overwrite any old Hypercore that might already exist + valueEncoding?: TValueEncoding // defaults to binary + encodeBatch?(batch: any[]): void // optionally apply an encoding to complete batches + keyPair?: KeyPair // optionally pass the public key and secret key as a key pair + encryptionKey?: Buffer // optionally pass an encryption key to enable block encryption + onwait?: () => {} // hook that is called if gets are waiting for download + timeout?: number // wait at max some milliseconds (0 means no timeout) + writable?: boolean // disable appends and truncates + } + + interface HypercoreGetOptions< + TValueEncoding extends Hypercore.ValueEncoding = 'binary' + > { + wait?: boolean // wait for block to be downloaded + onwait?(): void // hook that is called if the get is waiting for download + timeout?: number // wait at max some milliseconds (0 means no timeout) + valueEncoding?: TValueEncoding // defaults to the core's valueEncoding + decrypt?: boolean // automatically decrypts the block if encrypted + } + + type HypercoreStorage = + | string + | ((name: HypercoreStorageName) => RandomAccessStorage) +} + +declare class Hypercore< + TValueEncoding extends Hypercore.ValueEncoding = 'binary' +> extends TypedEmitter { + readonly writable: boolean + readonly readable: boolean + readonly id: null | string + readonly key: null | Buffer + readonly peers: any[] + readonly keyPair: null | KeyPair + readonly discoveryKey: null | Buffer + readonly encryptionKey: null | Buffer + readonly length: number + readonly contiguousLength: number + readonly fork: number + readonly padding: number + + constructor(storage: Hypercore.HypercoreStorage) + constructor( + storage: Hypercore.HypercoreStorage, + key: Buffer | string, + options?: Hypercore.HypercoreOptions + ) + constructor( + storage: Hypercore.HypercoreStorage, + options?: Hypercore.HypercoreOptions + ) + + /** Append a block of data (or an array of blocks) to the core. Returns the + * new length and byte length of the core. */ + append(block: any): Promise<{ length: number; byteLength: number }> + /** Get a block of data. If the data is not available locally this method will + * prioritize and wait for the data to be downloaded. */ + get( + index: number, + options?: Hypercore.HypercoreGetOptions + ): Promise< + | null + | (TGetValueEncoding extends 'binary' + ? Buffer + : TGetValueEncoding extends 'utf-8' + ? string + : TGetValueEncoding extends 'json' + ? any + : unknown) + > + /** Check if the core has all blocks between start and end. */ + has(index: number): boolean + has(start: number, end: number): boolean + update(opts?: { wait?: boolean }): Promise + seek( + byteOffset: number, + options?: { + wait: true // wait for data to be downloaded + timeout: 0 // wait at max some milliseconds (0 means no timeout) + } + ): Promise<[index: number, relativeOffset: number]> + createReadStream(options?: { + start: number + end: number + live: boolean + snapshot: boolean // auto set end to core.length on open or update it on every read + }): Readable + createByteStream(options?: { + byteOffset: number + byteLength: number + prefetch: number + }): Readable + clear(start: number, options?: { diff: boolean }): Promise + clear( + start: number, + end: number, + options?: { diff: boolean } + ): Promise + truncate(newLength: number, forkId?: number): Promise + purge(): Promise + treeHash(length?: number): Promise + info(opts?: { storage?: false }): Promise> + info(opts: { storage: true }): Promise + download(range?: { + start?: number + end?: number + blocks?: number[] + linear?: boolean + }): DownloadingRange + session(options?: Hypercore.HypercoreOptions): Hypercore + close(): Promise + ready(): Promise + registerExtension( + name: string, + handlers?: { encoding?: any; onmessage?: (buf: Buffer, peer: any) => void } + ): HypercoreExtension + replicate( + isInitiatorOrReplicationStream: boolean | Duplex, + opts?: { keepAlive?: boolean } + ): Duplex + findingPeers(): () => void +} + +export = Hypercore diff --git a/vendor/random-access-file.d.ts b/vendor/random-access-file.d.ts new file mode 100644 index 0000000..6de6469 --- /dev/null +++ b/vendor/random-access-file.d.ts @@ -0,0 +1,33 @@ +import RandomAccessStorage from 'random-access-storage' + +declare namespace RandomAccessFile { + interface RAFOptions { + /** truncate the file before reading / writing */ + truncate?: boolean + /** truncate the file to this size first */ + size?: number + /** should the file be opened as readable? */ + readable?: boolean + /** should the file be opened as writable? */ + writable?: boolean + /** lock the file */ + lock?: boolean + /** mark the file as sparse */ + sparse?: boolean + /** UNDOCUMENTED: directory for creating files */ + directory?: string + /** UNDOCUMENTED: file descriptor pool */ + pool?: Pool + } +} + +declare class Pool { + constructor(maxSize: number) +} + +declare class RandomAccessFile extends RandomAccessStorage { + constructor(filename: string, opts?: RandomAccessFile.RAFOptions) + static createPool(maxSize: number): Pool +} + +export = RandomAccessFile diff --git a/vendor/random-access-memory.d.ts b/vendor/random-access-memory.d.ts new file mode 100644 index 0000000..e1fad65 --- /dev/null +++ b/vendor/random-access-memory.d.ts @@ -0,0 +1,18 @@ +import RandomAccessStorage from 'random-access-storage' + +declare namespace RandomAccessMemory { + interface RAMOptions { + length?: number + pageSize?: number + buffer?: Buffer + } +} + +declare class RandomAccessMemory extends RandomAccessStorage { + constructor(options?: RandomAccessMemory.RAMOptions) + toBuffer(): Buffer + clone(): RandomAccessMemory + static reusable(): (name: string) => RandomAccessMemory +} + +export = RandomAccessMemory diff --git a/vendor/random-access-storage.d.ts b/vendor/random-access-storage.d.ts new file mode 100644 index 0000000..1445390 --- /dev/null +++ b/vendor/random-access-storage.d.ts @@ -0,0 +1,224 @@ +import { TypedEmitter } from 'tiny-typed-emitter' + +interface Events { + /** emitted when the storage is fully open */ + open(): void + /** emitted when the storage is fully closed */ + close(): void + /** emitted when the storage is fully unlinked */ + unlink(): void + /** emitted when the storage is fully suspended */ + suspend(): void + /** emitted when the storage comes out of suspension */ + unsuspend(): void +} + +interface Callback { + (err: Error | null, value: T): void +} + +declare namespace RandomAccessStorage { + interface RASOptions { + /** always create storage on first open */ + createAlways?: boolean + /** sets ._open */ + open?: typeof RandomAccessStorage.prototype.open + /** sets ._read */ + read?: typeof RandomAccessStorage.prototype.read + /** sets ._write */ + write?: typeof RandomAccessStorage.prototype.write + /** sets ._del */ + del?: typeof RandomAccessStorage.prototype.del + /** sets ._truncate */ + truncate?: typeof RandomAccessStorage.prototype.truncate + /** sets ._stat */ + stat?: typeof RandomAccessStorage.prototype.stat + /** sets ._suspend */ + suspend?: typeof RandomAccessStorage.prototype.suspend + /** sets ._close */ + close?: typeof RandomAccessStorage.prototype.close + /** sets ._unlink */ + unlink?: typeof RandomAccessStorage.prototype.unlink + } +} + +declare class RandomAccessStorage< + TStatObject extends {} = { size: number } +> extends TypedEmitter { + /** True if the storage implements ._read. */ + readable: boolean + /** True if the storage implements ._read. */ + writable: boolean + /** True if the storage implements ._read. */ + deletable: boolean + /** True if the storage implements ._read. */ + truncatable: boolean + /** True if the storage implements ._read. */ + statable: boolean + /** True if the storage has been fully opened. */ + opened: boolean + /** True if the storage has been fully close. */ + closed: boolean + /** True if the storage has been fully unlinked. */ + unlinked: boolean + /** True if the storage is currently being written to. */ + writing: boolean + + constructor(options?: RandomAccessStorage.RASOptions) + + /** + * Explicitly open the storage. If you do not call this yourself, it will + * automatically called before any read/write/del/stat operation. + * + * It is safe to call this more than once. + * + * Triggers one call to _open if you implement that. + */ + open(callback: Callback): void + + /** + * Implement storage open. + * + * req.create is true if the storage should be created. + * Call req.callback when it is fully opened. + * + * @param req + */ + _open(req: { create: boolean; callback: Callback }): void + + /** + * Read the specified bytes from the storage at the specified byte offset. + * Calls the callback with a (err, buffer). + */ + read(offset: number, size: number, callback: Callback): void + + /** + * Implement storage read. + * + * Note that this is guaranteed to run after the storage has been opened and + * not after it has been closed. + * + * @param req.offset the byte offset you should read at. + * @param req.size the amount of bytes you should read. + * @param req.callback when the read is completed. + */ + _read(req: { offset: number; size: number; callback: Callback }): void + + /** + * Write the specified buffer to the specified byte offset. Optionally pass a + * callback that is called with (err) when the write has completed. + */ + write(offset: number, buffer: Buffer, callback?: Callback): void + + /** + * Implement storage write. + * + * Note that this is guaranteed to run after the storage has been opened and + * not after it has been closed. + * + * @param req.offset the byte offset you should write at. + * @param req.data the buffer you should write. + * @param req.callback call when write is compelted + */ + _write(req: { offset: number; data: Buffer; callback: Callback }): void + + /** + * Delete the specified amount of bytes at the specified offset. Optionally + * pass a callback that is called with (err) when the delete has completed. + */ + del(offset: number, size: number, callback?: Callback): void + + /** + * Implement storage delete. + * + * Note that this is guaranteed to run after the storage has been opened and + * not after it has been closed. + * + * @param req.offset the byte offset you should delete at. + * @param req.size the amount of bytes you should delete. + * @param req.callback when the delete is completed. + */ + _del(req: { offset: number; size: number; callback: Callback }): void + + /** + * Truncate the storage at the specified offset. Optionally pass a callback + * that is called with (err) when the truncate has completed. + */ + truncate(offset: number, callback?: Callback): void + + /** + * Implement storage truncate. Defaults to storage._del(req). + * + * Note that this is guaranteed to run after the storage has been opened and + * not after it has been closed. + * + * @param req.offset the byte offset to truncate at. + */ + _truncate(req: { offset: number }): void + + /** + * Stat the storage. Should return an object with useful information about the + * underlying storage + */ + stat(callback: Callback): void + + /** + * Implement storage stat. + * + * Call req.callback(err, statObject) when the stat has completed. + * + * Note that this is guaranteed to run after the storage has been opened and + * not after it has been closed. + * + */ + _stat(req: { callback: Callback }): void + + /** + * Suspend (temporarily close) the storage instance. + */ + suspend(callback?: Callback): void + + /** + * Implement storage suspend. Defaults to calling _close. + * + * Optionally implement this to add a way for your storage instance to + * temporarily free resources. + * + * Call req.callback(err) when the storage has been fully suspended. + * + */ + _suspend(req: { callback: Callback }): void + + /** + * Close the storage instance. + */ + close(callback?: Callback): void + + /** + * Implement storage close + * + * Call req.callback(err) when the storage is fully closed. + * + * Note this is guaranteed to run after all pending read/write/stat/del + * operations has finished and no methods will run after. + * + */ + _close(req: { callback: Callback }): void + + /** + * Unlink the storage instance, removing all underlying data. + */ + unlink(callback?: Callback): void + + /** + * Implement storage unlink. + * + * Call req.callback(err) when the storage has been fully unlinked. + * + * Note this is guaranteed to run after .close() has been called and no + * methods will be run after. + */ + _unlink(req: { callback: Callback }): void +} + +export = RandomAccessStorage