From aeb2eae343b9fc2d85a4435eeb6a1a22ce9cd025 Mon Sep 17 00:00:00 2001 From: Luis Blanco Date: Mon, 9 Oct 2023 22:15:37 +0400 Subject: [PATCH] Adjust TS comments --- .github/workflows/cpplint.yml | 42 ++++ index.d.ts | 400 ++++++++++++++++++++++------------ package-lock.json | 11 +- package.json | 11 +- 4 files changed, 320 insertions(+), 144 deletions(-) create mode 100644 .github/workflows/cpplint.yml diff --git a/.github/workflows/cpplint.yml b/.github/workflows/cpplint.yml new file mode 100644 index 0000000..77f5de2 --- /dev/null +++ b/.github/workflows/cpplint.yml @@ -0,0 +1,42 @@ +name: Cpplint +defaults: + run: + shell: bash + +on: + push: + branches: + - master + pull_request: + branches: + - master + +jobs: + eslint: + name: Cpplint + runs-on: ubuntu-20.04 + + steps: + + - name: Fetch Repository + uses: actions/checkout@v3 + with: + persist-credentials: false + + - name: Install Node.js + uses: actions/setup-node@v3 + with: + node-version: 18.16.0 + cache: 'npm' + + - name: Install Modules + run: npm ci + + - name: Install Python + - uses: actions/setup-python@v1 + + - name: Install Cpplint + run: pip install cpplint + + - name: Run Cpplint + run: cpplint --recursive . diff --git a/index.d.ts b/index.d.ts index ac3d077..62beffa 100644 --- a/index.d.ts +++ b/index.d.ts @@ -1,22 +1,26 @@ -import type { Stats } from 'node:fs'; -import type { Writable } from 'node:stream'; - - declare module "addon-tools-raub" { + type Stats = import('node:fs').Stats; + type Writable = import('node:stream').Writable; + type Readable = import('node:stream').Readable; + type WritableOptions = import('node:stream').WritableOptions; + /** - * Get the internal paths for an addon - * Returns a set of platform dependent paths depending on the input dir - */ + * Get the internal paths for an addon + * + * Returns a set of platform dependent paths depending on the input dir + */ export const getPaths: (dir: string) => Readonly<{ /** - * Path to binaries - * Platform binary directory absolute path for this `dir` - */ + * Path to binaries + * + * Platform binary directory absolute path for this `dir` + */ bin: string; /** - * Path to include - * Include directory for this `dir` - */ + * Path to include + * + * Include directory for this `dir` + */ include: string; }>; @@ -24,214 +28,334 @@ declare module "addon-tools-raub" { type TPlatformDir = `bin-${TPlatformName}`; /** - * Get the platform-specific binary directory name - */ + * Get the platform-specific binary directory name + */ export const getBin: () => TPlatformDir; /** - * Get the platform identifier - */ + * Get the platform identifier + */ export const getPlatform: () => TPlatformName; /** - * Get the include directories for **binding.gyp** - * Both 'addon-tools-raub' and 'node-addon-api' include paths. - * In binding.gyp: `' string; /** - * Install binaries - * Downloads and unpacks the platform specific binary for the calling package. - * To use it, create a new script for your package, which may as well be named - * **install.js**, with the following content: - * - * ``` - * 'use strict'; - * const { install } = require('addon-tools-raub'); - * const prefix = 'https://github.com/USER/ADDON-NAME/releases/download'; - * const tag = '1.0.0'; - * install(`${prefix}/${tag}`); - * ``` - * - * * `prefix` - the constant base part of the download url. - * * `tag` - the version-dependent part of the url. - * - * ``` - * "scripts": { - * "postinstall": "node install" - * }, - * ``` - */ + * Install binaries + * + * Downloads and unpacks the platform specific binary for the calling package. + * To use it, create a new script for your package, which may as well be named + * **install.js**, with the following content: + * + * ``` + * 'use strict'; + * const { install } = require('addon-tools-raub'); + * const prefix = 'https://github.com/USER/ADDON-NAME/releases/download'; + * const tag = '1.0.0'; + * install(`${prefix}/${tag}`); + * ``` + * + * * `prefix` - the constant base part of the download url. + * * `tag` - the version-dependent part of the url. + * + * ``` + * "scripts": { + * "postinstall": "node install" + * }, + * ``` + */ export const install: (folder: string) => Promise; /** - * Copy binary - * Copies the addon binary from `src/build/Release` to the platform-specific folder. - * - * ``` - * "scripts": { - * * "build": "node-gyp rebuild && node -e \"require('addon-tools-raub').cpbin('ADDON')\"" - * }, - * ``` - * - * Here ADDON should be replaced with the name of your addon, without `.node` extension. - */ + * Copy binary + * + * Copies the addon binary from `src/build/Release` to the platform-specific folder. + * + * ``` + * "scripts": { + * * "build": "node-gyp rebuild && node -e \"require('addon-tools-raub').cpbin('ADDON')\"" + * }, + * ``` + * + * Here ADDON should be replaced with the name of your addon, without `.node` extension. + */ export const cpbin: (name: string) => Promise; /** - * Packs binaries into GZIP - * Example of `actionPack` usage in **Github Actions**: - * - * ``` - * - name: Pack Files - * id: pack-files - * run: node -e "require('addon-tools-raub').actionPack()" >> $GITHUB_OUTPUT - * - name: Store Binaries - * uses: softprops/action-gh-release@v1 - * with: - * files: ${{ steps.pack-files.outputs.pack }} - * ``` - */ + * Packs binaries into GZIP + * + * Example of `actionPack` usage in **Github Actions**: + * + * ``` + * - name: Pack Files + * id: pack-files + * run: node -e "require('addon-tools-raub').actionPack()" >> $GITHUB_OUTPUT + * - name: Store Binaries + * uses: softprops/action-gh-release@v1 + * with: + * files: ${{ steps.pack-files.outputs.pack }} + * ``` + */ export const actionPack: () => Promise; /** - * Download to memory - * Accepts an **URL**, and returns an in-memory file Buffer, - * when the file is loaded. Use for small files, as the whole - * file will be loaded into memory at once. - * - * ``` - * download(srcUrl).then(data => useData(data), err => emit('error', err)); - * ``` - * or - * ``` - * const data = await download(srcUrl); - * useData(data); - * ``` - */ + * Download to memory + * + * Accepts an **URL**, and returns an in-memory file Buffer, + * when the file is loaded. Use for small files, as the whole + * file will be loaded into memory at once. + * + * ``` + * download(srcUrl).then(data => useData(data), err => emit('error', err)); + * ``` + * or + * ``` + * const data = await download(srcUrl); + * useData(data); + * ``` + */ export const download: (url: string) => Promise; /** - * (async) Read a file - * Reads a whole file to string, NOT A Buffer - */ + * (async) Read a file + * + * Reads a whole file to string, NOT A Buffer + */ + type ComposeFnParam = (source: any) => void; /** - * WritableBuffer - * A [Writable](https://nodejs.org/api/stream.html#stream_writable_streams) - * stream buffer, that is stored in-memory and can be fully - * obtained when writing was finished. It is equivalent to stream-writing - * a temporary file and then reading it into a `Buffer`. - */ - export class WritableBuffer extends Writable { + * WritableBuffer + * + * A [Writable](https://nodejs.org/api/stream.html#stream_writable_streams) + * stream buffer, that is stored in-memory and can be fully + * obtained when writing was finished. It is equivalent to stream-writing + * a temporary file and then reading it into a `Buffer`. + */ + export class WritableBuffer implements Writable { constructor(); /** - * Get the downloaded data - * Use `stream.get()` to obtain the data when writing was finished - */ + * Get the downloaded data + * Use `stream.get()` to obtain the data when writing was finished + */ get(): Buffer; + + // ----------- implements Writable + + readonly writable: boolean; + readonly writableEnded: boolean; + readonly writableFinished: boolean; + readonly writableHighWaterMark: number; + readonly writableLength: number; + readonly writableObjectMode: boolean; + readonly writableCorked: number; + destroyed: boolean; + readonly closed: boolean; + readonly errored: Error | null; + readonly writableNeedDrain: boolean; + constructor(opts?: WritableOptions); + _write(chunk: any, encoding: BufferEncoding, callback: (error?: Error | null) => void): void; + _writev?( + chunks: Array<{ + chunk: any; + encoding: BufferEncoding; + }>, + callback: (error?: Error | null) => void, + ): void; + _construct?(callback: (error?: Error | null) => void): void; + _destroy(error: Error | null, callback: (error?: Error | null) => void): void; + _final(callback: (error?: Error | null) => void): void; + write(chunk: any, callback?: (error: Error | null | undefined) => void): boolean; + write(chunk: any, encoding: BufferEncoding, callback?: (error: Error | null | undefined) => void): boolean; + setDefaultEncoding(encoding: BufferEncoding): this; + end(cb?: () => void): this; + end(chunk: any, cb?: () => void): this; + end(chunk: any, encoding: BufferEncoding, cb?: () => void): this; + cork(): void; + uncork(): void; + destroy(error?: Error): this; + addListener(event: "close", listener: () => void): this; + addListener(event: "drain", listener: () => void): this; + addListener(event: "error", listener: (err: Error) => void): this; + addListener(event: "finish", listener: () => void): this; + addListener(event: "pipe", listener: (src: Readable) => void): this; + addListener(event: "unpipe", listener: (src: Readable) => void): this; + addListener(event: string | symbol, listener: (...args: any[]) => void): this; + emit(event: "close"): boolean; + emit(event: "drain"): boolean; + emit(event: "error", err: Error): boolean; + emit(event: "finish"): boolean; + emit(event: "pipe", src: Readable): boolean; + emit(event: "unpipe", src: Readable): boolean; + emit(event: string | symbol, ...args: any[]): boolean; + on(event: "close", listener: () => void): this; + on(event: "drain", listener: () => void): this; + on(event: "error", listener: (err: Error) => void): this; + on(event: "finish", listener: () => void): this; + on(event: "pipe", listener: (src: Readable) => void): this; + on(event: "unpipe", listener: (src: Readable) => void): this; + on(event: string | symbol, listener: (...args: any[]) => void): this; + once(event: "close", listener: () => void): this; + once(event: "drain", listener: () => void): this; + once(event: "error", listener: (err: Error) => void): this; + once(event: "finish", listener: () => void): this; + once(event: "pipe", listener: (src: Readable) => void): this; + once(event: "unpipe", listener: (src: Readable) => void): this; + once(event: string | symbol, listener: (...args: any[]) => void): this; + prependListener(event: "close", listener: () => void): this; + prependListener(event: "drain", listener: () => void): this; + prependListener(event: "error", listener: (err: Error) => void): this; + prependListener(event: "finish", listener: () => void): this; + prependListener(event: "pipe", listener: (src: Readable) => void): this; + prependListener(event: "unpipe", listener: (src: Readable) => void): this; + prependListener(event: string | symbol, listener: (...args: any[]) => void): this; + prependOnceListener(event: "close", listener: () => void): this; + prependOnceListener(event: "drain", listener: () => void): this; + prependOnceListener(event: "error", listener: (err: Error) => void): this; + prependOnceListener(event: "finish", listener: () => void): this; + prependOnceListener(event: "pipe", listener: (src: Readable) => void): this; + prependOnceListener(event: "unpipe", listener: (src: Readable) => void): this; + prependOnceListener(event: string | symbol, listener: (...args: any[]) => void): this; + removeListener(event: "close", listener: () => void): this; + removeListener(event: "drain", listener: () => void): this; + removeListener(event: "error", listener: (err: Error) => void): this; + removeListener(event: "finish", listener: () => void): this; + removeListener(event: "pipe", listener: (src: Readable) => void): this; + removeListener(event: "unpipe", listener: (src: Readable) => void): this; + removeListener(event: string | symbol, listener: (...args: any[]) => void): this; + pipe( + destination: T, + options?: { + end?: boolean | undefined; + }, + ): T; + compose( + stream: T | ComposeFnParam | Iterable | AsyncIterable, + options?: { signal: AbortSignal }, + ): T; + off(eventName: string | symbol, listener: (...args: any[]) => void): this; + removeAllListeners(event?: string | symbol): this; + setMaxListeners(n: number): this; + getMaxListeners(): number; + listeners(eventName: string | symbol): Function[]; + rawListeners(eventName: string | symbol): Function[]; + emit(eventName: string | symbol, ...args: any[]): boolean; + listenerCount(eventName: string | symbol, listener?: Function): number; + eventNames(): Array; } export const read: (name: string) => Promise; /** - * (async) Write a file - */ + * (async) Write a file + */ export const write: (name: string, text: string) => Promise; /** - * (async) Copy a file - */ + * (async) Copy a file + */ export const copy: (src: string, dest: string) => Promise; /** - * (async) Check if a file/folder exists - */ + * (async) Check if a file/folder exists + */ export const exists: (name: string) => Promise; /** - * (async) Create an empty folder - */ + * (async) Create an empty folder + */ export const mkdir: (name: string) => Promise; /** - * (async) Get status on a file - */ + * (async) Get status on a file + */ export const stat: (name: string) => Promise; /** - * (async) Check if the path is a folder - */ + * (async) Check if the path is a folder + */ export const isDir: (name: string) => Promise; /** - * (async) Check if the path is a file - */ + * (async) Check if the path is a file + */ export const isFile: (name: string) => Promise; /** - * Cut the path one folder up - */ + * Cut the path one folder up + */ export const dirUp: (dir: string) => string; /** - * (async) Create a directory - * Like `mkdir -p`, makes sure a directory exists - */ + * (async) Create a directory + * + * Like `mkdir -p`, makes sure a directory exists + */ export const ensuredir: (dir: string) => Promise; /** - * (async) Copy a file - * Copy a file, `dest` folder is created if needed - */ + * (async) Copy a file + * + * Copy a file, `dest` folder is created if needed + */ export const copysafe: (src: string, dest: string) => Promise; /** - * (async) Read a directory - * Get file/folder names of the 1st level - */ + * (async) Read a directory + * + * Get file/folder names of the 1st level + */ export const readdir: (src: string, dest: string) => Promise>; /** - * (async) List subdirectories - * Get folder paths (concatenated with input) of the 1st level - */ + * (async) List subdirectories + * + * Get folder paths (concatenated with input) of the 1st level + */ export const subdirs: (name: string) => Promise>; /** - * (async) List nested files - * Get file paths (concatenated with input) of the 1st level - */ + * (async) List nested files + * + * Get file paths (concatenated with input) of the 1st level + */ export const subfiles: (name: string) => Promise>; /** - * (async) Get all nested files recursively - * Folder paths are omitted by default. - * Order is: shallow-to-deep, each subdirectory lists dirs-then-files. - */ + * (async) Get all nested files recursively + * + * Folder paths are omitted by default. + * Order is: shallow-to-deep, each subdirectory lists dirs-then-files. + */ export const traverse: (name: string, showDirs?: boolean) => Promise>; /** - * (async) Copy a directory - * Copy a folder with all the contained files - */ + * (async) Copy a directory + * + * Copy a folder with all the contained files + */ export const copyall: (src: string, dest: string) => Promise; /** - * (async) Remove a directory - * Like `rm -rf`, removes everything recursively - */ + * (async) Remove a directory + * + * Like `rm -rf`, removes everything recursively + */ export const rmdir: (name: string) => Promise; /** - * (async) Remove a file - * Must be a file, not a folder. Just `fs.unlink`. - */ + * (async) Remove a file + * + * Must be a file, not a folder. Just `fs.unlink`. + */ export const rm: (name: string) => Promise; } diff --git a/package-lock.json b/package-lock.json index 2c79325..3818d58 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,14 +1,15 @@ { "name": "addon-tools-raub", - "version": "7.3.0", + "version": "7.3.1", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "addon-tools-raub", - "version": "7.3.0", + "version": "7.3.1", "license": "MIT", "devDependencies": { + "@types/node": "^20.8.3", "eslint": "^8.51.0", "eslint-plugin-node": "^11.1.0", "node-addon-api": "^7.0.0", @@ -160,6 +161,12 @@ "node": ">= 8" } }, + "node_modules/@types/node": { + "version": "20.8.3", + "resolved": "https://registry.npmjs.org/@types/node/-/node-20.8.3.tgz", + "integrity": "sha512-jxiZQFpb+NlH5kjW49vXxvxTjeeqlbsnTAdBTKpzEdPs9itay7MscYXz3Fo9VYFEsfQ6LJFitHad3faerLAjCw==", + "dev": true + }, "node_modules/acorn": { "version": "8.10.0", "resolved": "https://registry.npmjs.org/acorn/-/acorn-8.10.0.tgz", diff --git a/package.json b/package.json index 355188e..ad06097 100644 --- a/package.json +++ b/package.json @@ -1,7 +1,7 @@ { "author": "Luis Blanco ", "name": "addon-tools-raub", - "version": "7.3.0", + "version": "7.3.1", "description": "Helpers for Node.js addons and dependency packages", "license": "MIT", "main": "index.js", @@ -34,7 +34,7 @@ }, "scripts": { "eslint": "eslint .", - "test": "node --test --watch", + "test": "node --test --watch .", "test-ci": "node --test", "build-test": "cd test-addon && node-gyp rebuild -j max --silent && cd .." }, @@ -46,11 +46,14 @@ "node-addon-api": "^7.0.0" }, "peerDependenciesMeta": { - "node-addon-api": { "optional": true } + "node-addon-api": { + "optional": true + } }, "devDependencies": { - "eslint-plugin-node": "^11.1.0", + "@types/node": "^20.8.3", "eslint": "^8.51.0", + "eslint-plugin-node": "^11.1.0", "node-addon-api": "^7.0.0", "typescript": "^5.2.2" }