From a2cdc737351b657266a417a68ba46259eaeeef05 Mon Sep 17 00:00:00 2001 From: alina sireneva Date: Sun, 28 Apr 2024 22:41:28 +0300 Subject: [PATCH 01/10] feat: initial deno support --- .config/eslint.cjs | 4 +- .github/workflows/test.yaml | 2 +- .npmrc | 1 + package.json | 2 +- packages/bun/src/platform.ts | 6 + packages/bun/src/worker.ts | 4 +- .../highlevel/methods/files/upload-file.ts | 3 +- .../core/src/highlevel/types/files/utils.ts | 21 ++- .../core/src/highlevel/worker/protocol.ts | 1 + .../src/storage/sqlite/repository/peers.ts | 3 +- packages/core/src/types/utils.ts | 2 + packages/core/src/utils/error-reporting.ts | 3 +- packages/deno/README.md | 25 +++ packages/deno/build.config.cjs | 1 + packages/deno/package.json | 30 ++++ packages/deno/src/client.ts | 144 ++++++++++++++++++ packages/deno/src/common-internals-web | 1 + packages/deno/src/index.ts | 9 ++ packages/deno/src/methods.ts | 2 + packages/deno/src/methods/download-file.ts | 39 +++++ packages/deno/src/platform.ts | 48 ++++++ packages/deno/src/sqlite/driver.ts | 38 +++++ packages/deno/src/sqlite/index.ts | 14 ++ packages/deno/src/sqlite/sqlite.test.ts | 31 ++++ packages/deno/src/utils.ts | 1 + packages/deno/src/utils/crypto.test.ts | 13 ++ packages/deno/src/utils/crypto.ts | 97 ++++++++++++ packages/deno/src/utils/exit-hook.ts | 21 +++ packages/deno/src/utils/normalize-file.ts | 50 ++++++ packages/deno/src/utils/tcp.ts | 135 ++++++++++++++++ packages/deno/src/worker.ts | 71 +++++++++ packages/deno/tsconfig.json | 16 ++ packages/deno/typedoc.cjs | 10 ++ packages/dispatcher/tsconfig.json | 3 + .../src/common-internals-node/platform.ts | 2 +- packages/node/src/utils/crypto.ts | 3 +- .../base64.ts | 0 .../hex.ts | 0 .../src/{ => common-internals-web}/logging.ts | 0 .../web/src/common-internals-web/readme.md | 2 + .../utf8.ts | 2 +- packages/web/src/idb/driver.ts | 2 + packages/web/src/platform.ts | 9 +- packages/web/src/worker.ts | 2 + pnpm-lock.yaml | 105 +++++++++++++ scripts/build-package.js | 4 + scripts/fetch-deno-dts.mjs | 33 ++++ scripts/publish.js | 1 + scripts/remove-jsr-sourcefiles.mjs | 23 +++ tsconfig.json | 1 + 50 files changed, 1013 insertions(+), 27 deletions(-) create mode 100644 .npmrc create mode 100644 packages/deno/README.md create mode 100644 packages/deno/build.config.cjs create mode 100644 packages/deno/package.json create mode 100644 packages/deno/src/client.ts create mode 120000 packages/deno/src/common-internals-web create mode 100644 packages/deno/src/index.ts create mode 100644 packages/deno/src/methods.ts create mode 100644 packages/deno/src/methods/download-file.ts create mode 100644 packages/deno/src/platform.ts create mode 100644 packages/deno/src/sqlite/driver.ts create mode 100644 packages/deno/src/sqlite/index.ts create mode 100644 packages/deno/src/sqlite/sqlite.test.ts create mode 100644 packages/deno/src/utils.ts create mode 100644 packages/deno/src/utils/crypto.test.ts create mode 100644 packages/deno/src/utils/crypto.ts create mode 100644 packages/deno/src/utils/exit-hook.ts create mode 100644 packages/deno/src/utils/normalize-file.ts create mode 100644 packages/deno/src/utils/tcp.ts create mode 100644 packages/deno/src/worker.ts create mode 100644 packages/deno/tsconfig.json create mode 100644 packages/deno/typedoc.cjs rename packages/web/src/{encodings => common-internals-web}/base64.ts (100%) rename packages/web/src/{encodings => common-internals-web}/hex.ts (100%) rename packages/web/src/{ => common-internals-web}/logging.ts (100%) create mode 100644 packages/web/src/common-internals-web/readme.md rename packages/web/src/{encodings => common-internals-web}/utf8.ts (90%) create mode 100644 scripts/fetch-deno-dts.mjs create mode 100644 scripts/remove-jsr-sourcefiles.mjs diff --git a/.config/eslint.cjs b/.config/eslint.cjs index 2a1ea066..02b8bd5b 100644 --- a/.config/eslint.cjs +++ b/.config/eslint.cjs @@ -279,7 +279,7 @@ module.exports = { }, }, { - files: ['packages/bun/**'], + files: ['packages/bun/**', 'packages/deno/**'], rules: { 'import/no-unresolved': 'off', 'no-restricted-imports': 'off', @@ -291,7 +291,7 @@ module.exports = { rules: { 'import/no-unresolved': 'off', } - } + }, ], settings: { 'import/resolver': { diff --git a/.github/workflows/test.yaml b/.github/workflows/test.yaml index 2377652e..aae1b802 100644 --- a/.github/workflows/test.yaml +++ b/.github/workflows/test.yaml @@ -67,7 +67,7 @@ jobs: - name: 'Build tests' run: pnpm exec vite build -c .config/vite.deno.mts - name: 'Run tests' - run: cd dist/tests && deno test + run: cd dist/tests && deno test -A --unstable-ffi test-web: runs-on: ubuntu-latest diff --git a/.npmrc b/.npmrc new file mode 100644 index 00000000..41583e36 --- /dev/null +++ b/.npmrc @@ -0,0 +1 @@ +@jsr:registry=https://npm.jsr.io diff --git a/package.json b/package.json index ebd5c48a..ff338996 100644 --- a/package.json +++ b/package.json @@ -10,7 +10,7 @@ ], "scripts": { "prepare": "husky install .config/husky", - "postinstall": "node scripts/validate-deps-versions.mjs", + "postinstall": "node scripts/validate-deps-versions.mjs && node scripts/fetch-deno-dts.mjs && node scripts/remove-jsr-sourcefiles.mjs", "test": "pnpm run -r test && vitest --config .config/vite.mts run", "test:dev": "vitest --config .config/vite.mts watch", "test:ui": "vitest --config .config/vite.mts --ui", diff --git a/packages/bun/src/platform.ts b/packages/bun/src/platform.ts index ef805446..7af79895 100644 --- a/packages/bun/src/platform.ts +++ b/packages/bun/src/platform.ts @@ -1,8 +1,14 @@ +import * as os from 'os' + import { NodePlatform } from './common-internals-node/platform.js' import { normalizeFile } from './utils/normalize-file.js' export class BunPlatform extends NodePlatform { declare normalizeFile: typeof normalizeFile + + getDeviceModel(): string { + return `Bun/${process.version} (${os.type()} ${os.arch()})` + } } BunPlatform.prototype.normalizeFile = normalizeFile diff --git a/packages/bun/src/worker.ts b/packages/bun/src/worker.ts index 0c953a52..877db612 100644 --- a/packages/bun/src/worker.ts +++ b/packages/bun/src/worker.ts @@ -14,7 +14,7 @@ import { WorkerMessageHandler, } from '@mtcute/core/worker.js' -import { NodePlatform } from './common-internals-node/platform.js' +import { BunPlatform } from './platform.js' export type { TelegramWorkerOptions, TelegramWorkerPortOptions, WorkerCustomMethods } @@ -44,7 +44,7 @@ export class TelegramWorker extends TelegramWorke export class TelegramWorkerPort extends TelegramWorkerPortBase { constructor(readonly options: TelegramWorkerPortOptions) { - setPlatform(new NodePlatform()) + setPlatform(new BunPlatform()) super(options) } diff --git a/packages/core/src/highlevel/methods/files/upload-file.ts b/packages/core/src/highlevel/methods/files/upload-file.ts index eb74837d..0b4b5658 100644 --- a/packages/core/src/highlevel/methods/files/upload-file.ts +++ b/packages/core/src/highlevel/methods/files/upload-file.ts @@ -171,7 +171,8 @@ export async function uploadFile( throw new MtArgumentError('Fetch response contains `null` body') } - file = file.body + // eslint-disable-next-line @typescript-eslint/no-unnecessary-type-assertion + file = file.body as ReadableStream } if (!(file instanceof ReadableStream)) { diff --git a/packages/core/src/highlevel/types/files/utils.ts b/packages/core/src/highlevel/types/files/utils.ts index 0eac28bf..a339fc21 100644 --- a/packages/core/src/highlevel/types/files/utils.ts +++ b/packages/core/src/highlevel/types/files/utils.ts @@ -1,9 +1,7 @@ -/* eslint-disable no-restricted-imports */ -import type { ReadStream } from 'node:fs' - import { tdFileId } from '@mtcute/file-id' import { tl } from '@mtcute/tl' +import { AnyToNever } from '../../../types/utils.js' import { FileLocation } from './file-location.js' import { UploadedFile } from './uploaded-file.js' @@ -14,8 +12,9 @@ import { UploadedFile } from './uploaded-file.js' * - `File`, `Blob` (from the Web API) * - `string`, which will be interpreted as file path (**non-browser only!**) * - `URL` (from the Web API, will be `fetch()`-ed; `file://` URLs are not available in browsers) - * - `ReadStream` (for Node.js/Bun, from the `fs` module) + * - `ReadStream` (for Node.js/Bun, from the `node:fs` module) * - `BunFile` (from `Bun.file()`) + * - `Deno.FsFile` (from `Deno.open()` in Deno) * - `ReadableStream` (Web API readable stream) * - `Readable` (Node.js/Bun readable stream) * - `Response` (from `window.fetch`) @@ -26,10 +25,14 @@ export type UploadFileLike = | File | Blob | string - | ReadStream - | ReadableStream - | NodeJS.ReadableStream - | Response + | AnyToNever + | AnyToNever> + | AnyToNever + | AnyToNever + | AnyToNever + +// AnyToNever in the above type ensures we don't make the entire type `any` +// if some of the types are not available in the current environment /** * Describes types that can be used as an input @@ -41,6 +44,8 @@ export type UploadFileLike = * - `ReadStream` (for Node.js/Bun, from the `fs` module) * - `ReadableStream` (from the Web API, base readable stream) * - `Readable` (for Node.js/Bun, base readable stream) + * - `BunFile` (from `Bun.file()`) + * - `Deno.FsFile` (from `Deno.open()` in Deno) * - {@link UploadedFile} returned from {@link TelegramClient.uploadFile} * - `tl.TypeInputFile` and `tl.TypeInputMedia` TL objects * - `string` with a path to a local file prepended with `file:` (non-browser only) (e.g. `file:image.jpg`) diff --git a/packages/core/src/highlevel/worker/protocol.ts b/packages/core/src/highlevel/worker/protocol.ts index 4a603578..2f9b61d8 100644 --- a/packages/core/src/highlevel/worker/protocol.ts +++ b/packages/core/src/highlevel/worker/protocol.ts @@ -1,3 +1,4 @@ +/// import type { Worker as NodeWorker } from 'node:worker_threads' import { tl } from '@mtcute/tl' diff --git a/packages/core/src/storage/sqlite/repository/peers.ts b/packages/core/src/storage/sqlite/repository/peers.ts index 2e48b9ad..3426e0c8 100644 --- a/packages/core/src/storage/sqlite/repository/peers.ts +++ b/packages/core/src/storage/sqlite/repository/peers.ts @@ -62,10 +62,9 @@ export class SqlitePeersRepository implements IPeersRepository { this._driver._writeLater(this._store, [ peer.id, peer.accessHash, - // add commas to make it easier to search with LIKE JSON.stringify(peer.usernames), peer.updated, - peer.phone, + peer.phone ?? null, peer.complete, ]) } diff --git a/packages/core/src/types/utils.ts b/packages/core/src/types/utils.ts index 666c6914..2f58e50f 100644 --- a/packages/core/src/types/utils.ts +++ b/packages/core/src/types/utils.ts @@ -1,6 +1,8 @@ export type MaybePromise = T | Promise export type PartialExcept = Partial> & Pick export type PartialOnly = Partial> & Omit +// eslint-disable-next-line @typescript-eslint/no-explicit-any +export type AnyToNever = any extends T ? never : T export type MaybeArray = T | T[] diff --git a/packages/core/src/utils/error-reporting.ts b/packages/core/src/utils/error-reporting.ts index 7c9470e9..0f219153 100644 --- a/packages/core/src/utils/error-reporting.ts +++ b/packages/core/src/utils/error-reporting.ts @@ -7,7 +7,8 @@ export function reportUnknownError(log: Logger, error: tl.RpcError, method: stri fetch(`https://rpc.pwrtelegram.xyz/?code=${error.code}&method=${method}&error=${error.text}`) .then((r) => r.json()) - .then((r) => { + // eslint-disable-next-line @typescript-eslint/no-explicit-any + .then((r: any) => { if (r.ok) { log.info('telerpc responded with error info for %s: %s', error.text, r.result) } else { diff --git a/packages/deno/README.md b/packages/deno/README.md new file mode 100644 index 00000000..2d2baff9 --- /dev/null +++ b/packages/deno/README.md @@ -0,0 +1,25 @@ +# @mtcute/bun + +📖 [API Reference](https://ref.mtcute.dev/modules/_mtcute_deno.html) + +‼️ **Experimental** Deno support package for mtcute. Includes: +- SQLite storage (based on [`@db/sqlite`](https://jsr.io/@db/sqlite)) +- TCP transport (based on Deno-native APIs) +- `TelegramClient` implementation using the above +- HTML and Markdown parsers + +## Usage + +```typescript +import { TelegramClient } from '@mtcute/deno' + +const tg = new TelegramClient({ + apiId: 12345, + apiHash: 'abcdef', + storage: 'my-account' +}) + +tg.run(async (user) => { + console.log(`✨ logged in as ${user.displayName}`) +}) +``` diff --git a/packages/deno/build.config.cjs b/packages/deno/build.config.cjs new file mode 100644 index 00000000..17718026 --- /dev/null +++ b/packages/deno/build.config.cjs @@ -0,0 +1 @@ +module.exports = () => ({ buildCjs: false }) diff --git a/packages/deno/package.json b/packages/deno/package.json new file mode 100644 index 00000000..fa148f60 --- /dev/null +++ b/packages/deno/package.json @@ -0,0 +1,30 @@ +{ + "name": "@mtcute/deno", + "private": true, + "version": "0.11.0", + "description": "Meta-package for Deno", + "author": "alina sireneva ", + "license": "MIT", + "main": "src/index.ts", + "type": "module", + "sideEffects": false, + "scripts": { + "docs": "typedoc", + "build": "pnpm run -w build-package deno" + }, + "exports": { + ".": "./src/index.ts", + "./utils.js": "./src/utils.ts" + }, + "dependencies": { + "@mtcute/core": "workspace:^", + "@mtcute/wasm": "workspace:^", + "@mtcute/markdown-parser": "workspace:^", + "@mtcute/html-parser": "workspace:^", + "@db/sqlite": "npm:@jsr/db__sqlite@0.11.1", + "@std/io": "npm:@jsr/std__io@0.223.0" + }, + "devDependencies": { + "@mtcute/test": "workspace:^" + } +} diff --git a/packages/deno/src/client.ts b/packages/deno/src/client.ts new file mode 100644 index 00000000..32a03e96 --- /dev/null +++ b/packages/deno/src/client.ts @@ -0,0 +1,144 @@ +import { createInterface, Interface as RlInterface } from 'node:readline' +import { Readable, Writable } from 'node:stream' + +import { FileDownloadLocation, FileDownloadParameters, ITelegramStorageProvider, PartialOnly, User } from '@mtcute/core' +import { + BaseTelegramClient as BaseTelegramClientBase, + BaseTelegramClientOptions as BaseTelegramClientOptionsBase, + TelegramClient as TelegramClientBase, + TelegramClientOptions, +} from '@mtcute/core/client.js' +import { setPlatform } from '@mtcute/core/platform.js' + +import { downloadToFile } from './methods/download-file.js' +import { DenoPlatform } from './platform.js' +import { SqliteStorage } from './sqlite/index.js' +import { DenoCryptoProvider } from './utils/crypto.js' +import { TcpTransport } from './utils/tcp.js' + +export type { TelegramClientOptions } + +export interface BaseTelegramClientOptions + extends PartialOnly, 'transport' | 'crypto'> { + /** + * Storage to use for this client. + * + * If a string is passed, it will be used as + * a name for an SQLite database file. + * + * @default `"client.session"` + */ + storage?: string | ITelegramStorageProvider + + /** + * **ADVANCED USE ONLY** + * + * Whether to not set up the platform. + * This is useful if you call `setPlatform` yourself. + */ + platformless?: boolean +} + +export class BaseTelegramClient extends BaseTelegramClientBase { + constructor(opts: BaseTelegramClientOptions) { + if (!opts.platformless) setPlatform(new DenoPlatform()) + + super({ + crypto: new DenoCryptoProvider(), + transport: () => new TcpTransport(), + ...opts, + storage: + typeof opts.storage === 'string' ? + new SqliteStorage(opts.storage) : + opts.storage ?? new SqliteStorage('client.session'), + }) + } +} + +/** + * Telegram client for use in Node.js + */ +export class TelegramClient extends TelegramClientBase { + constructor(opts: TelegramClientOptions) { + if ('client' in opts) { + super(opts) + + return + } + + super({ + client: new BaseTelegramClient(opts), + }) + } + + private _rl?: RlInterface + + /** + * Tiny wrapper over Node `readline` package + * for simpler user input for `.run()` method. + * + * Associated `readline` interface is closed + * after `run()` returns, or with the client. + * + * @param text Text of the question + */ + input(text: string): Promise { + if (!this._rl) { + this._rl = createInterface({ + // eslint-disable-next-line + input: Readable.fromWeb(Deno.stdin.readable as any), + output: Writable.fromWeb(Deno.stdout.writable), + }) + } + + return new Promise((res) => this._rl?.question(text, res)) + } + + close(): Promise { + this._rl?.close() + + return super.close() + } + + start(params: Parameters[0] = {}): Promise { + if (!params.botToken) { + if (!params.phone) params.phone = () => this.input('phone > ') + if (!params.code) params.code = () => this.input('code > ') + + if (!params.password) { + params.password = () => this.input('2fa password > ') + } + } + + return super.start(params).then((user) => { + if (this._rl) { + this._rl.close() + delete this._rl + } + + return user + }) + } + + run( + params: Parameters[0] | ((user: User) => void | Promise), + then?: (user: User) => void | Promise, + ): void { + if (typeof params === 'function') { + then = params + params = {} + } + + this.start(params) + .then(then) + .catch((err) => this.emitError(err)) + } + + downloadToFile( + filename: string, + location: FileDownloadLocation, + params?: FileDownloadParameters | undefined, + ): Promise { + return downloadToFile(this, filename, location, params) + } +} diff --git a/packages/deno/src/common-internals-web b/packages/deno/src/common-internals-web new file mode 120000 index 00000000..3f10a5de --- /dev/null +++ b/packages/deno/src/common-internals-web @@ -0,0 +1 @@ +../../web/src/common-internals-web \ No newline at end of file diff --git a/packages/deno/src/index.ts b/packages/deno/src/index.ts new file mode 100644 index 00000000..87f84c57 --- /dev/null +++ b/packages/deno/src/index.ts @@ -0,0 +1,9 @@ +export * from './client.js' +export * from './platform.js' +export * from './sqlite/index.js' +export * from './utils/crypto.js' +export * from './utils/tcp.js' +export * from './worker.js' +export * from '@mtcute/core' +export * from '@mtcute/html-parser' +export * from '@mtcute/markdown-parser' diff --git a/packages/deno/src/methods.ts b/packages/deno/src/methods.ts new file mode 100644 index 00000000..f25b163c --- /dev/null +++ b/packages/deno/src/methods.ts @@ -0,0 +1,2 @@ +export { downloadToFile } from './methods/download-file.js' +export * from '@mtcute/core/methods.js' diff --git a/packages/deno/src/methods/download-file.ts b/packages/deno/src/methods/download-file.ts new file mode 100644 index 00000000..fc2adf48 --- /dev/null +++ b/packages/deno/src/methods/download-file.ts @@ -0,0 +1,39 @@ +import { FileDownloadLocation, FileDownloadParameters, FileLocation, ITelegramClient } from '@mtcute/core' +import { downloadAsIterable } from '@mtcute/core/methods.js' + +import { writeAll } from '@std/io/write-all' + +/** + * Download a remote file to a local file (only for NodeJS). + * Promise will resolve once the download is complete. + * + * @param filename Local file name to which the remote file will be downloaded + * @param params File download parameters + */ +export async function downloadToFile( + client: ITelegramClient, + filename: string, + location: FileDownloadLocation, + params?: FileDownloadParameters, +): Promise { + if (location instanceof FileLocation && ArrayBuffer.isView(location.location)) { + // early return for inline files + await Deno.writeFile(filename, location.location) + } + + const fd = await Deno.open(filename, { write: true, create: true, truncate: true }) + + if (params?.abortSignal) { + params.abortSignal.addEventListener('abort', () => { + client.log.debug('aborting file download %s - cleaning up', filename) + fd.close() + Deno.removeSync(filename) + }) + } + + for await (const chunk of downloadAsIterable(client, location, params)) { + await writeAll(fd, chunk) + } + + fd.close() +} diff --git a/packages/deno/src/platform.ts b/packages/deno/src/platform.ts new file mode 100644 index 00000000..aaff526a --- /dev/null +++ b/packages/deno/src/platform.ts @@ -0,0 +1,48 @@ +import { ICorePlatform } from '@mtcute/core/platform.js' + +import { base64Decode, base64Encode } from './common-internals-web/base64.js' +import { hexDecode, hexEncode } from './common-internals-web/hex.js' +import { defaultLoggingHandler } from './common-internals-web/logging.js' +import { utf8ByteLength, utf8Decode, utf8Encode } from './common-internals-web/utf8.js' +import { beforeExit } from './utils/exit-hook.js' +import { normalizeFile } from './utils/normalize-file.js' + +export class DenoPlatform implements ICorePlatform { + declare log: typeof defaultLoggingHandler + declare beforeExit: typeof beforeExit + declare normalizeFile: typeof normalizeFile + + getDeviceModel(): string { + return `Deno/${Deno.version.deno} (${Deno.build.os} ${Deno.build.arch})` + } + + getDefaultLogLevel(): number | null { + const envLogLevel = parseInt(Deno.env.get('MTCUTE_LOG_LEVEL') ?? '') + + if (!isNaN(envLogLevel)) { + return envLogLevel + } + + return null + } + + // ITlPlatform + declare utf8ByteLength: typeof utf8ByteLength + declare utf8Encode: typeof utf8Encode + declare utf8Decode: typeof utf8Decode + declare hexEncode: typeof hexEncode + declare hexDecode: typeof hexDecode + declare base64Encode: typeof base64Encode + declare base64Decode: typeof base64Decode +} + +DenoPlatform.prototype.utf8ByteLength = utf8ByteLength +DenoPlatform.prototype.utf8Encode = utf8Encode +DenoPlatform.prototype.utf8Decode = utf8Decode +DenoPlatform.prototype.hexEncode = hexEncode +DenoPlatform.prototype.hexDecode = hexDecode +DenoPlatform.prototype.base64Encode = base64Encode +DenoPlatform.prototype.base64Decode = base64Decode +DenoPlatform.prototype.log = defaultLoggingHandler +DenoPlatform.prototype.beforeExit = beforeExit +DenoPlatform.prototype.normalizeFile = normalizeFile diff --git a/packages/deno/src/sqlite/driver.ts b/packages/deno/src/sqlite/driver.ts new file mode 100644 index 00000000..e983f027 --- /dev/null +++ b/packages/deno/src/sqlite/driver.ts @@ -0,0 +1,38 @@ +import { BaseSqliteStorageDriver, ISqliteDatabase } from '@mtcute/core' + +import { Database } from '@db/sqlite' + +export interface SqliteStorageDriverOptions { + /** + * By default, WAL mode is enabled, which + * significantly improves performance. + * [Learn more](https://bun.sh/docs/api/sqlite#wal-mode) + * + * However, you might encounter some issues, + * and if you do, you can disable WAL by passing `true` + * + * @default false + */ + disableWal?: boolean +} + +export class SqliteStorageDriver extends BaseSqliteStorageDriver { + constructor( + readonly filename = ':memory:', + readonly params?: SqliteStorageDriverOptions, + ) { + super() + } + + _createDatabase(): ISqliteDatabase { + const db = new Database(this.filename, { + int64: true, + }) + + if (!this.params?.disableWal) { + db.exec('PRAGMA journal_mode = WAL;') + } + + return db as ISqliteDatabase + } +} diff --git a/packages/deno/src/sqlite/index.ts b/packages/deno/src/sqlite/index.ts new file mode 100644 index 00000000..882b228d --- /dev/null +++ b/packages/deno/src/sqlite/index.ts @@ -0,0 +1,14 @@ +import { BaseSqliteStorage } from '@mtcute/core' + +import { SqliteStorageDriver, SqliteStorageDriverOptions } from './driver.js' + +export { SqliteStorageDriver } from './driver.js' + +export class SqliteStorage extends BaseSqliteStorage { + constructor( + readonly filename = ':memory:', + readonly params?: SqliteStorageDriverOptions, + ) { + super(new SqliteStorageDriver(filename, params)) + } +} diff --git a/packages/deno/src/sqlite/sqlite.test.ts b/packages/deno/src/sqlite/sqlite.test.ts new file mode 100644 index 00000000..0a9d9924 --- /dev/null +++ b/packages/deno/src/sqlite/sqlite.test.ts @@ -0,0 +1,31 @@ +import { afterAll, beforeAll, describe } from 'vitest' + +import { LogManager } from '@mtcute/core/utils.js' +import { + testAuthKeysRepository, + testKeyValueRepository, + testPeersRepository, + testRefMessagesRepository, +} from '@mtcute/test' + +if (import.meta.env.TEST_ENV === 'deno') { + const { SqliteStorage } = await import('./index.js') + + describe('SqliteStorage', () => { + const storage = new SqliteStorage(':memory:') + + beforeAll(async () => { + storage.driver.setup(new LogManager()) + await storage.driver.load() + }) + + testAuthKeysRepository(storage.authKeys) + testKeyValueRepository(storage.kv, storage.driver) + testPeersRepository(storage.peers, storage.driver) + testRefMessagesRepository(storage.refMessages, storage.driver) + + afterAll(() => storage.driver.destroy()) + }) +} else { + describe.skip('SqliteStorage', () => {}) +} diff --git a/packages/deno/src/utils.ts b/packages/deno/src/utils.ts new file mode 100644 index 00000000..3356b98c --- /dev/null +++ b/packages/deno/src/utils.ts @@ -0,0 +1 @@ +export * from '@mtcute/core/utils.js' diff --git a/packages/deno/src/utils/crypto.test.ts b/packages/deno/src/utils/crypto.test.ts new file mode 100644 index 00000000..4095b5e2 --- /dev/null +++ b/packages/deno/src/utils/crypto.test.ts @@ -0,0 +1,13 @@ +import { describe } from 'vitest' + +import { testCryptoProvider } from '@mtcute/test' + +if (import.meta.env.TEST_ENV === 'deno') { + describe('DenoCryptoProvider', async () => { + const { DenoCryptoProvider } = await import('./crypto.js') + + testCryptoProvider(new DenoCryptoProvider()) + }) +} else { + describe.skip('DenoCryptoProvider', () => {}) +} diff --git a/packages/deno/src/utils/crypto.ts b/packages/deno/src/utils/crypto.ts new file mode 100644 index 00000000..04b7b21b --- /dev/null +++ b/packages/deno/src/utils/crypto.ts @@ -0,0 +1,97 @@ +/* eslint-disable no-restricted-globals */ +import { Buffer } from 'node:buffer' +import { createCipheriv, createHash, createHmac, pbkdf2 } from 'node:crypto' +import { deflateSync, gunzipSync } from 'node:zlib' + +import { BaseCryptoProvider, IAesCtr, ICryptoProvider, IEncryptionScheme } from '@mtcute/core/utils.js' +import { getWasmUrl, ige256Decrypt, ige256Encrypt, initSync } from '@mtcute/wasm' +// node:crypto is properly implemented in deno, so we can just use it +// largely just copy-pasting from @mtcute/node + +const toUint8Array = (buf: Buffer | Uint8Array): Uint8Array => { + if (!Buffer.isBuffer(buf)) return buf + + return new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength) +} + +export class DenoCryptoProvider extends BaseCryptoProvider implements ICryptoProvider { + async initialize(): Promise { + // eslint-disable-next-line no-restricted-globals + const wasm = await fetch(getWasmUrl()).then((res) => res.arrayBuffer()) + initSync(wasm) + } + + createAesCtr(key: Uint8Array, iv: Uint8Array): IAesCtr { + const cipher = createCipheriv(`aes-${key.length * 8}-ctr`, key, iv) + + const update = (data: Uint8Array) => toUint8Array(cipher.update(data)) + + return { + process: update, + } + } + + pbkdf2( + password: Uint8Array, + salt: Uint8Array, + iterations: number, + keylen = 64, + algo = 'sha512', + ): Promise { + return new Promise((resolve, reject) => + pbkdf2(password, salt, iterations, keylen, algo, (err: Error | null, buf: Uint8Array) => + err !== null ? reject(err) : resolve(toUint8Array(buf)), + ), + ) + } + + sha1(data: Uint8Array): Uint8Array { + return toUint8Array(createHash('sha1').update(data).digest()) + } + + sha256(data: Uint8Array): Uint8Array { + return toUint8Array(createHash('sha256').update(data).digest()) + } + + hmacSha256(data: Uint8Array, key: Uint8Array): Uint8Array { + return toUint8Array(createHmac('sha256', key).update(data).digest()) + } + + createAesIge(key: Uint8Array, iv: Uint8Array): IEncryptionScheme { + return { + encrypt(data: Uint8Array): Uint8Array { + return ige256Encrypt(data, key, iv) + }, + decrypt(data: Uint8Array): Uint8Array { + return ige256Decrypt(data, key, iv) + }, + } + } + + gzip(data: Uint8Array, maxSize: number): Uint8Array | null { + try { + // telegram accepts both zlib and gzip, but zlib is faster and has less overhead, so we use it here + return toUint8Array( + deflateSync(data, { + maxOutputLength: maxSize, + }), + ) + // hot path, avoid additional runtime checks + // eslint-disable-next-line @typescript-eslint/no-explicit-any + } catch (e: any) { + if (e.code === 'ERR_BUFFER_TOO_LARGE') { + return null + } + + throw e + } + } + + gunzip(data: Uint8Array): Uint8Array { + return toUint8Array(gunzipSync(data)) + } + + randomFill(buf: Uint8Array) { + crypto.getRandomValues(buf) + } +} diff --git a/packages/deno/src/utils/exit-hook.ts b/packages/deno/src/utils/exit-hook.ts new file mode 100644 index 00000000..aa43b595 --- /dev/null +++ b/packages/deno/src/utils/exit-hook.ts @@ -0,0 +1,21 @@ +const callbacks = new Set<() => void>() + +let registered = false + +export function beforeExit(fn: () => void): () => void { + if (!registered) { + registered = true + + window.addEventListener('unload', () => { + for (const callback of callbacks) { + callback() + } + }) + } + + callbacks.add(fn) + + return () => { + callbacks.delete(fn) + } +} diff --git a/packages/deno/src/utils/normalize-file.ts b/packages/deno/src/utils/normalize-file.ts new file mode 100644 index 00000000..7e5b10e8 --- /dev/null +++ b/packages/deno/src/utils/normalize-file.ts @@ -0,0 +1,50 @@ +import { ReadStream } from 'node:fs' +import { stat } from 'node:fs/promises' +import { basename } from 'node:path' +import { Readable as NodeReadable } from 'node:stream' + +import { UploadFileLike } from '@mtcute/core' +import { extractFileName } from '@mtcute/core/utils.js' + +export async function normalizeFile(file: UploadFileLike) { + if (typeof file === 'string') { + const fd = await Deno.open(file, { read: true }) + + return { + file: fd.readable, + fileSize: (await fd.stat()).size, + fileName: extractFileName(file), + } + } + + if (file instanceof Deno.FsFile) { + const stat = await file.stat() + + return { + file: file.readable, + // https://github.com/denoland/deno/issues/23591 + // fileName: ..., + fileSize: stat.size, + } + } + + // while these are not Deno-specific, they still may happen + if (file instanceof ReadStream) { + const fileName = basename(file.path.toString()) + const fileSize = await stat(file.path.toString()).then((stat) => stat.size) + + return { + file: NodeReadable.toWeb(file) as unknown as ReadableStream, + fileName, + fileSize, + } + } + + if (file instanceof NodeReadable) { + return { + file: NodeReadable.toWeb(file) as unknown as ReadableStream, + } + } + + return null +} diff --git a/packages/deno/src/utils/tcp.ts b/packages/deno/src/utils/tcp.ts new file mode 100644 index 00000000..0bdcd6ef --- /dev/null +++ b/packages/deno/src/utils/tcp.ts @@ -0,0 +1,135 @@ +import EventEmitter from 'events' + +import { IntermediatePacketCodec, IPacketCodec, ITelegramTransport, MtcuteError, TransportState } from '@mtcute/core' +import { BasicDcOption, ICryptoProvider, Logger } from '@mtcute/core/utils.js' + +import { writeAll } from '@std/io/write-all' + +/** + * Base for TCP transports. + * Subclasses must provide packet codec in `_packetCodec` property + */ +export abstract class BaseTcpTransport extends EventEmitter implements ITelegramTransport { + protected _currentDc: BasicDcOption | null = null + protected _state: TransportState = TransportState.Idle + protected _socket: Deno.TcpConn | null = null + + abstract _packetCodec: IPacketCodec + protected _crypto!: ICryptoProvider + protected log!: Logger + + packetCodecInitialized = false + + private _updateLogPrefix() { + if (this._currentDc) { + this.log.prefix = `[TCP:${this._currentDc.ipAddress}:${this._currentDc.port}] ` + } else { + this.log.prefix = '[TCP:disconnected] ' + } + } + + setup(crypto: ICryptoProvider, log: Logger): void { + this._crypto = crypto + this.log = log.create('tcp') + this._updateLogPrefix() + } + + state(): TransportState { + return this._state + } + + currentDc(): BasicDcOption | null { + return this._currentDc + } + + // eslint-disable-next-line @typescript-eslint/no-unused-vars + connect(dc: BasicDcOption, testMode: boolean): void { + if (this._state !== TransportState.Idle) { + throw new MtcuteError('Transport is not IDLE') + } + + if (!this.packetCodecInitialized) { + this._packetCodec.setup?.(this._crypto, this.log) + this._packetCodec.on('error', (err) => this.emit('error', err)) + this._packetCodec.on('packet', (buf) => this.emit('message', buf)) + this.packetCodecInitialized = true + } + + this._state = TransportState.Connecting + this._currentDc = dc + this._updateLogPrefix() + + this.log.debug('connecting to %j', dc) + + Deno.connect({ + hostname: dc.ipAddress, + port: dc.port, + transport: 'tcp', + }) + .then(this.handleConnect.bind(this)) + .catch((err) => { + this.handleError(err) + this.close() + }) + } + + close(): void { + if (this._state === TransportState.Idle) return + this.log.info('connection closed') + + this._state = TransportState.Idle + this._socket?.close() + this._socket = null + this._currentDc = null + this._packetCodec.reset() + this.emit('close') + } + + handleError(error: unknown): void { + this.log.error('error: %s', error) + this.emit('error', error) + } + + async handleConnect(socket: Deno.TcpConn): Promise { + this._socket = socket + this.log.info('connected') + + try { + const packet = await this._packetCodec.tag() + + if (packet.length) { + await writeAll(this._socket, packet) + } + + this._state = TransportState.Ready + this.emit('ready') + + const reader = this._socket.readable.getReader() + + while (true) { + const { done, value } = await reader.read() + if (done) break + + this._packetCodec.feed(value) + } + } catch (e) { + this.handleError(e) + } + + this.close() + } + + async send(bytes: Uint8Array): Promise { + const framed = await this._packetCodec.encode(bytes) + + if (this._state !== TransportState.Ready) { + throw new MtcuteError('Transport is not READY') + } + + await writeAll(this._socket!, framed) + } +} + +export class TcpTransport extends BaseTcpTransport { + _packetCodec = new IntermediatePacketCodec() +} diff --git a/packages/deno/src/worker.ts b/packages/deno/src/worker.ts new file mode 100644 index 00000000..64e34db3 --- /dev/null +++ b/packages/deno/src/worker.ts @@ -0,0 +1,71 @@ +/// +import { setPlatform } from '@mtcute/core/platform.js' +import { + ClientMessageHandler, + RespondFn, + SendFn, + SomeWorker, + TelegramWorker as TelegramWorkerBase, + TelegramWorkerOptions, + TelegramWorkerPort as TelegramWorkerPortBase, + TelegramWorkerPortOptions, + WorkerCustomMethods, + WorkerMessageHandler, +} from '@mtcute/core/worker.js' + +import { DenoPlatform } from './platform.js' + +export type { TelegramWorkerOptions, TelegramWorkerPortOptions, WorkerCustomMethods } + +let _registered = false + +export class TelegramWorker extends TelegramWorkerBase { + registerWorker(handler: WorkerMessageHandler): RespondFn { + if (_registered) { + throw new Error('TelegramWorker must be created only once') + } + + _registered = true + + if (typeof WorkerGlobalScope !== 'undefined' && self instanceof WorkerGlobalScope) { + const respond: RespondFn = self.postMessage.bind(self) + + // eslint-disable-next-line + self.addEventListener('message', (message) => handler((message as any).data, respond)) + + return respond + } + + throw new Error('TelegramWorker must be created from a worker') + } +} + +const platform = new DenoPlatform() + +export class TelegramWorkerPort extends TelegramWorkerPortBase { + constructor(readonly options: TelegramWorkerPortOptions) { + setPlatform(platform) + super(options) + } + + connectToWorker(worker: SomeWorker, handler: ClientMessageHandler): [SendFn, () => void] { + if (worker instanceof Worker) { + const send: SendFn = worker.postMessage.bind(worker) + + const messageHandler = (ev: MessageEvent) => { + // eslint-disable-next-line @typescript-eslint/no-unsafe-argument + handler(ev.data) + } + + worker.addEventListener('message', messageHandler) + + return [ + send, + () => { + worker.removeEventListener('message', messageHandler) + }, + ] + } + throw new Error('Only workers are supported') + } +} diff --git a/packages/deno/tsconfig.json b/packages/deno/tsconfig.json new file mode 100644 index 00000000..66079ea1 --- /dev/null +++ b/packages/deno/tsconfig.json @@ -0,0 +1,16 @@ +{ + "extends": "../../tsconfig.json", + "compilerOptions": { + "outDir": "./dist", + "rootDir": "./src", + }, + "include": [ + "./src", + ], + "references": [ + { "path": "../core" }, + { "path": "../dispatcher" }, + { "path": "../html-parser" }, + { "path": "../markdown-parser" } + ] +} diff --git a/packages/deno/typedoc.cjs b/packages/deno/typedoc.cjs new file mode 100644 index 00000000..e1f51e65 --- /dev/null +++ b/packages/deno/typedoc.cjs @@ -0,0 +1,10 @@ +module.exports = { + extends: ['../../.config/typedoc/config.base.cjs'], + entryPoints: ['./src/index.ts'], + externalPattern: [ + '../core/**', + '../html-parser/**', + '../markdown-parser/**', + '../sqlite/**', + ], +} diff --git a/packages/dispatcher/tsconfig.json b/packages/dispatcher/tsconfig.json index 6a3f7a53..919db0b1 100644 --- a/packages/dispatcher/tsconfig.json +++ b/packages/dispatcher/tsconfig.json @@ -6,5 +6,8 @@ }, "include": [ "./src", + ], + "references": [ + { "path": "../core" }, ] } diff --git a/packages/node/src/common-internals-node/platform.ts b/packages/node/src/common-internals-node/platform.ts index afd58299..f74035a5 100644 --- a/packages/node/src/common-internals-node/platform.ts +++ b/packages/node/src/common-internals-node/platform.ts @@ -17,7 +17,7 @@ export class NodePlatform implements ICorePlatform { declare normalizeFile: typeof normalizeFile getDeviceModel(): string { - return `${os.type()} ${os.arch()} ${os.release()}` + return `Node.js/${process.version} (${os.type()} ${os.arch()})` } getDefaultLogLevel(): number | null { diff --git a/packages/node/src/utils/crypto.ts b/packages/node/src/utils/crypto.ts index a04d1f13..96709dfa 100644 --- a/packages/node/src/utils/crypto.ts +++ b/packages/node/src/utils/crypto.ts @@ -4,7 +4,6 @@ import { readFile } from 'fs/promises' import { createRequire } from 'module' import { deflateSync, gunzipSync } from 'zlib' -import { MaybePromise } from '@mtcute/core' import { BaseCryptoProvider, IAesCtr, ICryptoProvider, IEncryptionScheme } from '@mtcute/core/utils.js' import { ige256Decrypt, ige256Encrypt, initSync } from '@mtcute/wasm' @@ -25,7 +24,7 @@ export abstract class BaseNodeCryptoProvider extends BaseCryptoProvider { iterations: number, keylen = 64, algo = 'sha512', - ): MaybePromise { + ): Promise { return new Promise((resolve, reject) => pbkdf2(password, salt, iterations, keylen, algo, (err: Error | null, buf: Uint8Array) => err !== null ? reject(err) : resolve(buf), diff --git a/packages/web/src/encodings/base64.ts b/packages/web/src/common-internals-web/base64.ts similarity index 100% rename from packages/web/src/encodings/base64.ts rename to packages/web/src/common-internals-web/base64.ts diff --git a/packages/web/src/encodings/hex.ts b/packages/web/src/common-internals-web/hex.ts similarity index 100% rename from packages/web/src/encodings/hex.ts rename to packages/web/src/common-internals-web/hex.ts diff --git a/packages/web/src/logging.ts b/packages/web/src/common-internals-web/logging.ts similarity index 100% rename from packages/web/src/logging.ts rename to packages/web/src/common-internals-web/logging.ts diff --git a/packages/web/src/common-internals-web/readme.md b/packages/web/src/common-internals-web/readme.md new file mode 100644 index 00000000..b03e8b77 --- /dev/null +++ b/packages/web/src/common-internals-web/readme.md @@ -0,0 +1,2 @@ +this folder is for common code across `@mtcute/web` and `@mtcute/deno`. +it is symlinked into `@mtcute/deno` \ No newline at end of file diff --git a/packages/web/src/encodings/utf8.ts b/packages/web/src/common-internals-web/utf8.ts similarity index 90% rename from packages/web/src/encodings/utf8.ts rename to packages/web/src/common-internals-web/utf8.ts index a4cb1168..8febf7e8 100644 --- a/packages/web/src/encodings/utf8.ts +++ b/packages/web/src/common-internals-web/utf8.ts @@ -9,7 +9,7 @@ export function utf8ByteLength(str: string) { const code = str.charCodeAt(i) if (code > 0x7f && code <= 0x7ff) s++ else if (code > 0x7ff && code <= 0xffff) s += 2 - if (code >= 0xDC00 && code <= 0xDFFF) i-- //trail surrogate + if (code >= 0xdc00 && code <= 0xdfff) i-- //trail surrogate } return s diff --git a/packages/web/src/idb/driver.ts b/packages/web/src/idb/driver.ts index a35d7a1f..7a26d5df 100644 --- a/packages/web/src/idb/driver.ts +++ b/packages/web/src/idb/driver.ts @@ -1,3 +1,5 @@ +/// +/// import { BaseStorageDriver, MtUnsupportedError } from '@mtcute/core' import { txToPromise } from './utils.js' diff --git a/packages/web/src/platform.ts b/packages/web/src/platform.ts index d90f2c3a..84d388e7 100644 --- a/packages/web/src/platform.ts +++ b/packages/web/src/platform.ts @@ -1,10 +1,10 @@ import { ICorePlatform } from '@mtcute/core/platform.js' -import { base64Decode, base64Encode } from './encodings/base64.js' -import { hexDecode, hexEncode } from './encodings/hex.js' -import { utf8ByteLength, utf8Decode, utf8Encode } from './encodings/utf8.js' +import { base64Decode, base64Encode } from './common-internals-web/base64.js' +import { hexDecode, hexEncode } from './common-internals-web/hex.js' +import { defaultLoggingHandler } from './common-internals-web/logging.js' +import { utf8ByteLength, utf8Decode, utf8Encode } from './common-internals-web/utf8.js' import { beforeExit } from './exit-hook.js' -import { defaultLoggingHandler } from './logging.js' export class WebPlatform implements ICorePlatform { // ICorePlatform @@ -52,7 +52,6 @@ export class WebPlatform implements ICorePlatform { declare utf8Decode: typeof utf8Decode declare hexEncode: typeof hexEncode declare hexDecode: typeof hexDecode - declare base64Encode: typeof base64Encode declare base64Decode: typeof base64Decode } diff --git a/packages/web/src/worker.ts b/packages/web/src/worker.ts index e45f7463..23f9dcfc 100644 --- a/packages/web/src/worker.ts +++ b/packages/web/src/worker.ts @@ -1,3 +1,5 @@ +/// +/// import { setPlatform } from '@mtcute/core/platform.js' import { ClientMessageHandler, diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 7c2a5e5d..e52cc9e7 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -231,6 +231,31 @@ importers: specifier: workspace:^ version: link:../test + packages/deno: + dependencies: + '@db/sqlite': + specifier: npm:@jsr/db__sqlite@0.11.1 + version: /@jsr/db__sqlite@0.11.1 + '@mtcute/core': + specifier: workspace:^ + version: link:../core + '@mtcute/html-parser': + specifier: workspace:^ + version: link:../html-parser + '@mtcute/markdown-parser': + specifier: workspace:^ + version: link:../markdown-parser + '@mtcute/wasm': + specifier: workspace:^ + version: link:../wasm + '@std/io': + specifier: npm:@jsr/std__io@0.223.0 + version: /@jsr/std__io@0.223.0 + devDependencies: + '@mtcute/test': + specifier: workspace:^ + version: link:../test + packages/dispatcher: dependencies: '@mtcute/core': @@ -1189,6 +1214,86 @@ packages: '@jridgewell/sourcemap-codec': 1.4.11 dev: true + /@jsr/db__sqlite@0.11.1: + resolution: {integrity: sha512-6IKyfi+TQan431kwOy3WrdzgKwITuDdSKfq6nkWINfNWknPQ+lQ6/R008bAUUz+AwW8e0prxi3IMMxzELUV8Lw==, tarball: https://npm.jsr.io/~/8/@jsr/db__sqlite/0.11.1.tgz} + dependencies: + '@jsr/denosaurs__plug': 1.0.6 + '@jsr/std__path': 0.217.0 + dev: false + + /@jsr/denosaurs__plug@1.0.6: + resolution: {integrity: sha512-2uqvX2xpDy5W76jJVKazXvHuh5WPNg8eUV+2u+Hcn5XLwKqWGr/xj4wQFRMXrS12Xhya+ToZdUg4gxLh+XOOCg==, tarball: https://npm.jsr.io/~/8/@jsr/denosaurs__plug/1.0.6.tgz} + dependencies: + '@jsr/std__encoding': 0.221.0 + '@jsr/std__fmt': 0.221.0 + '@jsr/std__fs': 0.221.0 + '@jsr/std__path': 0.221.0 + dev: false + + /@jsr/std__assert@0.217.0: + resolution: {integrity: sha512-RCQbXJeUVCgDGEPsrO57CI9Cgbo9NAWsJUhZ7vrHgtD//Ic32YmUQazdGKPZzao5Zn8dP6xV4Nma3HHZC5ySTw==, tarball: https://npm.jsr.io/~/8/@jsr/std__assert/0.217.0.tgz} + dependencies: + '@jsr/std__fmt': 0.217.0 + dev: false + + /@jsr/std__assert@0.221.0: + resolution: {integrity: sha512-2B+5fq4Rar8NmLms7sv9YfYlMukZDTNMQV5fXjtZvnaKc8ljt+59UsMtIjTXFsDwsAx7VoxkMKmmdHxlP+h5JA==, tarball: https://npm.jsr.io/~/8/@jsr/std__assert/0.221.0.tgz} + dependencies: + '@jsr/std__fmt': 0.221.0 + dev: false + + /@jsr/std__assert@0.223.0: + resolution: {integrity: sha512-9FWOoAQN1uF5SliWw3IgdXmk2usz5txvausX4sLAASHfQMbUSCe1akcD7HgFV01J/2Mr9TfCjPvsSUzuuASouQ==, tarball: https://npm.jsr.io/~/8/@jsr/std__assert/0.223.0.tgz} + dependencies: + '@jsr/std__fmt': 0.223.0 + dev: false + + /@jsr/std__bytes@0.223.0: + resolution: {integrity: sha512-BBjhj0uFlB3+AVEmaPygEwY5CL5mj3vSZlusC8xxjCRNWDYGukfQT/F5GOTTfjeaq7njduk7TYe6e5cDg659yg==, tarball: https://npm.jsr.io/~/8/@jsr/std__bytes/0.223.0.tgz} + dev: false + + /@jsr/std__encoding@0.221.0: + resolution: {integrity: sha512-FT5i/WHNtXJvqOITDK0eOVIyyOphqtxwhzo5PiVWoYTFmUuFcRYKas39GT1UQDi4s24FcHd2deQEBbi3tPAj1Q==, tarball: https://npm.jsr.io/~/8/@jsr/std__encoding/0.221.0.tgz} + dev: false + + /@jsr/std__fmt@0.217.0: + resolution: {integrity: sha512-L3mVYP7DsujrJ001SvPr4Fl/Fu0e3uzgHJ6NYTRUk7sgi9k7YKeLOLVwRijUX7qIsp3Ourp2DyAHHgYDgT4GcQ==, tarball: https://npm.jsr.io/~/8/@jsr/std__fmt/0.217.0.tgz} + dev: false + + /@jsr/std__fmt@0.221.0: + resolution: {integrity: sha512-VLqM052U78LQ11p/KfqI49a2/sDbKtHFHuxO/h+3Cnvhze9beIZU4Lg3Gpu8rGYjB2YS6CfXzKXHuyAJn5FJFg==, tarball: https://npm.jsr.io/~/8/@jsr/std__fmt/0.221.0.tgz} + dev: false + + /@jsr/std__fmt@0.223.0: + resolution: {integrity: sha512-J6SVTw/l3C4hOwEuqnZ4ZHD1jVIIZt09fb5LP9CMGyVGNnoW8/lxJvCNhIOv+3ZXC1ErGlIzW4bgYSxHwbvSaQ==, tarball: https://npm.jsr.io/~/8/@jsr/std__fmt/0.223.0.tgz} + dev: false + + /@jsr/std__fs@0.221.0: + resolution: {integrity: sha512-2XMlO67zQlKoxbCsfGOBVlnyWhMMdOzYUWfajvggfw2p+yITd9hJj9+tpfiwLf/88CzknhlMLwSCamSYjHKloA==, tarball: https://npm.jsr.io/~/8/@jsr/std__fs/0.221.0.tgz} + dependencies: + '@jsr/std__assert': 0.221.0 + '@jsr/std__path': 0.221.0 + dev: false + + /@jsr/std__io@0.223.0: + resolution: {integrity: sha512-K+OXJHsIf9227aYgNTaapEkpphHrI+oYVkl14UV+le+Fk9MzkJmebU0XAU6krgVS283mW7VPJsXVV3gD5JWvJw==, tarball: https://npm.jsr.io/~/8/@jsr/std__io/0.223.0.tgz} + dependencies: + '@jsr/std__assert': 0.223.0 + '@jsr/std__bytes': 0.223.0 + dev: false + + /@jsr/std__path@0.217.0: + resolution: {integrity: sha512-OkP+yiBJpFZKTH3gHqlepYU3TQzXM/UjEQ0U1gYw8BwVr87TwKfzwAb1WT1vY/Bs8NXScvuP4Kpu/UhEsNHD3A==, tarball: https://npm.jsr.io/~/8/@jsr/std__path/0.217.0.tgz} + dependencies: + '@jsr/std__assert': 0.217.0 + dev: false + + /@jsr/std__path@0.221.0: + resolution: {integrity: sha512-uOWaY4cWp28CFBSisr8M/92FtpyjiFO0+wQSH7GgmiXQUls+vALqdCGewFkunG8RfA/25RGdot5hFXedmtPdOg==, tarball: https://npm.jsr.io/~/8/@jsr/std__path/0.221.0.tgz} + dependencies: + '@jsr/std__assert': 0.221.0 + dev: false + /@ljharb/through@2.3.11: resolution: {integrity: sha512-ccfcIDlogiXNq5KcbAwbaO7lMh3Tm1i3khMPYpxlK8hH/W53zN81KM9coerRLOnTGu3nfXIniAmQbRI9OxbC0w==} engines: {node: '>= 0.4'} diff --git a/scripts/build-package.js b/scripts/build-package.js index fc7bec73..c5898ad6 100644 --- a/scripts/build-package.js +++ b/scripts/build-package.js @@ -499,6 +499,10 @@ if (IS_JSR) { for (const [name, version] of Object.entries(builtPkgJson.dependencies)) { if (name.startsWith('@mtcute/')) { importMap[name] = `jsr:${name}@${version}` + } else if (version.startsWith('npm:@jsr/')) { + const jsrName = version.slice(9).split('@')[0].replace('__', '/') + const jsrVersion = version.slice(9).split('@')[1] + importMap[name] = `jsr:@${jsrName}@${jsrVersion}` } else { importMap[name] = `npm:${name}@${version}` } diff --git a/scripts/fetch-deno-dts.mjs b/scripts/fetch-deno-dts.mjs new file mode 100644 index 00000000..89e7e90d --- /dev/null +++ b/scripts/fetch-deno-dts.mjs @@ -0,0 +1,33 @@ +import { createHash } from 'crypto' +import * as fs from 'fs/promises' +import { dirname } from 'path' +import { fileURLToPath } from 'url' + +const DTS_URL = 'https://github.com/denoland/deno/releases/download/v1.42.4/lib.deno.d.ts' +const SHA256 = '554b5da7baf05e5693ca064fcf1665b0b847743ccfd0db89cb6f2388f2de0276' +const LIB_TARGET = fileURLToPath(new URL('../node_modules/@types/deno/index.d.ts', import.meta.url)) + +const stat = await fs.stat(LIB_TARGET).catch(() => null) + +if (stat?.isFile()) { + const sha256 = createHash('sha256').update(await fs.readFile(LIB_TARGET)).digest('hex') + + if (sha256 === SHA256) { + console.log('lib.deno.d.ts is up to date') + process.exit(0) + } +} + +const stream = await fetch(DTS_URL) +const dts = await stream.text() + +const sha256 = createHash('sha256').update(dts).digest('hex') + +if (sha256 !== SHA256) { + console.error(`lib.deno.d.ts SHA256 mismatch: expected ${SHA256}, got ${sha256}`) + process.exit(1) +} + +await fs.mkdir(dirname(LIB_TARGET), { recursive: true }).catch(() => null) +await fs.writeFile(LIB_TARGET, dts) +console.log('lib.deno.d.ts updated') diff --git a/scripts/publish.js b/scripts/publish.js index e07c75c2..d3a483f4 100644 --- a/scripts/publish.js +++ b/scripts/publish.js @@ -25,6 +25,7 @@ const JSR_EXCEPTIONS = { bun: 'never', 'create-bot': 'never', 'crypto-node': 'never', + deno: 'only', node: 'never', 'http-proxy': 'never', 'socks-proxy': 'never', diff --git a/scripts/remove-jsr-sourcefiles.mjs b/scripts/remove-jsr-sourcefiles.mjs new file mode 100644 index 00000000..3ed84a26 --- /dev/null +++ b/scripts/remove-jsr-sourcefiles.mjs @@ -0,0 +1,23 @@ +import * as fs from 'fs' +import { globSync } from 'glob' +import { join } from 'path' +import { fileURLToPath } from 'url' + +// for whatever reason, jsr's npm compatibility jayer doesn't remove +// original typescript source files, which results in type errors when +// trying to build the project. this script removes all source files from @jsr/* +// https://discord.com/channels/684898665143206084/1203185670508515399/1234222204044967967 + +const nodeModules = fileURLToPath(new URL('../node_modules', import.meta.url)) + +let count = 0 + +for (const file of globSync(join(nodeModules, '.pnpm/**/node_modules/@jsr/**/*.ts'))) { + if (file.endsWith('.d.ts')) continue + if (!fs.existsSync(file)) continue + + fs.unlinkSync(file) + count++ +} + +console.log(`[jsr] removed ${count} source files`) diff --git a/tsconfig.json b/tsconfig.json index 92538b93..326dd224 100644 --- a/tsconfig.json +++ b/tsconfig.json @@ -19,6 +19,7 @@ "composite": true, "types": [ "node", + "deno", "vite/client" ], "lib": [ From b1b79e2ab142239484b90fa46e136a21e7536ec1 Mon Sep 17 00:00:00 2001 From: alina sireneva Date: Mon, 29 Apr 2024 01:36:42 +0300 Subject: [PATCH 02/10] test(e2e-deno): populate packages from upstream --- e2e/deno/cli.sh | 2 +- package.json | 2 +- packages/deno/build.config.cjs | 13 ++++++++++- packages/deno/src/client.ts | 3 ++- packages/deno/src/utils/crypto.ts | 2 +- packages/deno/src/utils/tcp.ts | 2 +- packages/deno/src/worker.ts | 9 +++++-- packages/web/src/idb/driver.ts | 7 +++--- packages/web/src/worker.ts | 12 ++++++---- pnpm-lock.yaml | 39 +++++++++++++++++++++++++++---- scripts/build-package.js | 30 ++++++++++++++++++++++++ scripts/publish.js | 32 +++++-------------------- 12 files changed, 107 insertions(+), 46 deletions(-) diff --git a/e2e/deno/cli.sh b/e2e/deno/cli.sh index 7d6afda7..e314f000 100755 --- a/e2e/deno/cli.sh +++ b/e2e/deno/cli.sh @@ -69,7 +69,7 @@ case "$method" in if [ -d .jsr-data ]; then # clean up data from previous runs docker compose down - rm -rf .jsr-data + sudo rm -rf .jsr-data fi mkdir .jsr-data ./cli.sh start diff --git a/package.json b/package.json index ff338996..3838a56b 100644 --- a/package.json +++ b/package.json @@ -35,7 +35,7 @@ "devDependencies": { "@commitlint/cli": "17.6.5", "@commitlint/config-conventional": "17.6.5", - "@teidesu/slow-types-compiler": "1.0.2", + "@teidesu/slow-types-compiler": "1.1.0", "@types/node": "20.10.0", "@types/ws": "8.5.4", "@typescript-eslint/eslint-plugin": "6.4.0", diff --git a/packages/deno/build.config.cjs b/packages/deno/build.config.cjs index 17718026..f8e7735c 100644 --- a/packages/deno/build.config.cjs +++ b/packages/deno/build.config.cjs @@ -1 +1,12 @@ -module.exports = () => ({ buildCjs: false }) +module.exports = ({ outDir, fs, jsr }) => ({ + buildCjs: false, + final() { + if (jsr) { + // jsr doesn't support symlinks, so we need to copy the files manually + const real = fs.realpathSync(`${outDir}/common-internals-web`) + fs.unlinkSync(`${outDir}/common-internals-web`) + // console.log(real) + fs.cpSync(real, `${outDir}/common-internals-web`, { recursive: true }) + } + }, +}) diff --git a/packages/deno/src/client.ts b/packages/deno/src/client.ts index 32a03e96..e36e1b21 100644 --- a/packages/deno/src/client.ts +++ b/packages/deno/src/client.ts @@ -87,7 +87,8 @@ export class TelegramClient extends TelegramClientBase { this._rl = createInterface({ // eslint-disable-next-line input: Readable.fromWeb(Deno.stdin.readable as any), - output: Writable.fromWeb(Deno.stdout.writable), + // eslint-disable-next-line + output: Writable.fromWeb(Deno.stdout.writable as any), }) } diff --git a/packages/deno/src/utils/crypto.ts b/packages/deno/src/utils/crypto.ts index 04b7b21b..9c08a6ed 100644 --- a/packages/deno/src/utils/crypto.ts +++ b/packages/deno/src/utils/crypto.ts @@ -1,10 +1,10 @@ -/* eslint-disable no-restricted-globals */ import { Buffer } from 'node:buffer' import { createCipheriv, createHash, createHmac, pbkdf2 } from 'node:crypto' import { deflateSync, gunzipSync } from 'node:zlib' import { BaseCryptoProvider, IAesCtr, ICryptoProvider, IEncryptionScheme } from '@mtcute/core/utils.js' import { getWasmUrl, ige256Decrypt, ige256Encrypt, initSync } from '@mtcute/wasm' + // node:crypto is properly implemented in deno, so we can just use it // largely just copy-pasting from @mtcute/node diff --git a/packages/deno/src/utils/tcp.ts b/packages/deno/src/utils/tcp.ts index 0bdcd6ef..848ded1e 100644 --- a/packages/deno/src/utils/tcp.ts +++ b/packages/deno/src/utils/tcp.ts @@ -1,4 +1,4 @@ -import EventEmitter from 'events' +import EventEmitter from 'node:events' import { IntermediatePacketCodec, IPacketCodec, ITelegramTransport, MtcuteError, TransportState } from '@mtcute/core' import { BasicDcOption, ICryptoProvider, Logger } from '@mtcute/core/utils.js' diff --git a/packages/deno/src/worker.ts b/packages/deno/src/worker.ts index 64e34db3..852a362d 100644 --- a/packages/deno/src/worker.ts +++ b/packages/deno/src/worker.ts @@ -1,4 +1,5 @@ -/// +/* eslint-disable @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-assignment */ +/* eslint-disable @typescript-eslint/no-unsafe-call */ import { setPlatform } from '@mtcute/core/platform.js' import { ClientMessageHandler, @@ -19,6 +20,10 @@ export type { TelegramWorkerOptions, TelegramWorkerPortOptions, WorkerCustomMeth let _registered = false +// thanks deno for this awesome lack of typings +declare const WorkerGlobalScope: any +declare const self: any + export class TelegramWorker extends TelegramWorkerBase { registerWorker(handler: WorkerMessageHandler): RespondFn { if (_registered) { @@ -31,7 +36,7 @@ export class TelegramWorker extends TelegramWorke const respond: RespondFn = self.postMessage.bind(self) // eslint-disable-next-line - self.addEventListener('message', (message) => handler((message as any).data, respond)) + self.addEventListener('message', (message: any) => handler(message.data, respond)) return respond } diff --git a/packages/web/src/idb/driver.ts b/packages/web/src/idb/driver.ts index 7a26d5df..73a6d431 100644 --- a/packages/web/src/idb/driver.ts +++ b/packages/web/src/idb/driver.ts @@ -1,5 +1,3 @@ -/// -/// import { BaseStorageDriver, MtUnsupportedError } from '@mtcute/core' import { txToPromise } from './utils.js' @@ -117,7 +115,8 @@ export class IdbStorageDriver extends BaseStorageDriver { db.createObjectStore(`${REPO_VERSION_PREFIX}${repo}:${targetVer}`) } - for (const key of db.objectStoreNames) { + // eslint-disable-next-line @typescript-eslint/no-explicit-any + for (const key of db.objectStoreNames as any as string[]) { if (!key.startsWith(REPO_VERSION_PREFIX)) continue const [, repo, version] = key.split(':') @@ -144,7 +143,7 @@ export class IdbStorageDriver extends BaseStorageDriver { this._pendingWrites = [] this._pendingWritesOses = new Set() - const tx = this.db.transaction(oses, 'readwrite') + const tx = this.db.transaction([...oses], 'readwrite') const osMap = new Map() diff --git a/packages/web/src/worker.ts b/packages/web/src/worker.ts index 23f9dcfc..6d1cf220 100644 --- a/packages/web/src/worker.ts +++ b/packages/web/src/worker.ts @@ -1,5 +1,4 @@ -/// -/// +/* eslint-disable @typescript-eslint/no-explicit-any */ import { setPlatform } from '@mtcute/core/platform.js' import { ClientMessageHandler, @@ -20,6 +19,11 @@ export type { TelegramWorkerOptions, TelegramWorkerPortOptions, WorkerCustomMeth let _registered = false +// thanks deno for this awesome lack of typings +declare const WorkerGlobalScope: any +declare const SharedWorkerGlobalScope: any +declare const self: any + export class TelegramWorker extends TelegramWorkerBase { registerWorker(handler: WorkerMessageHandler): RespondFn { if (_registered) { @@ -37,7 +41,7 @@ export class TelegramWorker extends TelegramWorke } } - self.onconnect = (event) => { + self.onconnect = (event: MessageEvent) => { const port = event.ports[0] connections.push(port) @@ -93,7 +97,7 @@ export class TelegramWorker extends TelegramWorke const respond: RespondFn = self.postMessage.bind(self) // eslint-disable-next-line @typescript-eslint/no-unsafe-argument - self.addEventListener('message', (message) => handler(message.data, respond)) + self.addEventListener('message', (message: MessageEvent) => handler(message.data, respond)) return respond } diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index e52cc9e7..f4902c33 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -19,8 +19,8 @@ importers: specifier: 17.6.5 version: 17.6.5 '@teidesu/slow-types-compiler': - specifier: 1.0.2 - version: 1.0.2(typescript@5.4.3) + specifier: 1.1.0 + version: 1.1.0(typescript@5.4.3) '@types/node': specifier: 20.10.0 version: 20.10.0 @@ -1467,8 +1467,8 @@ packages: /@sinclair/typebox@0.27.8: resolution: {integrity: sha512-+Fj43pSMwJs4KRrH/938Uf+uAELIgVBmQzg/q1YG10djyfA3TnrU8N8XzqCh/okZdszqBQTZf96idMfE5lnwTA==} - /@teidesu/slow-types-compiler@1.0.2(typescript@5.4.3): - resolution: {integrity: sha512-N0e3J/My4t405V5qD2kr6xXwLMlaB+el7bdYKLXJ2yyrLN1eAx4elf6qkeRTF4xy0GoiWrS0gKS0RZfddSOw1w==} + /@teidesu/slow-types-compiler@1.1.0(typescript@5.4.3): + resolution: {integrity: sha512-+WUHSKh56B32Jk5aJgXf07E2EOkMX1yilvgKLKBCJPFAJZ4xeo1U5aDu3wwHX3lrFl7AiVGXUP+FfuHy8X43BA==} hasBin: true peerDependencies: typescript: ^5.0.0 @@ -1476,6 +1476,7 @@ packages: arg: 5.0.2 dedent: 1.5.3 eager-async-pool: 1.0.0 + glob: 10.3.12 gunzip-maybe: 1.4.2 semver: 7.6.0 tar-stream: 3.1.7 @@ -3739,6 +3740,18 @@ packages: path-scurry: 1.10.1 dev: true + /glob@10.3.12: + resolution: {integrity: sha512-TCNv8vJ+xz4QiqTpfOJA7HvYv+tNIRHKfUWw/q+v2jdgN4ebz+KY9tGx5J4rHP0o84mNP+ApH66HRX8us3Khqg==} + engines: {node: '>=16 || 14 >=14.17'} + hasBin: true + dependencies: + foreground-child: 3.1.1 + jackspeak: 2.3.6 + minimatch: 9.0.3 + minipass: 7.0.4 + path-scurry: 1.10.2 + dev: true + /glob@7.2.0: resolution: {integrity: sha512-lmLf6gtyrPq8tTjSmrO94wBeQbFR3HbLHbuyD69wuyQkImp2hWqMGB47OX65FBkPffO641IP9jWa1z4ivqG26Q==} dependencies: @@ -4607,6 +4620,11 @@ packages: get-func-name: 2.0.2 dev: true + /lru-cache@10.2.2: + resolution: {integrity: sha512-9hp3Vp2/hFQUiIwKo8XCeFVnrg8Pk3TYNPIR7tJADKi5YfcF7vEaK7avFHTlSy3kOKYaJQaalfEo6YuXdceBOQ==} + engines: {node: 14 || >=16.14} + dev: true + /lru-cache@6.0.0: resolution: {integrity: sha512-Jo6dJ04CmSjuznwJSS3pUeWmd/H0ffTlkXXgwZi+eq1UCmqQwCh+eLsYOYCwY991i2Fah4h1BEMCx4qThGbsiA==} engines: {node: '>=10'} @@ -4852,6 +4870,11 @@ packages: resolution: {integrity: sha512-MzWSV5nYVT7mVyWCwn2o7JH13w2TBRmmSqSRCKzTw+lmft9X4z+3wjvs06Tzijo5z4W/kahUCDpRXTF+ZrmF/w==} engines: {node: '>=16 || 14 >=14.17'} + /minipass@7.0.4: + resolution: {integrity: sha512-jYofLM5Dam9279rdkWzqHozUo4ybjdZmCsDHePy5V/PbBcVMiSZR97gmAy45aqi8CK1lG2ECd356FU86avfwUQ==} + engines: {node: '>=16 || 14 >=14.17'} + dev: true + /minizlib@2.1.2: resolution: {integrity: sha512-bAxsR8BVfj60DWXHE3u30oHzfl4G7khkSuPW+qvpd7jFRHm7dLxOjUk1EHACJ/hxLY8phGJ0YhYHZo7jil7Qdg==} engines: {node: '>= 8'} @@ -5303,6 +5326,14 @@ packages: lru-cache: 9.1.2 minipass: 6.0.2 + /path-scurry@1.10.2: + resolution: {integrity: sha512-7xTavNy5RQXnsjANvVvMkEjvloOinkAjv/Z6Ildz9v2RinZ4SBKTWFOVRbaF8p0vpHnyjV/UwNDdKuUv6M5qcA==} + engines: {node: '>=16 || 14 >=14.17'} + dependencies: + lru-cache: 10.2.2 + minipass: 7.0.4 + dev: true + /path-type@4.0.0: resolution: {integrity: sha512-gDKb8aZMDeD/tZWs9P6+q0J9Mwkdl6xMV8TjnGP3qJVJ06bdMgkbBlLU8IdfOsIsFz2BW1rNVT3XuNEl8zPAvw==} engines: {node: '>=8'} diff --git a/scripts/build-package.js b/scripts/build-package.js index c5898ad6..892304b8 100644 --- a/scripts/build-package.js +++ b/scripts/build-package.js @@ -433,6 +433,8 @@ if (buildConfig.buildTs && !IS_JSR) { for (const [name, decl_] of Object.entries(nodeSpecificApis)) { if (fileContent.includes(name)) { + if (name === 'Buffer' && fileContent.includes('node:buffer')) continue + changed = true const isType = Array.isArray(decl_) && decl_[0] === 'type' const decl = isType ? decl_[1] : decl_ @@ -547,6 +549,34 @@ if (IS_JSR) { ), ) + if (process.env.E2E) { + // populate dependencies, if any + const depsToPopulate = [] + + for (const dep of Object.values(importMap)) { + if (!dep.startsWith('jsr:')) continue + if (dep.startsWith('jsr:@mtcute/')) continue + depsToPopulate.push(dep.slice(4)) + } + + if (depsToPopulate.length) { + console.log('[i] Populating %d dependencies...', depsToPopulate.length) + cp.spawnSync('pnpm', [ + 'exec', + 'slow-types-compiler', + 'populate', + '--downstream', + process.env.JSR_URL, + '--token', + process.env.JSR_TOKEN, + '--unstable-create-via-api', + ...depsToPopulate, + ], { + stdio: 'inherit', + }) + } + } + console.log('[i] Processing with slow-types-compiler...') const project = stc.createProject() stc.processPackage(project, denoJson) diff --git a/scripts/publish.js b/scripts/publish.js index d3a483f4..f6454788 100644 --- a/scripts/publish.js +++ b/scripts/publish.js @@ -1,6 +1,7 @@ const fs = require('fs') const path = require('path') const cp = require('child_process') +const stc = require('@teidesu/slow-types-compiler') const IS_JSR = process.env.JSR === '1' const MAIN_REGISTRY = IS_JSR ? 'http://jsr.test/' : 'https://registry.npmjs.org' @@ -54,30 +55,6 @@ async function checkVersion(name, version) { return fetchRetry(url).then((r) => r.status === 200) } -async function jsrMaybeCreatePackage(name) { - // check if the package even exists - const packageMeta = await fetchRetry(`${REGISTRY}api/scopes/mtcute/packages/${name}`) - - if (packageMeta.status === 404) { - console.error('[i] %s does not exist, creating..', name) - - const create = await fetchRetry(`${REGISTRY}api/scopes/mtcute/packages`, { - method: 'POST', - headers: { - 'Content-Type': 'application/json', - Cookie: `token=${process.env.JSR_TOKEN}`, - }, - body: JSON.stringify({ package: name }), - }) - - if (create.status !== 200) { - throw new Error(`Failed to create package: ${create.statusText} ${await create.text()}`) - } - } else if (packageMeta.status !== 200) { - throw new Error(`Failed to check package: ${packageMeta.statusText} ${await packageMeta.text()}`) - } -} - async function publishSinglePackage(name) { let packageDir = path.join(__dirname, '../packages', name) @@ -110,7 +87,11 @@ async function publishSinglePackage(name) { return } } else if (IS_JSR && process.env.JSR_TOKEN) { - await jsrMaybeCreatePackage(name) + await stc.jsrMaybeCreatePackage({ + name: `@mtcute/${name}`, + token: process.env.JSR_TOKEN, + registry: REGISTRY, + }) } if (IS_JSR) { @@ -157,7 +138,6 @@ function listPackages() { .map((d) => d.slice(8)) } - const stc = require('@teidesu/slow-types-compiler') packages = stc.determinePublishOrder(map) console.log('[i] Publishing order:', packages.join(', ')) } From 67b290643d1c8de18644d58813059ba6216a2da0 Mon Sep 17 00:00:00 2001 From: alina sireneva Date: Mon, 29 Apr 2024 05:50:18 +0300 Subject: [PATCH 03/10] build: use a stripped down non-conflicting version of lib.deno.d.ts instead --- package.json | 2 +- .../highlevel/methods/files/upload-file.ts | 3 +- .../core/src/highlevel/worker/protocol.ts | 1 - packages/core/src/utils/error-reporting.ts | 3 +- packages/deno/src/worker.ts | 8 +- packages/web/src/idb/driver.ts | 5 +- packages/web/src/worker.ts | 6 - scripts/build-package.js | 36 +- scripts/fetch-deno-dts.mjs | 33 - scripts/install-deno-dts.mjs | 16 + scripts/lib.deno.d.ts | 9038 +++++++++++++++++ 11 files changed, 9083 insertions(+), 68 deletions(-) delete mode 100644 scripts/fetch-deno-dts.mjs create mode 100644 scripts/install-deno-dts.mjs create mode 100644 scripts/lib.deno.d.ts diff --git a/package.json b/package.json index 3838a56b..c77fef8c 100644 --- a/package.json +++ b/package.json @@ -10,7 +10,7 @@ ], "scripts": { "prepare": "husky install .config/husky", - "postinstall": "node scripts/validate-deps-versions.mjs && node scripts/fetch-deno-dts.mjs && node scripts/remove-jsr-sourcefiles.mjs", + "postinstall": "node scripts/validate-deps-versions.mjs && node scripts/install-deno-dts.mjs && node scripts/remove-jsr-sourcefiles.mjs", "test": "pnpm run -r test && vitest --config .config/vite.mts run", "test:dev": "vitest --config .config/vite.mts watch", "test:ui": "vitest --config .config/vite.mts --ui", diff --git a/packages/core/src/highlevel/methods/files/upload-file.ts b/packages/core/src/highlevel/methods/files/upload-file.ts index 0b4b5658..eb74837d 100644 --- a/packages/core/src/highlevel/methods/files/upload-file.ts +++ b/packages/core/src/highlevel/methods/files/upload-file.ts @@ -171,8 +171,7 @@ export async function uploadFile( throw new MtArgumentError('Fetch response contains `null` body') } - // eslint-disable-next-line @typescript-eslint/no-unnecessary-type-assertion - file = file.body as ReadableStream + file = file.body } if (!(file instanceof ReadableStream)) { diff --git a/packages/core/src/highlevel/worker/protocol.ts b/packages/core/src/highlevel/worker/protocol.ts index 2f9b61d8..4a603578 100644 --- a/packages/core/src/highlevel/worker/protocol.ts +++ b/packages/core/src/highlevel/worker/protocol.ts @@ -1,4 +1,3 @@ -/// import type { Worker as NodeWorker } from 'node:worker_threads' import { tl } from '@mtcute/tl' diff --git a/packages/core/src/utils/error-reporting.ts b/packages/core/src/utils/error-reporting.ts index 0f219153..7c9470e9 100644 --- a/packages/core/src/utils/error-reporting.ts +++ b/packages/core/src/utils/error-reporting.ts @@ -7,8 +7,7 @@ export function reportUnknownError(log: Logger, error: tl.RpcError, method: stri fetch(`https://rpc.pwrtelegram.xyz/?code=${error.code}&method=${method}&error=${error.text}`) .then((r) => r.json()) - // eslint-disable-next-line @typescript-eslint/no-explicit-any - .then((r: any) => { + .then((r) => { if (r.ok) { log.info('telerpc responded with error info for %s: %s', error.text, r.result) } else { diff --git a/packages/deno/src/worker.ts b/packages/deno/src/worker.ts index 852a362d..facc7363 100644 --- a/packages/deno/src/worker.ts +++ b/packages/deno/src/worker.ts @@ -1,5 +1,3 @@ -/* eslint-disable @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-assignment */ -/* eslint-disable @typescript-eslint/no-unsafe-call */ import { setPlatform } from '@mtcute/core/platform.js' import { ClientMessageHandler, @@ -20,10 +18,6 @@ export type { TelegramWorkerOptions, TelegramWorkerPortOptions, WorkerCustomMeth let _registered = false -// thanks deno for this awesome lack of typings -declare const WorkerGlobalScope: any -declare const self: any - export class TelegramWorker extends TelegramWorkerBase { registerWorker(handler: WorkerMessageHandler): RespondFn { if (_registered) { @@ -36,7 +30,7 @@ export class TelegramWorker extends TelegramWorke const respond: RespondFn = self.postMessage.bind(self) // eslint-disable-next-line - self.addEventListener('message', (message: any) => handler(message.data, respond)) + self.addEventListener('message', (message) => handler(message.data, respond)) return respond } diff --git a/packages/web/src/idb/driver.ts b/packages/web/src/idb/driver.ts index 73a6d431..a35d7a1f 100644 --- a/packages/web/src/idb/driver.ts +++ b/packages/web/src/idb/driver.ts @@ -115,8 +115,7 @@ export class IdbStorageDriver extends BaseStorageDriver { db.createObjectStore(`${REPO_VERSION_PREFIX}${repo}:${targetVer}`) } - // eslint-disable-next-line @typescript-eslint/no-explicit-any - for (const key of db.objectStoreNames as any as string[]) { + for (const key of db.objectStoreNames) { if (!key.startsWith(REPO_VERSION_PREFIX)) continue const [, repo, version] = key.split(':') @@ -143,7 +142,7 @@ export class IdbStorageDriver extends BaseStorageDriver { this._pendingWrites = [] this._pendingWritesOses = new Set() - const tx = this.db.transaction([...oses], 'readwrite') + const tx = this.db.transaction(oses, 'readwrite') const osMap = new Map() diff --git a/packages/web/src/worker.ts b/packages/web/src/worker.ts index 6d1cf220..5e38206f 100644 --- a/packages/web/src/worker.ts +++ b/packages/web/src/worker.ts @@ -1,4 +1,3 @@ -/* eslint-disable @typescript-eslint/no-explicit-any */ import { setPlatform } from '@mtcute/core/platform.js' import { ClientMessageHandler, @@ -19,11 +18,6 @@ export type { TelegramWorkerOptions, TelegramWorkerPortOptions, WorkerCustomMeth let _registered = false -// thanks deno for this awesome lack of typings -declare const WorkerGlobalScope: any -declare const SharedWorkerGlobalScope: any -declare const self: any - export class TelegramWorker extends TelegramWorkerBase { registerWorker(handler: WorkerMessageHandler): RespondFn { if (_registered) { diff --git a/scripts/build-package.js b/scripts/build-package.js index 892304b8..151c2075 100644 --- a/scripts/build-package.js +++ b/scripts/build-package.js @@ -428,6 +428,12 @@ if (buildConfig.buildTs && !IS_JSR) { 'from: (data: any, encoding?: string) => { toString(encoding?: string): string }, ' + ' }', SharedWorker: ['type', 'never'], + WorkerGlobalScope: + '{ ' + + ' new (): typeof WorkerGlobalScope, ' + + ' postMessage: (message: any, transfer?: Transferable[]) => void, ' + + ' addEventListener: (type: "message", listener: (ev: MessageEvent) => void) => void, ' + + ' }', process: '{ ' + 'hrtime: { bigint: () => bigint }, ' + '}', } @@ -561,19 +567,23 @@ if (IS_JSR) { if (depsToPopulate.length) { console.log('[i] Populating %d dependencies...', depsToPopulate.length) - cp.spawnSync('pnpm', [ - 'exec', - 'slow-types-compiler', - 'populate', - '--downstream', - process.env.JSR_URL, - '--token', - process.env.JSR_TOKEN, - '--unstable-create-via-api', - ...depsToPopulate, - ], { - stdio: 'inherit', - }) + cp.spawnSync( + 'pnpm', + [ + 'exec', + 'slow-types-compiler', + 'populate', + '--downstream', + process.env.JSR_URL, + '--token', + process.env.JSR_TOKEN, + '--unstable-create-via-api', + ...depsToPopulate, + ], + { + stdio: 'inherit', + }, + ) } } diff --git a/scripts/fetch-deno-dts.mjs b/scripts/fetch-deno-dts.mjs deleted file mode 100644 index 89e7e90d..00000000 --- a/scripts/fetch-deno-dts.mjs +++ /dev/null @@ -1,33 +0,0 @@ -import { createHash } from 'crypto' -import * as fs from 'fs/promises' -import { dirname } from 'path' -import { fileURLToPath } from 'url' - -const DTS_URL = 'https://github.com/denoland/deno/releases/download/v1.42.4/lib.deno.d.ts' -const SHA256 = '554b5da7baf05e5693ca064fcf1665b0b847743ccfd0db89cb6f2388f2de0276' -const LIB_TARGET = fileURLToPath(new URL('../node_modules/@types/deno/index.d.ts', import.meta.url)) - -const stat = await fs.stat(LIB_TARGET).catch(() => null) - -if (stat?.isFile()) { - const sha256 = createHash('sha256').update(await fs.readFile(LIB_TARGET)).digest('hex') - - if (sha256 === SHA256) { - console.log('lib.deno.d.ts is up to date') - process.exit(0) - } -} - -const stream = await fetch(DTS_URL) -const dts = await stream.text() - -const sha256 = createHash('sha256').update(dts).digest('hex') - -if (sha256 !== SHA256) { - console.error(`lib.deno.d.ts SHA256 mismatch: expected ${SHA256}, got ${sha256}`) - process.exit(1) -} - -await fs.mkdir(dirname(LIB_TARGET), { recursive: true }).catch(() => null) -await fs.writeFile(LIB_TARGET, dts) -console.log('lib.deno.d.ts updated') diff --git a/scripts/install-deno-dts.mjs b/scripts/install-deno-dts.mjs new file mode 100644 index 00000000..514ee596 --- /dev/null +++ b/scripts/install-deno-dts.mjs @@ -0,0 +1,16 @@ +import * as fs from 'fs/promises' +import { dirname } from 'path' +import { fileURLToPath } from 'url' + +const LIB_SOURCE = fileURLToPath(new URL('./lib.deno.d.ts', import.meta.url)) +const LIB_TARGET = fileURLToPath(new URL('../node_modules/@types/deno/index.d.ts', import.meta.url)) + +await fs.mkdir(dirname(LIB_TARGET), { recursive: true }) + +if (await fs.stat(LIB_TARGET).catch(() => null)) { + await fs.unlink(LIB_TARGET) +} + +await fs.symlink(LIB_SOURCE, LIB_TARGET) + +console.log('lib.deno.d.ts linked') diff --git a/scripts/lib.deno.d.ts b/scripts/lib.deno.d.ts new file mode 100644 index 00000000..5145934a --- /dev/null +++ b/scripts/lib.deno.d.ts @@ -0,0 +1,9038 @@ +/* eslint-disable */ +// Copyright 2018-2024 the Deno authors. All rights reserved. MIT license. + +// this file is a stipped down version of lib.deno.d.ts from 1.42.4 +// original lib.deno.d.ts re-defines web apis, but we want to avoid interfering with the rest of the typings +// and use typescript's lib.dom.d.ts instead + +/** The global namespace where Deno specific, non-standard APIs are located. */ +declare namespace Deno { + /** A set of error constructors that are raised by Deno APIs. + * + * Can be used to provide more specific handling of failures within code + * which is using Deno APIs. For example, handling attempting to open a file + * which does not exist: + * + * ```ts + * try { + * const file = await Deno.open("./some/file.txt"); + * } catch (error) { + * if (error instanceof Deno.errors.NotFound) { + * console.error("the file was not found"); + * } else { + * // otherwise re-throw + * throw error; + * } + * } + * ``` + * + * @category Errors + */ + export namespace errors { + /** + * Raised when the underlying operating system indicates that the file + * was not found. + * + * @category Errors */ + export class NotFound extends Error {} + /** + * Raised when the underlying operating system indicates the current user + * which the Deno process is running under does not have the appropriate + * permissions to a file or resource, or the user _did not_ provide required + * `--allow-*` flag. + * + * @category Errors */ + export class PermissionDenied extends Error {} + /** + * Raised when the underlying operating system reports that a connection to + * a resource is refused. + * + * @category Errors */ + export class ConnectionRefused extends Error {} + /** + * Raised when the underlying operating system reports that a connection has + * been reset. With network servers, it can be a _normal_ occurrence where a + * client will abort a connection instead of properly shutting it down. + * + * @category Errors */ + export class ConnectionReset extends Error {} + /** + * Raised when the underlying operating system reports an `ECONNABORTED` + * error. + * + * @category Errors */ + export class ConnectionAborted extends Error {} + /** + * Raised when the underlying operating system reports an `ENOTCONN` error. + * + * @category Errors */ + export class NotConnected extends Error {} + /** + * Raised when attempting to open a server listener on an address and port + * that already has a listener. + * + * @category Errors */ + export class AddrInUse extends Error {} + /** + * Raised when the underlying operating system reports an `EADDRNOTAVAIL` + * error. + * + * @category Errors */ + export class AddrNotAvailable extends Error {} + /** + * Raised when trying to write to a resource and a broken pipe error occurs. + * This can happen when trying to write directly to `stdout` or `stderr` + * and the operating system is unable to pipe the output for a reason + * external to the Deno runtime. + * + * @category Errors */ + export class BrokenPipe extends Error {} + /** + * Raised when trying to create a resource, like a file, that already + * exits. + * + * @category Errors */ + export class AlreadyExists extends Error {} + /** + * Raised when an operation to returns data that is invalid for the + * operation being performed. + * + * @category Errors */ + export class InvalidData extends Error {} + /** + * Raised when the underlying operating system reports that an I/O operation + * has timed out (`ETIMEDOUT`). + * + * @category Errors */ + export class TimedOut extends Error {} + /** + * Raised when the underlying operating system reports an `EINTR` error. In + * many cases, this underlying IO error will be handled internally within + * Deno, or result in an @{link BadResource} error instead. + * + * @category Errors */ + export class Interrupted extends Error {} + /** + * Raised when the underlying operating system would need to block to + * complete but an asynchronous (non-blocking) API is used. + * + * @category Errors */ + export class WouldBlock extends Error {} + /** + * Raised when expecting to write to a IO buffer resulted in zero bytes + * being written. + * + * @category Errors */ + export class WriteZero extends Error {} + /** + * Raised when attempting to read bytes from a resource, but the EOF was + * unexpectedly encountered. + * + * @category Errors */ + export class UnexpectedEof extends Error {} + /** + * The underlying IO resource is invalid or closed, and so the operation + * could not be performed. + * + * @category Errors */ + export class BadResource extends Error {} + /** + * Raised in situations where when attempting to load a dynamic import, + * too many redirects were encountered. + * + * @category Errors */ + export class Http extends Error {} + /** + * Raised when the underlying IO resource is not available because it is + * being awaited on in another block of code. + * + * @category Errors */ + export class Busy extends Error {} + /** + * Raised when the underlying Deno API is asked to perform a function that + * is not currently supported. + * + * @category Errors */ + export class NotSupported extends Error {} + /** + * Raised when too many symbolic links were encountered when resolving the + * filename. + * + * @category Errors */ + export class FilesystemLoop extends Error {} + /** + * Raised when trying to open, create or write to a directory. + * + * @category Errors */ + export class IsADirectory extends Error {} + /** + * Raised when performing a socket operation but the remote host is + * not reachable. + * + * @category Errors */ + export class NetworkUnreachable extends Error {} + /** + * Raised when trying to perform an operation on a path that is not a + * directory, when directory is required. + * + * @category Errors */ + export class NotADirectory extends Error {} + } + + /** The current process ID of this instance of the Deno CLI. + * + * ```ts + * console.log(Deno.pid); + * ``` + * + * @category Runtime Environment + */ + export const pid: number; + + /** + * The process ID of parent process of this instance of the Deno CLI. + * + * ```ts + * console.log(Deno.ppid); + * ``` + * + * @category Runtime Environment + */ + export const ppid: number; + + /** @category Runtime Environment */ + export interface MemoryUsage { + /** The number of bytes of the current Deno's process resident set size, + * which is the amount of memory occupied in main memory (RAM). */ + rss: number; + /** The total size of the heap for V8, in bytes. */ + heapTotal: number; + /** The amount of the heap used for V8, in bytes. */ + heapUsed: number; + /** Memory, in bytes, associated with JavaScript objects outside of the + * JavaScript isolate. */ + external: number; + } + + /** + * Returns an object describing the memory usage of the Deno process and the + * V8 subsystem measured in bytes. + * + * @category Runtime Environment + */ + export function memoryUsage(): MemoryUsage; + + /** + * Get the `hostname` of the machine the Deno process is running on. + * + * ```ts + * console.log(Deno.hostname()); + * ``` + * + * Requires `allow-sys` permission. + * + * @tags allow-sys + * @category Runtime Environment + */ + export function hostname(): string; + + /** + * Returns an array containing the 1, 5, and 15 minute load averages. The + * load average is a measure of CPU and IO utilization of the last one, five, + * and 15 minute periods expressed as a fractional number. Zero means there + * is no load. On Windows, the three values are always the same and represent + * the current load, not the 1, 5 and 15 minute load averages. + * + * ```ts + * console.log(Deno.loadavg()); // e.g. [ 0.71, 0.44, 0.44 ] + * ``` + * + * Requires `allow-sys` permission. + * + * On Windows there is no API available to retrieve this information and this method returns `[ 0, 0, 0 ]`. + * + * @tags allow-sys + * @category Observability + */ + export function loadavg(): number[]; + + /** + * The information for a network interface returned from a call to + * {@linkcode Deno.networkInterfaces}. + * + * @category Network + */ + export interface NetworkInterfaceInfo { + /** The network interface name. */ + name: string; + /** The IP protocol version. */ + family: "IPv4" | "IPv6"; + /** The IP address bound to the interface. */ + address: string; + /** The netmask applied to the interface. */ + netmask: string; + /** The IPv6 scope id or `null`. */ + scopeid: number | null; + /** The CIDR range. */ + cidr: string; + /** The MAC address. */ + mac: string; + } + + /** + * Returns an array of the network interface information. + * + * ```ts + * console.log(Deno.networkInterfaces()); + * ``` + * + * Requires `allow-sys` permission. + * + * @tags allow-sys + * @category Network + */ + export function networkInterfaces(): NetworkInterfaceInfo[]; + + /** + * Displays the total amount of free and used physical and swap memory in the + * system, as well as the buffers and caches used by the kernel. + * + * This is similar to the `free` command in Linux + * + * ```ts + * console.log(Deno.systemMemoryInfo()); + * ``` + * + * Requires `allow-sys` permission. + * + * @tags allow-sys + * @category Runtime Environment + */ + export function systemMemoryInfo(): SystemMemoryInfo; + + /** + * Information returned from a call to {@linkcode Deno.systemMemoryInfo}. + * + * @category Runtime Environment + */ + export interface SystemMemoryInfo { + /** Total installed memory in bytes. */ + total: number; + /** Unused memory in bytes. */ + free: number; + /** Estimation of how much memory, in bytes, is available for starting new + * applications, without swapping. Unlike the data provided by the cache or + * free fields, this field takes into account page cache and also that not + * all reclaimable memory will be reclaimed due to items being in use. + */ + available: number; + /** Memory used by kernel buffers. */ + buffers: number; + /** Memory used by the page cache and slabs. */ + cached: number; + /** Total swap memory. */ + swapTotal: number; + /** Unused swap memory. */ + swapFree: number; + } + + /** Reflects the `NO_COLOR` environment variable at program start. + * + * When the value is `true`, the Deno CLI will attempt to not send color codes + * to `stderr` or `stdout` and other command line programs should also attempt + * to respect this value. + * + * See: https://no-color.org/ + * + * @category Runtime Environment + */ + export const noColor: boolean; + + /** + * Returns the release version of the Operating System. + * + * ```ts + * console.log(Deno.osRelease()); + * ``` + * + * Requires `allow-sys` permission. + * Under consideration to possibly move to Deno.build or Deno.versions and if + * it should depend sys-info, which may not be desirable. + * + * @tags allow-sys + * @category Runtime Environment + */ + export function osRelease(): string; + + /** + * Returns the Operating System uptime in number of seconds. + * + * ```ts + * console.log(Deno.osUptime()); + * ``` + * + * Requires `allow-sys` permission. + * + * @tags allow-sys + * @category Runtime Environment + */ + export function osUptime(): number; + + /** + * Options which define the permissions within a test or worker context. + * + * `"inherit"` ensures that all permissions of the parent process will be + * applied to the test context. `"none"` ensures the test context has no + * permissions. A `PermissionOptionsObject` provides a more specific + * set of permissions to the test context. + * + * @category Permissions */ + export type PermissionOptions = + | "inherit" + | "none" + | PermissionOptionsObject; + + /** + * A set of options which can define the permissions within a test or worker + * context at a highly specific level. + * + * @category Permissions */ + export interface PermissionOptionsObject { + /** Specifies if the `env` permission should be requested or revoked. + * If set to `"inherit"`, the current `env` permission will be inherited. + * If set to `true`, the global `env` permission will be requested. + * If set to `false`, the global `env` permission will be revoked. + * + * @default {false} + */ + env?: "inherit" | boolean | string[]; + + /** Specifies if the `sys` permission should be requested or revoked. + * If set to `"inherit"`, the current `sys` permission will be inherited. + * If set to `true`, the global `sys` permission will be requested. + * If set to `false`, the global `sys` permission will be revoked. + * + * @default {false} + */ + sys?: "inherit" | boolean | string[]; + + /** Specifies if the `hrtime` permission should be requested or revoked. + * If set to `"inherit"`, the current `hrtime` permission will be inherited. + * If set to `true`, the global `hrtime` permission will be requested. + * If set to `false`, the global `hrtime` permission will be revoked. + * + * @default {false} + */ + hrtime?: "inherit" | boolean; + + /** Specifies if the `net` permission should be requested or revoked. + * if set to `"inherit"`, the current `net` permission will be inherited. + * if set to `true`, the global `net` permission will be requested. + * if set to `false`, the global `net` permission will be revoked. + * if set to `string[]`, the `net` permission will be requested with the + * specified host strings with the format `"[:]`. + * + * @default {false} + * + * Examples: + * + * ```ts + * import { assertEquals } from "jsr:@std/assert"; + * + * Deno.test({ + * name: "inherit", + * permissions: { + * net: "inherit", + * }, + * async fn() { + * const status = await Deno.permissions.query({ name: "net" }) + * assertEquals(status.state, "granted"); + * }, + * }); + * ``` + * + * ```ts + * import { assertEquals } from "jsr:@std/assert"; + * + * Deno.test({ + * name: "true", + * permissions: { + * net: true, + * }, + * async fn() { + * const status = await Deno.permissions.query({ name: "net" }); + * assertEquals(status.state, "granted"); + * }, + * }); + * ``` + * + * ```ts + * import { assertEquals } from "jsr:@std/assert"; + * + * Deno.test({ + * name: "false", + * permissions: { + * net: false, + * }, + * async fn() { + * const status = await Deno.permissions.query({ name: "net" }); + * assertEquals(status.state, "denied"); + * }, + * }); + * ``` + * + * ```ts + * import { assertEquals } from "jsr:@std/assert"; + * + * Deno.test({ + * name: "localhost:8080", + * permissions: { + * net: ["localhost:8080"], + * }, + * async fn() { + * const status = await Deno.permissions.query({ name: "net", host: "localhost:8080" }); + * assertEquals(status.state, "granted"); + * }, + * }); + * ``` + */ + net?: "inherit" | boolean | string[]; + + /** Specifies if the `ffi` permission should be requested or revoked. + * If set to `"inherit"`, the current `ffi` permission will be inherited. + * If set to `true`, the global `ffi` permission will be requested. + * If set to `false`, the global `ffi` permission will be revoked. + * + * @default {false} + */ + ffi?: "inherit" | boolean | Array; + + /** Specifies if the `read` permission should be requested or revoked. + * If set to `"inherit"`, the current `read` permission will be inherited. + * If set to `true`, the global `read` permission will be requested. + * If set to `false`, the global `read` permission will be revoked. + * If set to `Array`, the `read` permission will be requested with the + * specified file paths. + * + * @default {false} + */ + read?: "inherit" | boolean | Array; + + /** Specifies if the `run` permission should be requested or revoked. + * If set to `"inherit"`, the current `run` permission will be inherited. + * If set to `true`, the global `run` permission will be requested. + * If set to `false`, the global `run` permission will be revoked. + * + * @default {false} + */ + run?: "inherit" | boolean | Array; + + /** Specifies if the `write` permission should be requested or revoked. + * If set to `"inherit"`, the current `write` permission will be inherited. + * If set to `true`, the global `write` permission will be requested. + * If set to `false`, the global `write` permission will be revoked. + * If set to `Array`, the `write` permission will be requested with the + * specified file paths. + * + * @default {false} + */ + write?: "inherit" | boolean | Array; + } + + /** + * Context that is passed to a testing function, which can be used to either + * gain information about the current test, or register additional test + * steps within the current test. + * + * @category Testing */ + export interface TestContext { + /** The current test name. */ + name: string; + /** The string URL of the current test. */ + origin: string; + /** If the current test is a step of another test, the parent test context + * will be set here. */ + parent?: TestContext; + + /** Run a sub step of the parent test or step. Returns a promise + * that resolves to a boolean signifying if the step completed successfully. + * + * The returned promise never rejects unless the arguments are invalid. + * + * If the test was ignored the promise returns `false`. + * + * ```ts + * Deno.test({ + * name: "a parent test", + * async fn(t) { + * console.log("before the step"); + * await t.step({ + * name: "step 1", + * fn(t) { + * console.log("current step:", t.name); + * } + * }); + * console.log("after the step"); + * } + * }); + * ``` + */ + step(definition: TestStepDefinition): Promise; + + /** Run a sub step of the parent test or step. Returns a promise + * that resolves to a boolean signifying if the step completed successfully. + * + * The returned promise never rejects unless the arguments are invalid. + * + * If the test was ignored the promise returns `false`. + * + * ```ts + * Deno.test( + * "a parent test", + * async (t) => { + * console.log("before the step"); + * await t.step( + * "step 1", + * (t) => { + * console.log("current step:", t.name); + * } + * ); + * console.log("after the step"); + * } + * ); + * ``` + */ + step( + name: string, + fn: (t: TestContext) => void | Promise, + ): Promise; + + /** Run a sub step of the parent test or step. Returns a promise + * that resolves to a boolean signifying if the step completed successfully. + * + * The returned promise never rejects unless the arguments are invalid. + * + * If the test was ignored the promise returns `false`. + * + * ```ts + * Deno.test(async function aParentTest(t) { + * console.log("before the step"); + * await t.step(function step1(t) { + * console.log("current step:", t.name); + * }); + * console.log("after the step"); + * }); + * ``` + */ + step(fn: (t: TestContext) => void | Promise): Promise; + } + + /** @category Testing */ + export interface TestStepDefinition { + /** The test function that will be tested when this step is executed. The + * function can take an argument which will provide information about the + * current step's context. */ + fn: (t: TestContext) => void | Promise; + /** The name of the step. */ + name: string; + /** If truthy the current test step will be ignored. + * + * This is a quick way to skip over a step, but also can be used for + * conditional logic, like determining if an environment feature is present. + */ + ignore?: boolean; + /** Check that the number of async completed operations after the test step + * is the same as number of dispatched operations. This ensures that the + * code tested does not start async operations which it then does + * not await. This helps in preventing logic errors and memory leaks + * in the application code. + * + * Defaults to the parent test or step's value. */ + sanitizeOps?: boolean; + /** Ensure the test step does not "leak" resources - like open files or + * network connections - by ensuring the open resources at the start of the + * step match the open resources at the end of the step. + * + * Defaults to the parent test or step's value. */ + sanitizeResources?: boolean; + /** Ensure the test step does not prematurely cause the process to exit, + * for example via a call to {@linkcode Deno.exit}. + * + * Defaults to the parent test or step's value. */ + sanitizeExit?: boolean; + } + + /** @category Testing */ + export interface TestDefinition { + fn: (t: TestContext) => void | Promise; + /** The name of the test. */ + name: string; + /** If truthy the current test step will be ignored. + * + * It is a quick way to skip over a step, but also can be used for + * conditional logic, like determining if an environment feature is present. + */ + ignore?: boolean; + /** If at least one test has `only` set to `true`, only run tests that have + * `only` set to `true` and fail the test suite. */ + only?: boolean; + /** Check that the number of async completed operations after the test step + * is the same as number of dispatched operations. This ensures that the + * code tested does not start async operations which it then does + * not await. This helps in preventing logic errors and memory leaks + * in the application code. + * + * @default {true} */ + sanitizeOps?: boolean; + /** Ensure the test step does not "leak" resources - like open files or + * network connections - by ensuring the open resources at the start of the + * test match the open resources at the end of the test. + * + * @default {true} */ + sanitizeResources?: boolean; + /** Ensure the test case does not prematurely cause the process to exit, + * for example via a call to {@linkcode Deno.exit}. + * + * @default {true} */ + sanitizeExit?: boolean; + /** Specifies the permissions that should be used to run the test. + * + * Set this to "inherit" to keep the calling runtime permissions, set this + * to "none" to revoke all permissions, or set a more specific set of + * permissions using a {@linkcode PermissionOptionsObject}. + * + * @default {"inherit"} */ + permissions?: PermissionOptions; + } + + /** Register a test which will be run when `deno test` is used on the command + * line and the containing module looks like a test module. + * + * `fn` can be async if required. + * + * ```ts + * import { assertEquals } from "jsr:@std/assert"; + * + * Deno.test({ + * name: "example test", + * fn() { + * assertEquals("world", "world"); + * }, + * }); + * + * Deno.test({ + * name: "example ignored test", + * ignore: Deno.build.os === "windows", + * fn() { + * // This test is ignored only on Windows machines + * }, + * }); + * + * Deno.test({ + * name: "example async test", + * async fn() { + * const decoder = new TextDecoder("utf-8"); + * const data = await Deno.readFile("hello_world.txt"); + * assertEquals(decoder.decode(data), "Hello world"); + * } + * }); + * ``` + * + * @category Testing + */ + export const test: DenoTest; + + /** + * @category Testing + */ + interface DenoTest { + /** Register a test which will be run when `deno test` is used on the command + * line and the containing module looks like a test module. + * + * `fn` can be async if required. + * + * ```ts + * import { assertEquals } from "jsr:@std/assert"; + * + * Deno.test({ + * name: "example test", + * fn() { + * assertEquals("world", "world"); + * }, + * }); + * + * Deno.test({ + * name: "example ignored test", + * ignore: Deno.build.os === "windows", + * fn() { + * // This test is ignored only on Windows machines + * }, + * }); + * + * Deno.test({ + * name: "example async test", + * async fn() { + * const decoder = new TextDecoder("utf-8"); + * const data = await Deno.readFile("hello_world.txt"); + * assertEquals(decoder.decode(data), "Hello world"); + * } + * }); + * ``` + * + * @category Testing + */ + (t: TestDefinition): void; + + /** Register a test which will be run when `deno test` is used on the command + * line and the containing module looks like a test module. + * + * `fn` can be async if required. + * + * ```ts + * import { assertEquals } from "jsr:@std/assert"; + * + * Deno.test("My test description", () => { + * assertEquals("hello", "hello"); + * }); + * + * Deno.test("My async test description", async () => { + * const decoder = new TextDecoder("utf-8"); + * const data = await Deno.readFile("hello_world.txt"); + * assertEquals(decoder.decode(data), "Hello world"); + * }); + * ``` + * + * @category Testing + */ + ( + name: string, + fn: (t: TestContext) => void | Promise, + ): void; + + /** Register a test which will be run when `deno test` is used on the command + * line and the containing module looks like a test module. + * + * `fn` can be async if required. Declared function must have a name. + * + * ```ts + * import { assertEquals } from "jsr:@std/assert"; + * + * Deno.test(function myTestName() { + * assertEquals("hello", "hello"); + * }); + * + * Deno.test(async function myOtherTestName() { + * const decoder = new TextDecoder("utf-8"); + * const data = await Deno.readFile("hello_world.txt"); + * assertEquals(decoder.decode(data), "Hello world"); + * }); + * ``` + * + * @category Testing + */ + (fn: (t: TestContext) => void | Promise): void; + + /** Register a test which will be run when `deno test` is used on the command + * line and the containing module looks like a test module. + * + * `fn` can be async if required. + * + * ```ts + * import { assert, fail, assertEquals } from "jsr:@std/assert"; + * + * Deno.test("My test description", { permissions: { read: true } }, (): void => { + * assertEquals("hello", "hello"); + * }); + * + * Deno.test("My async test description", { permissions: { read: false } }, async (): Promise => { + * const decoder = new TextDecoder("utf-8"); + * const data = await Deno.readFile("hello_world.txt"); + * assertEquals(decoder.decode(data), "Hello world"); + * }); + * ``` + * + * @category Testing + */ + ( + name: string, + options: Omit, + fn: (t: TestContext) => void | Promise, + ): void; + + /** Register a test which will be run when `deno test` is used on the command + * line and the containing module looks like a test module. + * + * `fn` can be async if required. + * + * ```ts + * import { assertEquals } from "jsr:@std/assert"; + * + * Deno.test( + * { + * name: "My test description", + * permissions: { read: true }, + * }, + * () => { + * assertEquals("hello", "hello"); + * }, + * ); + * + * Deno.test( + * { + * name: "My async test description", + * permissions: { read: false }, + * }, + * async () => { + * const decoder = new TextDecoder("utf-8"); + * const data = await Deno.readFile("hello_world.txt"); + * assertEquals(decoder.decode(data), "Hello world"); + * }, + * ); + * ``` + * + * @category Testing + */ + ( + options: Omit, + fn: (t: TestContext) => void | Promise, + ): void; + + /** Register a test which will be run when `deno test` is used on the command + * line and the containing module looks like a test module. + * + * `fn` can be async if required. Declared function must have a name. + * + * ```ts + * import { assertEquals } from "jsr:@std/assert"; + * + * Deno.test( + * { permissions: { read: true } }, + * function myTestName() { + * assertEquals("hello", "hello"); + * }, + * ); + * + * Deno.test( + * { permissions: { read: false } }, + * async function myOtherTestName() { + * const decoder = new TextDecoder("utf-8"); + * const data = await Deno.readFile("hello_world.txt"); + * assertEquals(decoder.decode(data), "Hello world"); + * }, + * ); + * ``` + * + * @category Testing + */ + ( + options: Omit, + fn: (t: TestContext) => void | Promise, + ): void; + + /** Shorthand property for ignoring a particular test case. + * + * @category Testing + */ + ignore(t: Omit): void; + + /** Shorthand property for ignoring a particular test case. + * + * @category Testing + */ + ignore( + name: string, + fn: (t: TestContext) => void | Promise, + ): void; + + /** Shorthand property for ignoring a particular test case. + * + * @category Testing + */ + ignore(fn: (t: TestContext) => void | Promise): void; + + /** Shorthand property for ignoring a particular test case. + * + * @category Testing + */ + ignore( + name: string, + options: Omit, + fn: (t: TestContext) => void | Promise, + ): void; + + /** Shorthand property for ignoring a particular test case. + * + * @category Testing + */ + ignore( + options: Omit, + fn: (t: TestContext) => void | Promise, + ): void; + + /** Shorthand property for ignoring a particular test case. + * + * @category Testing + */ + ignore( + options: Omit, + fn: (t: TestContext) => void | Promise, + ): void; + + /** Shorthand property for focusing a particular test case. + * + * @category Testing + */ + only(t: Omit): void; + + /** Shorthand property for focusing a particular test case. + * + * @category Testing + */ + only( + name: string, + fn: (t: TestContext) => void | Promise, + ): void; + + /** Shorthand property for focusing a particular test case. + * + * @category Testing + */ + only(fn: (t: TestContext) => void | Promise): void; + + /** Shorthand property for focusing a particular test case. + * + * @category Testing + */ + only( + name: string, + options: Omit, + fn: (t: TestContext) => void | Promise, + ): void; + + /** Shorthand property for focusing a particular test case. + * + * @category Testing + */ + only( + options: Omit, + fn: (t: TestContext) => void | Promise, + ): void; + + /** Shorthand property for focusing a particular test case. + * + * @category Testing + */ + only( + options: Omit, + fn: (t: TestContext) => void | Promise, + ): void; + } + + /** + * Context that is passed to a benchmarked function. The instance is shared + * between iterations of the benchmark. Its methods can be used for example + * to override of the measured portion of the function. + * + * @category Testing + */ + export interface BenchContext { + /** The current benchmark name. */ + name: string; + /** The string URL of the current benchmark. */ + origin: string; + + /** Restarts the timer for the bench measurement. This should be called + * after doing setup work which should not be measured. + * + * Warning: This method should not be used for benchmarks averaging less + * than 10μs per iteration. In such cases it will be disabled but the call + * will still have noticeable overhead, resulting in a warning. + * + * ```ts + * Deno.bench("foo", async (t) => { + * const data = await Deno.readFile("data.txt"); + * t.start(); + * // some operation on `data`... + * }); + * ``` + */ + start(): void; + + /** End the timer early for the bench measurement. This should be called + * before doing teardown work which should not be measured. + * + * Warning: This method should not be used for benchmarks averaging less + * than 10μs per iteration. In such cases it will be disabled but the call + * will still have noticeable overhead, resulting in a warning. + * + * ```ts + * Deno.bench("foo", async (t) => { + * using file = await Deno.open("data.txt"); + * t.start(); + * // some operation on `file`... + * t.end(); + * }); + * ``` + */ + end(): void; + } + + /** + * The interface for defining a benchmark test using {@linkcode Deno.bench}. + * + * @category Testing + */ + export interface BenchDefinition { + /** The test function which will be benchmarked. */ + fn: (b: BenchContext) => void | Promise; + /** The name of the test, which will be used in displaying the results. */ + name: string; + /** If truthy, the benchmark test will be ignored/skipped. */ + ignore?: boolean; + /** Group name for the benchmark. + * + * Grouped benchmarks produce a group time summary, where the difference + * in performance between each test of the group is compared. */ + group?: string; + /** Benchmark should be used as the baseline for other benchmarks. + * + * If there are multiple baselines in a group, the first one is used as the + * baseline. */ + baseline?: boolean; + /** If at least one bench has `only` set to true, only run benches that have + * `only` set to `true` and fail the bench suite. */ + only?: boolean; + /** Ensure the bench case does not prematurely cause the process to exit, + * for example via a call to {@linkcode Deno.exit}. + * + * @default {true} */ + sanitizeExit?: boolean; + /** Specifies the permissions that should be used to run the bench. + * + * Set this to `"inherit"` to keep the calling thread's permissions. + * + * Set this to `"none"` to revoke all permissions. + * + * @default {"inherit"} + */ + permissions?: PermissionOptions; + } + + /** + * Register a benchmark test which will be run when `deno bench` is used on + * the command line and the containing module looks like a bench module. + * + * If the test function (`fn`) returns a promise or is async, the test runner + * will await resolution to consider the test complete. + * + * ```ts + * import { assertEquals } from "jsr:@std/assert"; + * + * Deno.bench({ + * name: "example test", + * fn() { + * assertEquals("world", "world"); + * }, + * }); + * + * Deno.bench({ + * name: "example ignored test", + * ignore: Deno.build.os === "windows", + * fn() { + * // This test is ignored only on Windows machines + * }, + * }); + * + * Deno.bench({ + * name: "example async test", + * async fn() { + * const decoder = new TextDecoder("utf-8"); + * const data = await Deno.readFile("hello_world.txt"); + * assertEquals(decoder.decode(data), "Hello world"); + * } + * }); + * ``` + * + * @category Testing + */ + export function bench(b: BenchDefinition): void; + + /** + * Register a benchmark test which will be run when `deno bench` is used on + * the command line and the containing module looks like a bench module. + * + * If the test function (`fn`) returns a promise or is async, the test runner + * will await resolution to consider the test complete. + * + * ```ts + * import { assertEquals } from "jsr:@std/assert"; + * + * Deno.bench("My test description", () => { + * assertEquals("hello", "hello"); + * }); + * + * Deno.bench("My async test description", async () => { + * const decoder = new TextDecoder("utf-8"); + * const data = await Deno.readFile("hello_world.txt"); + * assertEquals(decoder.decode(data), "Hello world"); + * }); + * ``` + * + * @category Testing + */ + export function bench( + name: string, + fn: (b: BenchContext) => void | Promise, + ): void; + + /** + * Register a benchmark test which will be run when `deno bench` is used on + * the command line and the containing module looks like a bench module. + * + * If the test function (`fn`) returns a promise or is async, the test runner + * will await resolution to consider the test complete. + * + * ```ts + * import { assertEquals } from "jsr:@std/assert"; + * + * Deno.bench(function myTestName() { + * assertEquals("hello", "hello"); + * }); + * + * Deno.bench(async function myOtherTestName() { + * const decoder = new TextDecoder("utf-8"); + * const data = await Deno.readFile("hello_world.txt"); + * assertEquals(decoder.decode(data), "Hello world"); + * }); + * ``` + * + * @category Testing + */ + export function bench(fn: (b: BenchContext) => void | Promise): void; + + /** + * Register a benchmark test which will be run when `deno bench` is used on + * the command line and the containing module looks like a bench module. + * + * If the test function (`fn`) returns a promise or is async, the test runner + * will await resolution to consider the test complete. + * + * ```ts + * import { assertEquals } from "jsr:@std/assert"; + * + * Deno.bench( + * "My test description", + * { permissions: { read: true } }, + * () => { + * assertEquals("hello", "hello"); + * } + * ); + * + * Deno.bench( + * "My async test description", + * { permissions: { read: false } }, + * async () => { + * const decoder = new TextDecoder("utf-8"); + * const data = await Deno.readFile("hello_world.txt"); + * assertEquals(decoder.decode(data), "Hello world"); + * } + * ); + * ``` + * + * @category Testing + */ + export function bench( + name: string, + options: Omit, + fn: (b: BenchContext) => void | Promise, + ): void; + + /** + * Register a benchmark test which will be run when `deno bench` is used on + * the command line and the containing module looks like a bench module. + * + * If the test function (`fn`) returns a promise or is async, the test runner + * will await resolution to consider the test complete. + * + * ```ts + * import { assertEquals } from "jsr:@std/assert"; + * + * Deno.bench( + * { name: "My test description", permissions: { read: true } }, + * () => { + * assertEquals("hello", "hello"); + * } + * ); + * + * Deno.bench( + * { name: "My async test description", permissions: { read: false } }, + * async () => { + * const decoder = new TextDecoder("utf-8"); + * const data = await Deno.readFile("hello_world.txt"); + * assertEquals(decoder.decode(data), "Hello world"); + * } + * ); + * ``` + * + * @category Testing + */ + export function bench( + options: Omit, + fn: (b: BenchContext) => void | Promise, + ): void; + + /** + * Register a benchmark test which will be run when `deno bench` is used on + * the command line and the containing module looks like a bench module. + * + * If the test function (`fn`) returns a promise or is async, the test runner + * will await resolution to consider the test complete. + * + * ```ts + * import { assertEquals } from "jsr:@std/assert"; + * + * Deno.bench( + * { permissions: { read: true } }, + * function myTestName() { + * assertEquals("hello", "hello"); + * } + * ); + * + * Deno.bench( + * { permissions: { read: false } }, + * async function myOtherTestName() { + * const decoder = new TextDecoder("utf-8"); + * const data = await Deno.readFile("hello_world.txt"); + * assertEquals(decoder.decode(data), "Hello world"); + * } + * ); + * ``` + * + * @category Testing + */ + export function bench( + options: Omit, + fn: (b: BenchContext) => void | Promise, + ): void; + + /** Exit the Deno process with optional exit code. + * + * If no exit code is supplied then Deno will exit with return code of `0`. + * + * In worker contexts this is an alias to `self.close();`. + * + * ```ts + * Deno.exit(5); + * ``` + * + * @category Runtime Environment + */ + export function exit(code?: number): never; + + /** An interface containing methods to interact with the process environment + * variables. + * + * @tags allow-env + * @category Runtime Environment + */ + export interface Env { + /** Retrieve the value of an environment variable. + * + * Returns `undefined` if the supplied environment variable is not defined. + * + * ```ts + * console.log(Deno.env.get("HOME")); // e.g. outputs "/home/alice" + * console.log(Deno.env.get("MADE_UP_VAR")); // outputs "undefined" + * ``` + * + * Requires `allow-env` permission. + * + * @tags allow-env + */ + get(key: string): string | undefined; + + /** Set the value of an environment variable. + * + * ```ts + * Deno.env.set("SOME_VAR", "Value"); + * Deno.env.get("SOME_VAR"); // outputs "Value" + * ``` + * + * Requires `allow-env` permission. + * + * @tags allow-env + */ + set(key: string, value: string): void; + + /** Delete the value of an environment variable. + * + * ```ts + * Deno.env.set("SOME_VAR", "Value"); + * Deno.env.delete("SOME_VAR"); // outputs "undefined" + * ``` + * + * Requires `allow-env` permission. + * + * @tags allow-env + */ + delete(key: string): void; + + /** Check whether an environment variable is present or not. + * + * ```ts + * Deno.env.set("SOME_VAR", "Value"); + * Deno.env.has("SOME_VAR"); // outputs true + * ``` + * + * Requires `allow-env` permission. + * + * @tags allow-env + */ + has(key: string): boolean; + + /** Returns a snapshot of the environment variables at invocation as a + * simple object of keys and values. + * + * ```ts + * Deno.env.set("TEST_VAR", "A"); + * const myEnv = Deno.env.toObject(); + * console.log(myEnv.SHELL); + * Deno.env.set("TEST_VAR", "B"); + * console.log(myEnv.TEST_VAR); // outputs "A" + * ``` + * + * Requires `allow-env` permission. + * + * @tags allow-env + */ + toObject(): { [index: string]: string }; + } + + /** An interface containing methods to interact with the process environment + * variables. + * + * @tags allow-env + * @category Runtime Environment + */ + export const env: Env; + + /** + * Returns the path to the current deno executable. + * + * ```ts + * console.log(Deno.execPath()); // e.g. "/home/alice/.local/bin/deno" + * ``` + * + * Requires `allow-read` permission. + * + * @tags allow-read + * @category Runtime Environment + */ + export function execPath(): string; + + /** + * Change the current working directory to the specified path. + * + * ```ts + * Deno.chdir("/home/userA"); + * Deno.chdir("../userB"); + * Deno.chdir("C:\\Program Files (x86)\\Java"); + * ``` + * + * Throws {@linkcode Deno.errors.NotFound} if directory not found. + * + * Throws {@linkcode Deno.errors.PermissionDenied} if the user does not have + * operating system file access rights. + * + * Requires `allow-read` permission. + * + * @tags allow-read + * @category Runtime Environment + */ + export function chdir(directory: string | URL): void; + + /** + * Return a string representing the current working directory. + * + * If the current directory can be reached via multiple paths (due to symbolic + * links), `cwd()` may return any one of them. + * + * ```ts + * const currentWorkingDirectory = Deno.cwd(); + * ``` + * + * Throws {@linkcode Deno.errors.NotFound} if directory not available. + * + * Requires `allow-read` permission. + * + * @tags allow-read + * @category Runtime Environment + */ + export function cwd(): string; + + /** + * Creates `newpath` as a hard link to `oldpath`. + * + * ```ts + * await Deno.link("old/name", "new/name"); + * ``` + * + * Requires `allow-read` and `allow-write` permissions. + * + * @tags allow-read, allow-write + * @category File System + */ + export function link(oldpath: string, newpath: string): Promise; + + /** + * Synchronously creates `newpath` as a hard link to `oldpath`. + * + * ```ts + * Deno.linkSync("old/name", "new/name"); + * ``` + * + * Requires `allow-read` and `allow-write` permissions. + * + * @tags allow-read, allow-write + * @category File System + */ + export function linkSync(oldpath: string, newpath: string): void; + + /** + * A enum which defines the seek mode for IO related APIs that support + * seeking. + * + * @category I/O */ + export enum SeekMode { + /* Seek from the start of the file/resource. */ + Start = 0, + /* Seek from the current position within the file/resource. */ + Current = 1, + /* Seek from the end of the current file/resource. */ + End = 2, + } + + /** + * An abstract interface which when implemented provides an interface to read + * bytes into an array buffer asynchronously. + * + * @deprecated This will be removed in Deno 2.0. See the + * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide} + * for migration instructions. + * + * @category I/O */ + export interface Reader { + /** Reads up to `p.byteLength` bytes into `p`. It resolves to the number of + * bytes read (`0` < `n` <= `p.byteLength`) and rejects if any error + * encountered. Even if `read()` resolves to `n` < `p.byteLength`, it may + * use all of `p` as scratch space during the call. If some data is + * available but not `p.byteLength` bytes, `read()` conventionally resolves + * to what is available instead of waiting for more. + * + * When `read()` encounters end-of-file condition, it resolves to EOF + * (`null`). + * + * When `read()` encounters an error, it rejects with an error. + * + * Callers should always process the `n` > `0` bytes returned before + * considering the EOF (`null`). Doing so correctly handles I/O errors that + * happen after reading some bytes and also both of the allowed EOF + * behaviors. + * + * Implementations should not retain a reference to `p`. + * + * Use + * {@linkcode https://jsr.io/@std/io/doc/iterate-reader/~/iterateReader | iterateReader} + * to turn {@linkcode Reader} into an {@linkcode AsyncIterator}. + */ + read(p: Uint8Array): Promise; + } + + /** + * An abstract interface which when implemented provides an interface to read + * bytes into an array buffer synchronously. + * + * @deprecated This will be removed in Deno 2.0. See the + * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide} + * for migration instructions. + * + * @category I/O */ + export interface ReaderSync { + /** Reads up to `p.byteLength` bytes into `p`. It resolves to the number + * of bytes read (`0` < `n` <= `p.byteLength`) and rejects if any error + * encountered. Even if `readSync()` returns `n` < `p.byteLength`, it may use + * all of `p` as scratch space during the call. If some data is available + * but not `p.byteLength` bytes, `readSync()` conventionally returns what is + * available instead of waiting for more. + * + * When `readSync()` encounters end-of-file condition, it returns EOF + * (`null`). + * + * When `readSync()` encounters an error, it throws with an error. + * + * Callers should always process the `n` > `0` bytes returned before + * considering the EOF (`null`). Doing so correctly handles I/O errors that + * happen after reading some bytes and also both of the allowed EOF + * behaviors. + * + * Implementations should not retain a reference to `p`. + * + * Use + * {@linkcode https://jsr.io/@std/io/doc/iterate-reader/~/iterateReaderSync | iterateReaderSync} + * to turn {@linkcode ReaderSync} into an {@linkcode Iterator}. + */ + readSync(p: Uint8Array): number | null; + } + + /** + * An abstract interface which when implemented provides an interface to write + * bytes from an array buffer to a file/resource asynchronously. + * + * @deprecated This will be removed in Deno 2.0. See the + * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide} + * for migration instructions. + * + * @category I/O */ + export interface Writer { + /** Writes `p.byteLength` bytes from `p` to the underlying data stream. It + * resolves to the number of bytes written from `p` (`0` <= `n` <= + * `p.byteLength`) or reject with the error encountered that caused the + * write to stop early. `write()` must reject with a non-null error if + * would resolve to `n` < `p.byteLength`. `write()` must not modify the + * slice data, even temporarily. + * + * This function is one of the lowest + * level APIs and most users should not work with this directly, but rather + * use {@linkcode https://jsr.io/@std/io/doc/write-all/~/writeAll | writeAll} + * instead. + * + * Implementations should not retain a reference to `p`. + */ + write(p: Uint8Array): Promise; + } + + /** + * An abstract interface which when implemented provides an interface to write + * bytes from an array buffer to a file/resource synchronously. + * + * @deprecated This will be removed in Deno 2.0. See the + * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide} + * for migration instructions. + * + * @category I/O */ + export interface WriterSync { + /** Writes `p.byteLength` bytes from `p` to the underlying data + * stream. It returns the number of bytes written from `p` (`0` <= `n` + * <= `p.byteLength`) and any error encountered that caused the write to + * stop early. `writeSync()` must throw a non-null error if it returns `n` < + * `p.byteLength`. `writeSync()` must not modify the slice data, even + * temporarily. + * + * Implementations should not retain a reference to `p`. + */ + writeSync(p: Uint8Array): number; + } + + /** + * An abstract interface which when implemented provides an interface to close + * files/resources that were previously opened. + * + * @deprecated This will be removed in Deno 2.0. See the + * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide} + * for migration instructions. + * + * @category I/O */ + export interface Closer { + /** Closes the resource, "freeing" the backing file/resource. */ + close(): void; + } + + /** + * An abstract interface which when implemented provides an interface to seek + * within an open file/resource asynchronously. + * + * @category I/O */ + export interface Seeker { + /** Seek sets the offset for the next `read()` or `write()` to offset, + * interpreted according to `whence`: `Start` means relative to the + * start of the file, `Current` means relative to the current offset, + * and `End` means relative to the end. Seek resolves to the new offset + * relative to the start of the file. + * + * Seeking to an offset before the start of the file is an error. Seeking to + * any positive offset is legal, but the behavior of subsequent I/O + * operations on the underlying object is implementation-dependent. + * + * It resolves with the updated offset. + */ + seek(offset: number | bigint, whence: SeekMode): Promise; + } + + /** + * An abstract interface which when implemented provides an interface to seek + * within an open file/resource synchronously. + * + * @category I/O */ + export interface SeekerSync { + /** Seek sets the offset for the next `readSync()` or `writeSync()` to + * offset, interpreted according to `whence`: `Start` means relative + * to the start of the file, `Current` means relative to the current + * offset, and `End` means relative to the end. + * + * Seeking to an offset before the start of the file is an error. Seeking to + * any positive offset is legal, but the behavior of subsequent I/O + * operations on the underlying object is implementation-dependent. + * + * It returns the updated offset. + */ + seekSync(offset: number | bigint, whence: SeekMode): number; + } + + /** + * Copies from `src` to `dst` until either EOF (`null`) is read from `src` or + * an error occurs. It resolves to the number of bytes copied or rejects with + * the first error encountered while copying. + * + * @deprecated This will be removed in Deno 2.0. See the + * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide} + * for migration instructions. + * + * @category I/O + * + * @param src The source to copy from + * @param dst The destination to copy to + * @param options Can be used to tune size of the buffer. Default size is 32kB + */ + export function copy( + src: Reader, + dst: Writer, + options?: { bufSize?: number }, + ): Promise; + + /** + * Turns a Reader, `r`, into an async iterator. + * + * @deprecated This will be removed in Deno 2.0. See the + * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide} + * for migration instructions. + * + * @category I/O + */ + export function iter( + r: Reader, + options?: { bufSize?: number }, + ): AsyncIterableIterator; + + /** + * Turns a ReaderSync, `r`, into an iterator. + * + * @deprecated This will be removed in Deno 2.0. See the + * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide} + * for migration instructions. + * + * @category I/O + */ + export function iterSync( + r: ReaderSync, + options?: { + bufSize?: number; + }, + ): IterableIterator; + + /** Open a file and resolve to an instance of {@linkcode Deno.FsFile}. The + * file does not need to previously exist if using the `create` or `createNew` + * open options. The caller may have the resulting file automatically closed + * by the runtime once it's out of scope by declaring the file variable with + * the `using` keyword. + * + * ```ts + * using file = await Deno.open("/foo/bar.txt", { read: true, write: true }); + * // Do work with file + * ``` + * + * Alternatively, the caller may manually close the resource when finished with + * it. + * + * ```ts + * const file = await Deno.open("/foo/bar.txt", { read: true, write: true }); + * // Do work with file + * file.close(); + * ``` + * + * Requires `allow-read` and/or `allow-write` permissions depending on + * options. + * + * @tags allow-read, allow-write + * @category File System + */ + export function open( + path: string | URL, + options?: OpenOptions, + ): Promise; + + /** Synchronously open a file and return an instance of + * {@linkcode Deno.FsFile}. The file does not need to previously exist if + * using the `create` or `createNew` open options. The caller may have the + * resulting file automatically closed by the runtime once it's out of scope + * by declaring the file variable with the `using` keyword. + * + * ```ts + * using file = Deno.openSync("/foo/bar.txt", { read: true, write: true }); + * // Do work with file + * ``` + * + * Alternatively, the caller may manually close the resource when finished with + * it. + * + * ```ts + * const file = Deno.openSync("/foo/bar.txt", { read: true, write: true }); + * // Do work with file + * file.close(); + * ``` + * + * Requires `allow-read` and/or `allow-write` permissions depending on + * options. + * + * @tags allow-read, allow-write + * @category File System + */ + export function openSync(path: string | URL, options?: OpenOptions): FsFile; + + /** Creates a file if none exists or truncates an existing file and resolves to + * an instance of {@linkcode Deno.FsFile}. + * + * ```ts + * const file = await Deno.create("/foo/bar.txt"); + * ``` + * + * Requires `allow-read` and `allow-write` permissions. + * + * @tags allow-read, allow-write + * @category File System + */ + export function create(path: string | URL): Promise; + + /** Creates a file if none exists or truncates an existing file and returns + * an instance of {@linkcode Deno.FsFile}. + * + * ```ts + * const file = Deno.createSync("/foo/bar.txt"); + * ``` + * + * Requires `allow-read` and `allow-write` permissions. + * + * @tags allow-read, allow-write + * @category File System + */ + export function createSync(path: string | URL): FsFile; + + /** Read from a resource ID (`rid`) into an array buffer (`buffer`). + * + * Resolves to either the number of bytes read during the operation or EOF + * (`null`) if there was nothing more to read. + * + * It is possible for a read to successfully return with `0` bytes. This does + * not indicate EOF. + * + * This function is one of the lowest level APIs and most users should not + * work with this directly, but rather use {@linkcode ReadableStream} and + * {@linkcode https://jsr.io/@std/streams/doc/to-array-buffer/~/toArrayBuffer | toArrayBuffer} + * instead. + * + * **It is not guaranteed that the full buffer will be read in a single call.** + * + * ```ts + * // if "/foo/bar.txt" contains the text "hello world": + * using file = await Deno.open("/foo/bar.txt"); + * const buf = new Uint8Array(100); + * const numberOfBytesRead = await Deno.read(file.rid, buf); // 11 bytes + * const text = new TextDecoder().decode(buf); // "hello world" + * ``` + * + * @deprecated This will be removed in Deno 2.0. See the + * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide} + * for migration instructions. + * + * @category I/O + */ + export function read(rid: number, buffer: Uint8Array): Promise; + + /** Synchronously read from a resource ID (`rid`) into an array buffer + * (`buffer`). + * + * Returns either the number of bytes read during the operation or EOF + * (`null`) if there was nothing more to read. + * + * It is possible for a read to successfully return with `0` bytes. This does + * not indicate EOF. + * + * This function is one of the lowest level APIs and most users should not + * work with this directly, but rather use {@linkcode ReadableStream} and + * {@linkcode https://jsr.io/@std/streams/doc/to-array-buffer/~/toArrayBuffer | toArrayBuffer} + * instead. + * + * **It is not guaranteed that the full buffer will be read in a single + * call.** + * + * ```ts + * // if "/foo/bar.txt" contains the text "hello world": + * using file = Deno.openSync("/foo/bar.txt"); + * const buf = new Uint8Array(100); + * const numberOfBytesRead = Deno.readSync(file.rid, buf); // 11 bytes + * const text = new TextDecoder().decode(buf); // "hello world" + * ``` + * + * @deprecated This will be removed in Deno 2.0. See the + * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide} + * for migration instructions. + * + * @category I/O + */ + export function readSync(rid: number, buffer: Uint8Array): number | null; + + /** Write to the resource ID (`rid`) the contents of the array buffer (`data`). + * + * Resolves to the number of bytes written. This function is one of the lowest + * level APIs and most users should not work with this directly, but rather + * use {@linkcode WritableStream}, {@linkcode ReadableStream.from} and + * {@linkcode ReadableStream.pipeTo}. + * + * **It is not guaranteed that the full buffer will be written in a single + * call.** + * + * ```ts + * const encoder = new TextEncoder(); + * const data = encoder.encode("Hello world"); + * using file = await Deno.open("/foo/bar.txt", { write: true }); + * const bytesWritten = await Deno.write(file.rid, data); // 11 + * ``` + * + * @deprecated This will be removed in Deno 2.0. See the + * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide} + * for migration instructions. + * + * @category I/O + */ + export function write(rid: number, data: Uint8Array): Promise; + + /** Synchronously write to the resource ID (`rid`) the contents of the array + * buffer (`data`). + * + * Returns the number of bytes written. This function is one of the lowest + * level APIs and most users should not work with this directly, but rather + * use {@linkcode WritableStream}, {@linkcode ReadableStream.from} and + * {@linkcode ReadableStream.pipeTo}. + * + * **It is not guaranteed that the full buffer will be written in a single + * call.** + * + * ```ts + * const encoder = new TextEncoder(); + * const data = encoder.encode("Hello world"); + * using file = Deno.openSync("/foo/bar.txt", { write: true }); + * const bytesWritten = Deno.writeSync(file.rid, data); // 11 + * ``` + * + * @deprecated This will be removed in Deno 2.0. See the + * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide} + * for migration instructions. + * + * @category I/O + */ + export function writeSync(rid: number, data: Uint8Array): number; + + /** Seek a resource ID (`rid`) to the given `offset` under mode given by `whence`. + * The call resolves to the new position within the resource (bytes from the start). + * + * ```ts + * // Given file.rid pointing to file with "Hello world", which is 11 bytes long: + * using file = await Deno.open( + * "hello.txt", + * { read: true, write: true, truncate: true, create: true }, + * ); + * await file.write(new TextEncoder().encode("Hello world")); + * + * // advance cursor 6 bytes + * const cursorPosition = await Deno.seek(file.rid, 6, Deno.SeekMode.Start); + * console.log(cursorPosition); // 6 + * const buf = new Uint8Array(100); + * await file.read(buf); + * console.log(new TextDecoder().decode(buf)); // "world" + * ``` + * + * The seek modes work as follows: + * + * ```ts + * // Given file.rid pointing to file with "Hello world", which is 11 bytes long: + * using file = await Deno.open( + * "hello.txt", + * { read: true, write: true, truncate: true, create: true }, + * ); + * await file.write(new TextEncoder().encode("Hello world")); + * + * // Seek 6 bytes from the start of the file + * console.log(await Deno.seek(file.rid, 6, Deno.SeekMode.Start)); // "6" + * // Seek 2 more bytes from the current position + * console.log(await Deno.seek(file.rid, 2, Deno.SeekMode.Current)); // "8" + * // Seek backwards 2 bytes from the end of the file + * console.log(await Deno.seek(file.rid, -2, Deno.SeekMode.End)); // "9" (i.e. 11-2) + * ``` + * + * @deprecated This will be removed in Deno 2.0. See the + * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide} + * for migration instructions. + * + * @category I/O + */ + export function seek( + rid: number, + offset: number | bigint, + whence: SeekMode, + ): Promise; + + /** Synchronously seek a resource ID (`rid`) to the given `offset` under mode + * given by `whence`. The new position within the resource (bytes from the + * start) is returned. + * + * ```ts + * using file = Deno.openSync( + * "hello.txt", + * { read: true, write: true, truncate: true, create: true }, + * ); + * file.writeSync(new TextEncoder().encode("Hello world")); + * + * // advance cursor 6 bytes + * const cursorPosition = Deno.seekSync(file.rid, 6, Deno.SeekMode.Start); + * console.log(cursorPosition); // 6 + * const buf = new Uint8Array(100); + * file.readSync(buf); + * console.log(new TextDecoder().decode(buf)); // "world" + * ``` + * + * The seek modes work as follows: + * + * ```ts + * // Given file.rid pointing to file with "Hello world", which is 11 bytes long: + * using file = Deno.openSync( + * "hello.txt", + * { read: true, write: true, truncate: true, create: true }, + * ); + * file.writeSync(new TextEncoder().encode("Hello world")); + * + * // Seek 6 bytes from the start of the file + * console.log(Deno.seekSync(file.rid, 6, Deno.SeekMode.Start)); // "6" + * // Seek 2 more bytes from the current position + * console.log(Deno.seekSync(file.rid, 2, Deno.SeekMode.Current)); // "8" + * // Seek backwards 2 bytes from the end of the file + * console.log(Deno.seekSync(file.rid, -2, Deno.SeekMode.End)); // "9" (i.e. 11-2) + * ``` + * + * @deprecated This will be removed in Deno 2.0. See the + * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide} + * for migration instructions. + * + * @category I/O + */ + export function seekSync( + rid: number, + offset: number | bigint, + whence: SeekMode, + ): number; + + /** + * Flushes any pending data and metadata operations of the given file stream + * to disk. + * + * ```ts + * const file = await Deno.open( + * "my_file.txt", + * { read: true, write: true, create: true }, + * ); + * await file.write(new TextEncoder().encode("Hello World")); + * await file.truncate(1); + * await Deno.fsync(file.rid); + * console.log(await Deno.readTextFile("my_file.txt")); // H + * ``` + * + * @category File System + */ + export function fsync(rid: number): Promise; + + /** + * Synchronously flushes any pending data and metadata operations of the given + * file stream to disk. + * + * ```ts + * const file = Deno.openSync( + * "my_file.txt", + * { read: true, write: true, create: true }, + * ); + * file.writeSync(new TextEncoder().encode("Hello World")); + * file.truncateSync(1); + * Deno.fsyncSync(file.rid); + * console.log(Deno.readTextFileSync("my_file.txt")); // H + * ``` + * + * @category File System + */ + export function fsyncSync(rid: number): void; + + /** + * Flushes any pending data operations of the given file stream to disk. + * ```ts + * const file = await Deno.open( + * "my_file.txt", + * { read: true, write: true, create: true }, + * ); + * await file.write(new TextEncoder().encode("Hello World")); + * await Deno.fdatasync(file.rid); + * console.log(await Deno.readTextFile("my_file.txt")); // Hello World + * ``` + * + * @category File System + */ + export function fdatasync(rid: number): Promise; + + /** + * Synchronously flushes any pending data operations of the given file stream + * to disk. + * + * ```ts + * const file = Deno.openSync( + * "my_file.txt", + * { read: true, write: true, create: true }, + * ); + * file.writeSync(new TextEncoder().encode("Hello World")); + * Deno.fdatasyncSync(file.rid); + * console.log(Deno.readTextFileSync("my_file.txt")); // Hello World + * ``` + * + * @category File System + */ + export function fdatasyncSync(rid: number): void; + + /** Close the given resource ID (`rid`) which has been previously opened, such + * as via opening or creating a file. Closing a file when you are finished + * with it is important to avoid leaking resources. + * + * ```ts + * const file = await Deno.open("my_file.txt"); + * // do work with "file" object + * Deno.close(file.rid); + * ``` + * + * It is recommended to define the variable with the `using` keyword so the + * runtime will automatically close the resource when it goes out of scope. + * Doing so negates the need to manually close the resource. + * + * ```ts + * using file = await Deno.open("my_file.txt"); + * // do work with "file" object + * ``` + * + * @deprecated This will be removed in Deno 2.0. See the + * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide} + * for migration instructions. + * + * @category I/O + */ + export function close(rid: number): void; + + /** The Deno abstraction for reading and writing files. + * + * This is the most straight forward way of handling files within Deno and is + * recommended over using the discrete functions within the `Deno` namespace. + * + * ```ts + * using file = await Deno.open("/foo/bar.txt", { read: true }); + * const fileInfo = await file.stat(); + * if (fileInfo.isFile) { + * const buf = new Uint8Array(100); + * const numberOfBytesRead = await file.read(buf); // 11 bytes + * const text = new TextDecoder().decode(buf); // "hello world" + * } + * ``` + * + * @category File System + */ + export class FsFile implements Reader, ReaderSync, Writer, WriterSync, Seeker, SeekerSync, Closer, Disposable { + /** + * The resource ID associated with the file instance. The resource ID + * should be considered an opaque reference to resource. + * + * @deprecated This will be removed in Deno 2.0. See the + * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide} + * for migration instructions. + */ + readonly rid: number; + /** A {@linkcode ReadableStream} instance representing to the byte contents + * of the file. This makes it easy to interoperate with other web streams + * based APIs. + * + * ```ts + * using file = await Deno.open("my_file.txt", { read: true }); + * const decoder = new TextDecoder(); + * for await (const chunk of file.readable) { + * console.log(decoder.decode(chunk)); + * } + * ``` + */ + readonly readable: ReadableStream; + /** A {@linkcode WritableStream} instance to write the contents of the + * file. This makes it easy to interoperate with other web streams based + * APIs. + * + * ```ts + * const items = ["hello", "world"]; + * using file = await Deno.open("my_file.txt", { write: true }); + * const encoder = new TextEncoder(); + * const writer = file.writable.getWriter(); + * for (const item of items) { + * await writer.write(encoder.encode(item)); + * } + * ``` + */ + readonly writable: WritableStream; + /** + * The constructor which takes a resource ID. Generally `FsFile` should + * not be constructed directly. Instead use {@linkcode Deno.open} or + * {@linkcode Deno.openSync} to create a new instance of `FsFile`. + * + * @deprecated This will be removed in Deno 2.0. See the + * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide} + * for migration instructions. + */ + constructor(rid: number); + /** Write the contents of the array buffer (`p`) to the file. + * + * Resolves to the number of bytes written. + * + * **It is not guaranteed that the full buffer will be written in a single + * call.** + * + * ```ts + * const encoder = new TextEncoder(); + * const data = encoder.encode("Hello world"); + * using file = await Deno.open("/foo/bar.txt", { write: true }); + * const bytesWritten = await file.write(data); // 11 + * ``` + * + * @category I/O + */ + write(p: Uint8Array): Promise; + /** Synchronously write the contents of the array buffer (`p`) to the file. + * + * Returns the number of bytes written. + * + * **It is not guaranteed that the full buffer will be written in a single + * call.** + * + * ```ts + * const encoder = new TextEncoder(); + * const data = encoder.encode("Hello world"); + * using file = Deno.openSync("/foo/bar.txt", { write: true }); + * const bytesWritten = file.writeSync(data); // 11 + * ``` + */ + writeSync(p: Uint8Array): number; + /** Truncates (or extends) the file to reach the specified `len`. If `len` + * is not specified, then the entire file contents are truncated. + * + * ### Truncate the entire file + * + * ```ts + * using file = await Deno.open("my_file.txt", { write: true }); + * await file.truncate(); + * ``` + * + * ### Truncate part of the file + * + * ```ts + * // if "my_file.txt" contains the text "hello world": + * using file = await Deno.open("my_file.txt", { write: true }); + * await file.truncate(7); + * const buf = new Uint8Array(100); + * await file.read(buf); + * const text = new TextDecoder().decode(buf); // "hello w" + * ``` + */ + truncate(len?: number): Promise; + /** Synchronously truncates (or extends) the file to reach the specified + * `len`. If `len` is not specified, then the entire file contents are + * truncated. + * + * ### Truncate the entire file + * + * ```ts + * using file = Deno.openSync("my_file.txt", { write: true }); + * file.truncateSync(); + * ``` + * + * ### Truncate part of the file + * + * ```ts + * // if "my_file.txt" contains the text "hello world": + * using file = Deno.openSync("my_file.txt", { write: true }); + * file.truncateSync(7); + * const buf = new Uint8Array(100); + * file.readSync(buf); + * const text = new TextDecoder().decode(buf); // "hello w" + * ``` + */ + truncateSync(len?: number): void; + /** Read the file into an array buffer (`p`). + * + * Resolves to either the number of bytes read during the operation or EOF + * (`null`) if there was nothing more to read. + * + * It is possible for a read to successfully return with `0` bytes. This + * does not indicate EOF. + * + * **It is not guaranteed that the full buffer will be read in a single + * call.** + * + * ```ts + * // if "/foo/bar.txt" contains the text "hello world": + * using file = await Deno.open("/foo/bar.txt"); + * const buf = new Uint8Array(100); + * const numberOfBytesRead = await file.read(buf); // 11 bytes + * const text = new TextDecoder().decode(buf); // "hello world" + * ``` + */ + read(p: Uint8Array): Promise; + /** Synchronously read from the file into an array buffer (`p`). + * + * Returns either the number of bytes read during the operation or EOF + * (`null`) if there was nothing more to read. + * + * It is possible for a read to successfully return with `0` bytes. This + * does not indicate EOF. + * + * **It is not guaranteed that the full buffer will be read in a single + * call.** + * + * ```ts + * // if "/foo/bar.txt" contains the text "hello world": + * using file = Deno.openSync("/foo/bar.txt"); + * const buf = new Uint8Array(100); + * const numberOfBytesRead = file.readSync(buf); // 11 bytes + * const text = new TextDecoder().decode(buf); // "hello world" + * ``` + */ + readSync(p: Uint8Array): number | null; + /** Seek to the given `offset` under mode given by `whence`. The call + * resolves to the new position within the resource (bytes from the start). + * + * ```ts + * // Given file pointing to file with "Hello world", which is 11 bytes long: + * using file = await Deno.open( + * "hello.txt", + * { read: true, write: true, truncate: true, create: true }, + * ); + * await file.write(new TextEncoder().encode("Hello world")); + * + * // advance cursor 6 bytes + * const cursorPosition = await file.seek(6, Deno.SeekMode.Start); + * console.log(cursorPosition); // 6 + * const buf = new Uint8Array(100); + * await file.read(buf); + * console.log(new TextDecoder().decode(buf)); // "world" + * ``` + * + * The seek modes work as follows: + * + * ```ts + * // Given file.rid pointing to file with "Hello world", which is 11 bytes long: + * const file = await Deno.open( + * "hello.txt", + * { read: true, write: true, truncate: true, create: true }, + * ); + * await file.write(new TextEncoder().encode("Hello world")); + * + * // Seek 6 bytes from the start of the file + * console.log(await file.seek(6, Deno.SeekMode.Start)); // "6" + * // Seek 2 more bytes from the current position + * console.log(await file.seek(2, Deno.SeekMode.Current)); // "8" + * // Seek backwards 2 bytes from the end of the file + * console.log(await file.seek(-2, Deno.SeekMode.End)); // "9" (i.e. 11-2) + * ``` + */ + seek(offset: number | bigint, whence: SeekMode): Promise; + /** Synchronously seek to the given `offset` under mode given by `whence`. + * The new position within the resource (bytes from the start) is returned. + * + * ```ts + * using file = Deno.openSync( + * "hello.txt", + * { read: true, write: true, truncate: true, create: true }, + * ); + * file.writeSync(new TextEncoder().encode("Hello world")); + * + * // advance cursor 6 bytes + * const cursorPosition = file.seekSync(6, Deno.SeekMode.Start); + * console.log(cursorPosition); // 6 + * const buf = new Uint8Array(100); + * file.readSync(buf); + * console.log(new TextDecoder().decode(buf)); // "world" + * ``` + * + * The seek modes work as follows: + * + * ```ts + * // Given file.rid pointing to file with "Hello world", which is 11 bytes long: + * using file = Deno.openSync( + * "hello.txt", + * { read: true, write: true, truncate: true, create: true }, + * ); + * file.writeSync(new TextEncoder().encode("Hello world")); + * + * // Seek 6 bytes from the start of the file + * console.log(file.seekSync(6, Deno.SeekMode.Start)); // "6" + * // Seek 2 more bytes from the current position + * console.log(file.seekSync(2, Deno.SeekMode.Current)); // "8" + * // Seek backwards 2 bytes from the end of the file + * console.log(file.seekSync(-2, Deno.SeekMode.End)); // "9" (i.e. 11-2) + * ``` + */ + seekSync(offset: number | bigint, whence: SeekMode): number; + /** Resolves to a {@linkcode Deno.FileInfo} for the file. + * + * ```ts + * import { assert } from "jsr:@std/assert"; + * + * using file = await Deno.open("hello.txt"); + * const fileInfo = await file.stat(); + * assert(fileInfo.isFile); + * ``` + */ + stat(): Promise; + /** Synchronously returns a {@linkcode Deno.FileInfo} for the file. + * + * ```ts + * import { assert } from "jsr:@std/assert"; + * + * using file = Deno.openSync("hello.txt") + * const fileInfo = file.statSync(); + * assert(fileInfo.isFile); + * ``` + */ + statSync(): FileInfo; + /** **UNSTABLE**: New API, yet to be vetted. + * + * Flushes any pending data and metadata operations of the given file + * stream to disk. + * + * ```ts + * const file = await Deno.open( + * "my_file.txt", + * { read: true, write: true, create: true }, + * ); + * await file.write(new TextEncoder().encode("Hello World")); + * await file.truncate(1); + * await file.sync(); + * console.log(await Deno.readTextFile("my_file.txt")); // H + * ``` + * + * @category I/O + */ + sync(): Promise; + /** **UNSTABLE**: New API, yet to be vetted. + * + * Synchronously flushes any pending data and metadata operations of the given + * file stream to disk. + * + * ```ts + * const file = Deno.openSync( + * "my_file.txt", + * { read: true, write: true, create: true }, + * ); + * file.writeSync(new TextEncoder().encode("Hello World")); + * file.truncateSync(1); + * file.syncSync(); + * console.log(Deno.readTextFileSync("my_file.txt")); // H + * ``` + * + * @category I/O + */ + syncSync(): void; + /** **UNSTABLE**: New API, yet to be vetted. + * + * Flushes any pending data operations of the given file stream to disk. + * ```ts + * using file = await Deno.open( + * "my_file.txt", + * { read: true, write: true, create: true }, + * ); + * await file.write(new TextEncoder().encode("Hello World")); + * await file.syncData(); + * console.log(await Deno.readTextFile("my_file.txt")); // Hello World + * ``` + * + * @category I/O + */ + syncData(): Promise; + /** **UNSTABLE**: New API, yet to be vetted. + * + * Synchronously flushes any pending data operations of the given file stream + * to disk. + * + * ```ts + * using file = Deno.openSync( + * "my_file.txt", + * { read: true, write: true, create: true }, + * ); + * file.writeSync(new TextEncoder().encode("Hello World")); + * file.syncDataSync(); + * console.log(Deno.readTextFileSync("my_file.txt")); // Hello World + * ``` + * + * @category I/O + */ + syncDataSync(): void; + /** + * Changes the access (`atime`) and modification (`mtime`) times of the + * file stream resource. Given times are either in seconds (UNIX epoch + * time) or as `Date` objects. + * + * ```ts + * using file = await Deno.open("file.txt", { create: true, write: true }); + * await file.utime(1556495550, new Date()); + * ``` + * + * @category File System + */ + utime(atime: number | Date, mtime: number | Date): Promise; + /** + * Synchronously changes the access (`atime`) and modification (`mtime`) + * times of the file stream resource. Given times are either in seconds + * (UNIX epoch time) or as `Date` objects. + * + * ```ts + * using file = Deno.openSync("file.txt", { create: true, write: true }); + * file.utime(1556495550, new Date()); + * ``` + * + * @category File System + */ + utimeSync(atime: number | Date, mtime: number | Date): void; + /** **UNSTABLE**: New API, yet to be vetted. + * + * Checks if the file resource is a TTY (terminal). + * + * ```ts + * // This example is system and context specific + * using file = await Deno.open("/dev/tty6"); + * file.isTerminal(); // true + * ``` + */ + isTerminal(): boolean; + /** **UNSTABLE**: New API, yet to be vetted. + * + * Set TTY to be under raw mode or not. In raw mode, characters are read and + * returned as is, without being processed. All special processing of + * characters by the terminal is disabled, including echoing input + * characters. Reading from a TTY device in raw mode is faster than reading + * from a TTY device in canonical mode. + * + * ```ts + * using file = await Deno.open("/dev/tty6"); + * file.setRaw(true, { cbreak: true }); + * ``` + */ + setRaw(mode: boolean, options?: SetRawOptions): void; + /** **UNSTABLE**: New API, yet to be vetted. + * + * Acquire an advisory file-system lock for the file. + * + * @param [exclusive=false] + */ + lock(exclusive?: boolean): Promise; + /** **UNSTABLE**: New API, yet to be vetted. + * + * Synchronously acquire an advisory file-system lock synchronously for the file. + * + * @param [exclusive=false] + */ + lockSync(exclusive?: boolean): void; + /** **UNSTABLE**: New API, yet to be vetted. + * + * Release an advisory file-system lock for the file. + */ + unlock(): Promise; + /** **UNSTABLE**: New API, yet to be vetted. + * + * Synchronously release an advisory file-system lock for the file. + */ + unlockSync(): void; + /** Close the file. Closing a file when you are finished with it is + * important to avoid leaking resources. + * + * ```ts + * using file = await Deno.open("my_file.txt"); + * // do work with "file" object + * ``` + */ + close(): void; + + [Symbol.dispose](): void; + } + + /** + * The Deno abstraction for reading and writing files. + * + * @deprecated This will be removed in Deno 2.0. See the + * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide} + * for migration instructions. + * + * @category File System + */ + export const File: typeof FsFile; + + /** Gets the size of the console as columns/rows. + * + * ```ts + * const { columns, rows } = Deno.consoleSize(); + * ``` + * + * This returns the size of the console window as reported by the operating + * system. It's not a reflection of how many characters will fit within the + * console window, but can be used as part of that calculation. + * + * @category I/O + */ + export function consoleSize(): { + columns: number; + rows: number; + }; + + /** @category I/O */ + export interface SetRawOptions { + /** + * The `cbreak` option can be used to indicate that characters that + * correspond to a signal should still be generated. When disabling raw + * mode, this option is ignored. This functionality currently only works on + * Linux and Mac OS. + */ + cbreak: boolean; + } + + /** A reference to `stdin` which can be used to read directly from `stdin`. + * It implements the Deno specific {@linkcode Reader}, {@linkcode ReaderSync}, + * and {@linkcode Closer} interfaces as well as provides a + * {@linkcode ReadableStream} interface. + * + * ### Reading chunks from the readable stream + * + * ```ts + * const decoder = new TextDecoder(); + * for await (const chunk of Deno.stdin.readable) { + * const text = decoder.decode(chunk); + * // do something with the text + * } + * ``` + * + * @category I/O + */ + export const stdin: Reader & ReaderSync & Closer & { + /** + * The resource ID assigned to `stdin`. This can be used with the discrete + * I/O functions in the `Deno` namespace. + * + * @deprecated This will be soft-removed in Deno 2.0. See the + * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide} + * for migration instructions. + */ + readonly rid: number; + /** A readable stream interface to `stdin`. */ + readonly readable: ReadableStream; + /** + * Set TTY to be under raw mode or not. In raw mode, characters are read and + * returned as is, without being processed. All special processing of + * characters by the terminal is disabled, including echoing input + * characters. Reading from a TTY device in raw mode is faster than reading + * from a TTY device in canonical mode. + * + * ```ts + * Deno.stdin.setRaw(true, { cbreak: true }); + * ``` + * + * @category I/O + */ + setRaw(mode: boolean, options?: SetRawOptions): void; + /** + * Checks if `stdin` is a TTY (terminal). + * + * ```ts + * // This example is system and context specific + * Deno.stdin.isTerminal(); // true + * ``` + * + * @category I/O + */ + isTerminal(): boolean; + }; + /** A reference to `stdout` which can be used to write directly to `stdout`. + * It implements the Deno specific {@linkcode Writer}, {@linkcode WriterSync}, + * and {@linkcode Closer} interfaces as well as provides a + * {@linkcode WritableStream} interface. + * + * These are low level constructs, and the {@linkcode console} interface is a + * more straight forward way to interact with `stdout` and `stderr`. + * + * @category I/O + */ + export const stdout: Writer & WriterSync & Closer & { + /** + * The resource ID assigned to `stdout`. This can be used with the discrete + * I/O functions in the `Deno` namespace. + * + * @deprecated This will be soft-removed in Deno 2.0. See the + * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide} + * for migration instructions. + */ + readonly rid: number; + /** A writable stream interface to `stdout`. */ + readonly writable: WritableStream; + /** + * Checks if `stdout` is a TTY (terminal). + * + * ```ts + * // This example is system and context specific + * Deno.stdout.isTerminal(); // true + * ``` + * + * @category I/O + */ + isTerminal(): boolean; + }; + /** A reference to `stderr` which can be used to write directly to `stderr`. + * It implements the Deno specific {@linkcode Writer}, {@linkcode WriterSync}, + * and {@linkcode Closer} interfaces as well as provides a + * {@linkcode WritableStream} interface. + * + * These are low level constructs, and the {@linkcode console} interface is a + * more straight forward way to interact with `stdout` and `stderr`. + * + * @category I/O + */ + export const stderr: Writer & WriterSync & Closer & { + /** + * The resource ID assigned to `stderr`. This can be used with the discrete + * I/O functions in the `Deno` namespace. + * + * @deprecated This will be soft-removed in Deno 2.0. See the + * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide} + * for migration instructions. + */ + readonly rid: number; + /** A writable stream interface to `stderr`. */ + readonly writable: WritableStream; + /** + * Checks if `stderr` is a TTY (terminal). + * + * ```ts + * // This example is system and context specific + * Deno.stderr.isTerminal(); // true + * ``` + * + * @category I/O + */ + isTerminal(): boolean; + }; + + /** + * Options which can be set when doing {@linkcode Deno.open} and + * {@linkcode Deno.openSync}. + * + * @category File System */ + export interface OpenOptions { + /** Sets the option for read access. This option, when `true`, means that + * the file should be read-able if opened. + * + * @default {true} */ + read?: boolean; + /** Sets the option for write access. This option, when `true`, means that + * the file should be write-able if opened. If the file already exists, + * any write calls on it will overwrite its contents, by default without + * truncating it. + * + * @default {false} */ + write?: boolean; + /** Sets the option for the append mode. This option, when `true`, means + * that writes will append to a file instead of overwriting previous + * contents. + * + * Note that setting `{ write: true, append: true }` has the same effect as + * setting only `{ append: true }`. + * + * @default {false} */ + append?: boolean; + /** Sets the option for truncating a previous file. If a file is + * successfully opened with this option set it will truncate the file to `0` + * size if it already exists. The file must be opened with write access + * for truncate to work. + * + * @default {false} */ + truncate?: boolean; + /** Sets the option to allow creating a new file, if one doesn't already + * exist at the specified path. Requires write or append access to be + * used. + * + * @default {false} */ + create?: boolean; + /** If set to `true`, no file, directory, or symlink is allowed to exist at + * the target location. Requires write or append access to be used. When + * createNew is set to `true`, create and truncate are ignored. + * + * @default {false} */ + createNew?: boolean; + /** Permissions to use if creating the file (defaults to `0o666`, before + * the process's umask). + * + * Ignored on Windows. */ + mode?: number; + } + + /** + * Options which can be set when using {@linkcode Deno.readFile} or + * {@linkcode Deno.readFileSync}. + * + * @category File System */ + export interface ReadFileOptions { + /** + * An abort signal to allow cancellation of the file read operation. + * If the signal becomes aborted the readFile operation will be stopped + * and the promise returned will be rejected with an AbortError. + */ + signal?: AbortSignal; + } + + /** + * Check if a given resource id (`rid`) is a TTY (a terminal). + * + * ```ts + * // This example is system and context specific + * const nonTTYRid = Deno.openSync("my_file.txt").rid; + * const ttyRid = Deno.openSync("/dev/tty6").rid; + * console.log(Deno.isatty(nonTTYRid)); // false + * console.log(Deno.isatty(ttyRid)); // true + * ``` + * + * @deprecated This will be soft-removed in Deno 2.0. See the + * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide} + * for migration instructions. + * + * @category I/O + */ + export function isatty(rid: number): boolean; + + /** + * A variable-sized buffer of bytes with `read()` and `write()` methods. + * + * @deprecated This will be removed in Deno 2.0. See the + * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide} + * for migration instructions. + * + * @category I/O + */ + export class Buffer implements Reader, ReaderSync, Writer, WriterSync { + constructor(ab?: ArrayBuffer); + /** Returns a slice holding the unread portion of the buffer. + * + * The slice is valid for use only until the next buffer modification (that + * is, only until the next call to a method like `read()`, `write()`, + * `reset()`, or `truncate()`). If `options.copy` is false the slice aliases the buffer content at + * least until the next buffer modification, so immediate changes to the + * slice will affect the result of future reads. + * @param options Defaults to `{ copy: true }` + */ + bytes(options?: { copy?: boolean }): Uint8Array; + /** Returns whether the unread portion of the buffer is empty. */ + empty(): boolean; + /** A read only number of bytes of the unread portion of the buffer. */ + readonly length: number; + /** The read only capacity of the buffer's underlying byte slice, that is, + * the total space allocated for the buffer's data. */ + readonly capacity: number; + /** Discards all but the first `n` unread bytes from the buffer but + * continues to use the same allocated storage. It throws if `n` is + * negative or greater than the length of the buffer. */ + truncate(n: number): void; + /** Resets the buffer to be empty, but it retains the underlying storage for + * use by future writes. `.reset()` is the same as `.truncate(0)`. */ + reset(): void; + /** Reads the next `p.length` bytes from the buffer or until the buffer is + * drained. Returns the number of bytes read. If the buffer has no data to + * return, the return is EOF (`null`). */ + readSync(p: Uint8Array): number | null; + /** Reads the next `p.length` bytes from the buffer or until the buffer is + * drained. Resolves to the number of bytes read. If the buffer has no + * data to return, resolves to EOF (`null`). + * + * NOTE: This methods reads bytes synchronously; it's provided for + * compatibility with `Reader` interfaces. + */ + read(p: Uint8Array): Promise; + writeSync(p: Uint8Array): number; + /** NOTE: This methods writes bytes synchronously; it's provided for + * compatibility with `Writer` interface. */ + write(p: Uint8Array): Promise; + /** Grows the buffer's capacity, if necessary, to guarantee space for + * another `n` bytes. After `.grow(n)`, at least `n` bytes can be written to + * the buffer without another allocation. If `n` is negative, `.grow()` will + * throw. If the buffer can't grow it will throw an error. + * + * Based on Go Lang's + * [Buffer.Grow](https://golang.org/pkg/bytes/#Buffer.Grow). */ + grow(n: number): void; + /** Reads data from `r` until EOF (`null`) and appends it to the buffer, + * growing the buffer as needed. It resolves to the number of bytes read. + * If the buffer becomes too large, `.readFrom()` will reject with an error. + * + * Based on Go Lang's + * [Buffer.ReadFrom](https://golang.org/pkg/bytes/#Buffer.ReadFrom). */ + readFrom(r: Reader): Promise; + /** Reads data from `r` until EOF (`null`) and appends it to the buffer, + * growing the buffer as needed. It returns the number of bytes read. If the + * buffer becomes too large, `.readFromSync()` will throw an error. + * + * Based on Go Lang's + * [Buffer.ReadFrom](https://golang.org/pkg/bytes/#Buffer.ReadFrom). */ + readFromSync(r: ReaderSync): number; + } + + /** + * Read Reader `r` until EOF (`null`) and resolve to the content as + * Uint8Array`. + * + * @deprecated This will be removed in Deno 2.0. See the + * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide} + * for migration instructions. + * + * @category I/O + */ + export function readAll(r: Reader): Promise; + + /** + * Synchronously reads Reader `r` until EOF (`null`) and returns the content + * as `Uint8Array`. + * + * @deprecated This will be removed in Deno 2.0. See the + * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide} + * for migration instructions. + * + * @category I/O + */ + export function readAllSync(r: ReaderSync): Uint8Array; + + /** + * Write all the content of the array buffer (`arr`) to the writer (`w`). + * + * @deprecated This will be removed in Deno 2.0. See the + * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide} + * for migration instructions. + * + * @category I/O + */ + export function writeAll(w: Writer, arr: Uint8Array): Promise; + + /** + * Synchronously write all the content of the array buffer (`arr`) to the + * writer (`w`). + * + * @deprecated This will be removed in Deno 2.0. See the + * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide} + * for migration instructions. + * + * @category I/O + */ + export function writeAllSync(w: WriterSync, arr: Uint8Array): void; + + /** + * Options which can be set when using {@linkcode Deno.mkdir} and + * {@linkcode Deno.mkdirSync}. + * + * @category File System */ + export interface MkdirOptions { + /** If set to `true`, means that any intermediate directories will also be + * created (as with the shell command `mkdir -p`). + * + * Intermediate directories are created with the same permissions. + * + * When recursive is set to `true`, succeeds silently (without changing any + * permissions) if a directory already exists at the path, or if the path + * is a symlink to an existing directory. + * + * @default {false} */ + recursive?: boolean; + /** Permissions to use when creating the directory (defaults to `0o777`, + * before the process's umask). + * + * Ignored on Windows. */ + mode?: number; + } + + /** Creates a new directory with the specified path. + * + * ```ts + * await Deno.mkdir("new_dir"); + * await Deno.mkdir("nested/directories", { recursive: true }); + * await Deno.mkdir("restricted_access_dir", { mode: 0o700 }); + * ``` + * + * Defaults to throwing error if the directory already exists. + * + * Requires `allow-write` permission. + * + * @tags allow-write + * @category File System + */ + export function mkdir( + path: string | URL, + options?: MkdirOptions, + ): Promise; + + /** Synchronously creates a new directory with the specified path. + * + * ```ts + * Deno.mkdirSync("new_dir"); + * Deno.mkdirSync("nested/directories", { recursive: true }); + * Deno.mkdirSync("restricted_access_dir", { mode: 0o700 }); + * ``` + * + * Defaults to throwing error if the directory already exists. + * + * Requires `allow-write` permission. + * + * @tags allow-write + * @category File System + */ + export function mkdirSync(path: string | URL, options?: MkdirOptions): void; + + /** + * Options which can be set when using {@linkcode Deno.makeTempDir}, + * {@linkcode Deno.makeTempDirSync}, {@linkcode Deno.makeTempFile}, and + * {@linkcode Deno.makeTempFileSync}. + * + * @category File System */ + export interface MakeTempOptions { + /** Directory where the temporary directory should be created (defaults to + * the env variable `TMPDIR`, or the system's default, usually `/tmp`). + * + * Note that if the passed `dir` is relative, the path returned by + * `makeTempFile()` and `makeTempDir()` will also be relative. Be mindful of + * this when changing working directory. */ + dir?: string; + /** String that should precede the random portion of the temporary + * directory's name. */ + prefix?: string; + /** String that should follow the random portion of the temporary + * directory's name. */ + suffix?: string; + } + + /** Creates a new temporary directory in the default directory for temporary + * files, unless `dir` is specified. Other optional options include + * prefixing and suffixing the directory name with `prefix` and `suffix` + * respectively. + * + * This call resolves to the full path to the newly created directory. + * + * Multiple programs calling this function simultaneously will create different + * directories. It is the caller's responsibility to remove the directory when + * no longer needed. + * + * ```ts + * const tempDirName0 = await Deno.makeTempDir(); // e.g. /tmp/2894ea76 + * const tempDirName1 = await Deno.makeTempDir({ prefix: 'my_temp' }); // e.g. /tmp/my_temp339c944d + * ``` + * + * Requires `allow-write` permission. + * + * @tags allow-write + * @category File System + */ + // TODO(ry) Doesn't check permissions. + export function makeTempDir(options?: MakeTempOptions): Promise; + + /** Synchronously creates a new temporary directory in the default directory + * for temporary files, unless `dir` is specified. Other optional options + * include prefixing and suffixing the directory name with `prefix` and + * `suffix` respectively. + * + * The full path to the newly created directory is returned. + * + * Multiple programs calling this function simultaneously will create different + * directories. It is the caller's responsibility to remove the directory when + * no longer needed. + * + * ```ts + * const tempDirName0 = Deno.makeTempDirSync(); // e.g. /tmp/2894ea76 + * const tempDirName1 = Deno.makeTempDirSync({ prefix: 'my_temp' }); // e.g. /tmp/my_temp339c944d + * ``` + * + * Requires `allow-write` permission. + * + * @tags allow-write + * @category File System + */ + // TODO(ry) Doesn't check permissions. + export function makeTempDirSync(options?: MakeTempOptions): string; + + /** Creates a new temporary file in the default directory for temporary + * files, unless `dir` is specified. + * + * Other options include prefixing and suffixing the directory name with + * `prefix` and `suffix` respectively. + * + * This call resolves to the full path to the newly created file. + * + * Multiple programs calling this function simultaneously will create + * different files. It is the caller's responsibility to remove the file when + * no longer needed. + * + * ```ts + * const tmpFileName0 = await Deno.makeTempFile(); // e.g. /tmp/419e0bf2 + * const tmpFileName1 = await Deno.makeTempFile({ prefix: 'my_temp' }); // e.g. /tmp/my_temp754d3098 + * ``` + * + * Requires `allow-write` permission. + * + * @tags allow-write + * @category File System + */ + export function makeTempFile(options?: MakeTempOptions): Promise; + + /** Synchronously creates a new temporary file in the default directory for + * temporary files, unless `dir` is specified. + * + * Other options include prefixing and suffixing the directory name with + * `prefix` and `suffix` respectively. + * + * The full path to the newly created file is returned. + * + * Multiple programs calling this function simultaneously will create + * different files. It is the caller's responsibility to remove the file when + * no longer needed. + * + * ```ts + * const tempFileName0 = Deno.makeTempFileSync(); // e.g. /tmp/419e0bf2 + * const tempFileName1 = Deno.makeTempFileSync({ prefix: 'my_temp' }); // e.g. /tmp/my_temp754d3098 + * ``` + * + * Requires `allow-write` permission. + * + * @tags allow-write + * @category File System + */ + export function makeTempFileSync(options?: MakeTempOptions): string; + + /** Changes the permission of a specific file/directory of specified path. + * Ignores the process's umask. + * + * ```ts + * await Deno.chmod("/path/to/file", 0o666); + * ``` + * + * The mode is a sequence of 3 octal numbers. The first/left-most number + * specifies the permissions for the owner. The second number specifies the + * permissions for the group. The last/right-most number specifies the + * permissions for others. For example, with a mode of 0o764, the owner (7) + * can read/write/execute, the group (6) can read/write and everyone else (4) + * can read only. + * + * | Number | Description | + * | ------ | ----------- | + * | 7 | read, write, and execute | + * | 6 | read and write | + * | 5 | read and execute | + * | 4 | read only | + * | 3 | write and execute | + * | 2 | write only | + * | 1 | execute only | + * | 0 | no permission | + * + * NOTE: This API currently throws on Windows + * + * Requires `allow-write` permission. + * + * @tags allow-write + * @category File System + */ + export function chmod(path: string | URL, mode: number): Promise; + + /** Synchronously changes the permission of a specific file/directory of + * specified path. Ignores the process's umask. + * + * ```ts + * Deno.chmodSync("/path/to/file", 0o666); + * ``` + * + * For a full description, see {@linkcode Deno.chmod}. + * + * NOTE: This API currently throws on Windows + * + * Requires `allow-write` permission. + * + * @tags allow-write + * @category File System + */ + export function chmodSync(path: string | URL, mode: number): void; + + /** Change owner of a regular file or directory. + * + * This functionality is not available on Windows. + * + * ```ts + * await Deno.chown("myFile.txt", 1000, 1002); + * ``` + * + * Requires `allow-write` permission. + * + * Throws Error (not implemented) if executed on Windows. + * + * @tags allow-write + * @category File System + * + * @param path path to the file + * @param uid user id (UID) of the new owner, or `null` for no change + * @param gid group id (GID) of the new owner, or `null` for no change + */ + export function chown( + path: string | URL, + uid: number | null, + gid: number | null, + ): Promise; + + /** Synchronously change owner of a regular file or directory. + * + * This functionality is not available on Windows. + * + * ```ts + * Deno.chownSync("myFile.txt", 1000, 1002); + * ``` + * + * Requires `allow-write` permission. + * + * Throws Error (not implemented) if executed on Windows. + * + * @tags allow-write + * @category File System + * + * @param path path to the file + * @param uid user id (UID) of the new owner, or `null` for no change + * @param gid group id (GID) of the new owner, or `null` for no change + */ + export function chownSync( + path: string | URL, + uid: number | null, + gid: number | null, + ): void; + + /** + * Options which can be set when using {@linkcode Deno.remove} and + * {@linkcode Deno.removeSync}. + * + * @category File System */ + export interface RemoveOptions { + /** If set to `true`, path will be removed even if it's a non-empty directory. + * + * @default {false} */ + recursive?: boolean; + } + + /** Removes the named file or directory. + * + * ```ts + * await Deno.remove("/path/to/empty_dir/or/file"); + * await Deno.remove("/path/to/populated_dir/or/file", { recursive: true }); + * ``` + * + * Throws error if permission denied, path not found, or path is a non-empty + * directory and the `recursive` option isn't set to `true`. + * + * Requires `allow-write` permission. + * + * @tags allow-write + * @category File System + */ + export function remove( + path: string | URL, + options?: RemoveOptions, + ): Promise; + + /** Synchronously removes the named file or directory. + * + * ```ts + * Deno.removeSync("/path/to/empty_dir/or/file"); + * Deno.removeSync("/path/to/populated_dir/or/file", { recursive: true }); + * ``` + * + * Throws error if permission denied, path not found, or path is a non-empty + * directory and the `recursive` option isn't set to `true`. + * + * Requires `allow-write` permission. + * + * @tags allow-write + * @category File System + */ + export function removeSync(path: string | URL, options?: RemoveOptions): void; + + /** Synchronously renames (moves) `oldpath` to `newpath`. Paths may be files or + * directories. If `newpath` already exists and is not a directory, + * `renameSync()` replaces it. OS-specific restrictions may apply when + * `oldpath` and `newpath` are in different directories. + * + * ```ts + * Deno.renameSync("old/path", "new/path"); + * ``` + * + * On Unix-like OSes, this operation does not follow symlinks at either path. + * + * It varies between platforms when the operation throws errors, and if so what + * they are. It's always an error to rename anything to a non-empty directory. + * + * Requires `allow-read` and `allow-write` permissions. + * + * @tags allow-read, allow-write + * @category File System + */ + export function renameSync( + oldpath: string | URL, + newpath: string | URL, + ): void; + + /** Renames (moves) `oldpath` to `newpath`. Paths may be files or directories. + * If `newpath` already exists and is not a directory, `rename()` replaces it. + * OS-specific restrictions may apply when `oldpath` and `newpath` are in + * different directories. + * + * ```ts + * await Deno.rename("old/path", "new/path"); + * ``` + * + * On Unix-like OSes, this operation does not follow symlinks at either path. + * + * It varies between platforms when the operation throws errors, and if so + * what they are. It's always an error to rename anything to a non-empty + * directory. + * + * Requires `allow-read` and `allow-write` permissions. + * + * @tags allow-read, allow-write + * @category File System + */ + export function rename( + oldpath: string | URL, + newpath: string | URL, + ): Promise; + + /** Asynchronously reads and returns the entire contents of a file as an UTF-8 + * decoded string. Reading a directory throws an error. + * + * ```ts + * const data = await Deno.readTextFile("hello.txt"); + * console.log(data); + * ``` + * + * Requires `allow-read` permission. + * + * @tags allow-read + * @category File System + */ + export function readTextFile( + path: string | URL, + options?: ReadFileOptions, + ): Promise; + + /** Synchronously reads and returns the entire contents of a file as an UTF-8 + * decoded string. Reading a directory throws an error. + * + * ```ts + * const data = Deno.readTextFileSync("hello.txt"); + * console.log(data); + * ``` + * + * Requires `allow-read` permission. + * + * @tags allow-read + * @category File System + */ + export function readTextFileSync(path: string | URL): string; + + /** Reads and resolves to the entire contents of a file as an array of bytes. + * `TextDecoder` can be used to transform the bytes to string if required. + * Reading a directory returns an empty data array. + * + * ```ts + * const decoder = new TextDecoder("utf-8"); + * const data = await Deno.readFile("hello.txt"); + * console.log(decoder.decode(data)); + * ``` + * + * Requires `allow-read` permission. + * + * @tags allow-read + * @category File System + */ + export function readFile( + path: string | URL, + options?: ReadFileOptions, + ): Promise; + + /** Synchronously reads and returns the entire contents of a file as an array + * of bytes. `TextDecoder` can be used to transform the bytes to string if + * required. Reading a directory returns an empty data array. + * + * ```ts + * const decoder = new TextDecoder("utf-8"); + * const data = Deno.readFileSync("hello.txt"); + * console.log(decoder.decode(data)); + * ``` + * + * Requires `allow-read` permission. + * + * @tags allow-read + * @category File System + */ + export function readFileSync(path: string | URL): Uint8Array; + + /** Provides information about a file and is returned by + * {@linkcode Deno.stat}, {@linkcode Deno.lstat}, {@linkcode Deno.statSync}, + * and {@linkcode Deno.lstatSync} or from calling `stat()` and `statSync()` + * on an {@linkcode Deno.FsFile} instance. + * + * @category File System + */ + export interface FileInfo { + /** True if this is info for a regular file. Mutually exclusive to + * `FileInfo.isDirectory` and `FileInfo.isSymlink`. */ + isFile: boolean; + /** True if this is info for a regular directory. Mutually exclusive to + * `FileInfo.isFile` and `FileInfo.isSymlink`. */ + isDirectory: boolean; + /** True if this is info for a symlink. Mutually exclusive to + * `FileInfo.isFile` and `FileInfo.isDirectory`. */ + isSymlink: boolean; + /** The size of the file, in bytes. */ + size: number; + /** The last modification time of the file. This corresponds to the `mtime` + * field from `stat` on Linux/Mac OS and `ftLastWriteTime` on Windows. This + * may not be available on all platforms. */ + mtime: Date | null; + /** The last access time of the file. This corresponds to the `atime` + * field from `stat` on Unix and `ftLastAccessTime` on Windows. This may not + * be available on all platforms. */ + atime: Date | null; + /** The creation time of the file. This corresponds to the `birthtime` + * field from `stat` on Mac/BSD and `ftCreationTime` on Windows. This may + * not be available on all platforms. */ + birthtime: Date | null; + /** ID of the device containing the file. */ + dev: number; + /** Inode number. + * + * _Linux/Mac OS only._ */ + ino: number | null; + /** The underlying raw `st_mode` bits that contain the standard Unix + * permissions for this file/directory. + * + * _Linux/Mac OS only._ */ + mode: number | null; + /** Number of hard links pointing to this file. + * + * _Linux/Mac OS only._ */ + nlink: number | null; + /** User ID of the owner of this file. + * + * _Linux/Mac OS only._ */ + uid: number | null; + /** Group ID of the owner of this file. + * + * _Linux/Mac OS only._ */ + gid: number | null; + /** Device ID of this file. + * + * _Linux/Mac OS only._ */ + rdev: number | null; + /** Blocksize for filesystem I/O. + * + * _Linux/Mac OS only._ */ + blksize: number | null; + /** Number of blocks allocated to the file, in 512-byte units. + * + * _Linux/Mac OS only._ */ + blocks: number | null; + /** True if this is info for a block device. + * + * _Linux/Mac OS only._ */ + isBlockDevice: boolean | null; + /** True if this is info for a char device. + * + * _Linux/Mac OS only._ */ + isCharDevice: boolean | null; + /** True if this is info for a fifo. + * + * _Linux/Mac OS only._ */ + isFifo: boolean | null; + /** True if this is info for a socket. + * + * _Linux/Mac OS only._ */ + isSocket: boolean | null; + } + + /** Resolves to the absolute normalized path, with symbolic links resolved. + * + * ```ts + * // e.g. given /home/alice/file.txt and current directory /home/alice + * await Deno.symlink("file.txt", "symlink_file.txt"); + * const realPath = await Deno.realPath("./file.txt"); + * const realSymLinkPath = await Deno.realPath("./symlink_file.txt"); + * console.log(realPath); // outputs "/home/alice/file.txt" + * console.log(realSymLinkPath); // outputs "/home/alice/file.txt" + * ``` + * + * Requires `allow-read` permission for the target path. + * + * Also requires `allow-read` permission for the `CWD` if the target path is + * relative. + * + * @tags allow-read + * @category File System + */ + export function realPath(path: string | URL): Promise; + + /** Synchronously returns absolute normalized path, with symbolic links + * resolved. + * + * ```ts + * // e.g. given /home/alice/file.txt and current directory /home/alice + * Deno.symlinkSync("file.txt", "symlink_file.txt"); + * const realPath = Deno.realPathSync("./file.txt"); + * const realSymLinkPath = Deno.realPathSync("./symlink_file.txt"); + * console.log(realPath); // outputs "/home/alice/file.txt" + * console.log(realSymLinkPath); // outputs "/home/alice/file.txt" + * ``` + * + * Requires `allow-read` permission for the target path. + * + * Also requires `allow-read` permission for the `CWD` if the target path is + * relative. + * + * @tags allow-read + * @category File System + */ + export function realPathSync(path: string | URL): string; + + /** + * Information about a directory entry returned from {@linkcode Deno.readDir} + * and {@linkcode Deno.readDirSync}. + * + * @category File System */ + export interface DirEntry { + /** The file name of the entry. It is just the entity name and does not + * include the full path. */ + name: string; + /** True if this is info for a regular file. Mutually exclusive to + * `DirEntry.isDirectory` and `DirEntry.isSymlink`. */ + isFile: boolean; + /** True if this is info for a regular directory. Mutually exclusive to + * `DirEntry.isFile` and `DirEntry.isSymlink`. */ + isDirectory: boolean; + /** True if this is info for a symlink. Mutually exclusive to + * `DirEntry.isFile` and `DirEntry.isDirectory`. */ + isSymlink: boolean; + } + + /** Reads the directory given by `path` and returns an async iterable of + * {@linkcode Deno.DirEntry}. The order of entries is not guaranteed. + * + * ```ts + * for await (const dirEntry of Deno.readDir("/")) { + * console.log(dirEntry.name); + * } + * ``` + * + * Throws error if `path` is not a directory. + * + * Requires `allow-read` permission. + * + * @tags allow-read + * @category File System + */ + export function readDir(path: string | URL): AsyncIterable; + + /** Synchronously reads the directory given by `path` and returns an iterable + * of {@linkcode Deno.DirEntry}. The order of entries is not guaranteed. + * + * ```ts + * for (const dirEntry of Deno.readDirSync("/")) { + * console.log(dirEntry.name); + * } + * ``` + * + * Throws error if `path` is not a directory. + * + * Requires `allow-read` permission. + * + * @tags allow-read + * @category File System + */ + export function readDirSync(path: string | URL): Iterable; + + /** Copies the contents and permissions of one file to another specified path, + * by default creating a new file if needed, else overwriting. Fails if target + * path is a directory or is unwritable. + * + * ```ts + * await Deno.copyFile("from.txt", "to.txt"); + * ``` + * + * Requires `allow-read` permission on `fromPath`. + * + * Requires `allow-write` permission on `toPath`. + * + * @tags allow-read, allow-write + * @category File System + */ + export function copyFile( + fromPath: string | URL, + toPath: string | URL, + ): Promise; + + /** Synchronously copies the contents and permissions of one file to another + * specified path, by default creating a new file if needed, else overwriting. + * Fails if target path is a directory or is unwritable. + * + * ```ts + * Deno.copyFileSync("from.txt", "to.txt"); + * ``` + * + * Requires `allow-read` permission on `fromPath`. + * + * Requires `allow-write` permission on `toPath`. + * + * @tags allow-read, allow-write + * @category File System + */ + export function copyFileSync( + fromPath: string | URL, + toPath: string | URL, + ): void; + + /** Resolves to the full path destination of the named symbolic link. + * + * ```ts + * await Deno.symlink("./test.txt", "./test_link.txt"); + * const target = await Deno.readLink("./test_link.txt"); // full path of ./test.txt + * ``` + * + * Throws TypeError if called with a hard link. + * + * Requires `allow-read` permission. + * + * @tags allow-read + * @category File System + */ + export function readLink(path: string | URL): Promise; + + /** Synchronously returns the full path destination of the named symbolic + * link. + * + * ```ts + * Deno.symlinkSync("./test.txt", "./test_link.txt"); + * const target = Deno.readLinkSync("./test_link.txt"); // full path of ./test.txt + * ``` + * + * Throws TypeError if called with a hard link. + * + * Requires `allow-read` permission. + * + * @tags allow-read + * @category File System + */ + export function readLinkSync(path: string | URL): string; + + /** Resolves to a {@linkcode Deno.FileInfo} for the specified `path`. If + * `path` is a symlink, information for the symlink will be returned instead + * of what it points to. + * + * ```ts + * import { assert } from "jsr:@std/assert"; + * const fileInfo = await Deno.lstat("hello.txt"); + * assert(fileInfo.isFile); + * ``` + * + * Requires `allow-read` permission. + * + * @tags allow-read + * @category File System + */ + export function lstat(path: string | URL): Promise; + + /** Synchronously returns a {@linkcode Deno.FileInfo} for the specified + * `path`. If `path` is a symlink, information for the symlink will be + * returned instead of what it points to. + * + * ```ts + * import { assert } from "jsr:@std/assert"; + * const fileInfo = Deno.lstatSync("hello.txt"); + * assert(fileInfo.isFile); + * ``` + * + * Requires `allow-read` permission. + * + * @tags allow-read + * @category File System + */ + export function lstatSync(path: string | URL): FileInfo; + + /** Resolves to a {@linkcode Deno.FileInfo} for the specified `path`. Will + * always follow symlinks. + * + * ```ts + * import { assert } from "jsr:@std/assert"; + * const fileInfo = await Deno.stat("hello.txt"); + * assert(fileInfo.isFile); + * ``` + * + * Requires `allow-read` permission. + * + * @tags allow-read + * @category File System + */ + export function stat(path: string | URL): Promise; + + /** Synchronously returns a {@linkcode Deno.FileInfo} for the specified + * `path`. Will always follow symlinks. + * + * ```ts + * import { assert } from "jsr:@std/assert"; + * const fileInfo = Deno.statSync("hello.txt"); + * assert(fileInfo.isFile); + * ``` + * + * Requires `allow-read` permission. + * + * @tags allow-read + * @category File System + */ + export function statSync(path: string | URL): FileInfo; + + /** Options for writing to a file. + * + * @category File System + */ + export interface WriteFileOptions { + /** If set to `true`, will append to a file instead of overwriting previous + * contents. + * + * @default {false} */ + append?: boolean; + /** Sets the option to allow creating a new file, if one doesn't already + * exist at the specified path. + * + * @default {true} */ + create?: boolean; + /** If set to `true`, no file, directory, or symlink is allowed to exist at + * the target location. When createNew is set to `true`, `create` is ignored. + * + * @default {false} */ + createNew?: boolean; + /** Permissions always applied to file. */ + mode?: number; + /** An abort signal to allow cancellation of the file write operation. + * + * If the signal becomes aborted the write file operation will be stopped + * and the promise returned will be rejected with an {@linkcode AbortError}. + */ + signal?: AbortSignal; + } + + /** Write `data` to the given `path`, by default creating a new file if + * needed, else overwriting. + * + * ```ts + * const encoder = new TextEncoder(); + * const data = encoder.encode("Hello world\n"); + * await Deno.writeFile("hello1.txt", data); // overwrite "hello1.txt" or create it + * await Deno.writeFile("hello2.txt", data, { create: false }); // only works if "hello2.txt" exists + * await Deno.writeFile("hello3.txt", data, { mode: 0o777 }); // set permissions on new file + * await Deno.writeFile("hello4.txt", data, { append: true }); // add data to the end of the file + * ``` + * + * Requires `allow-write` permission, and `allow-read` if `options.create` is + * `false`. + * + * @tags allow-read, allow-write + * @category File System + */ + export function writeFile( + path: string | URL, + data: Uint8Array | ReadableStream, + options?: WriteFileOptions, + ): Promise; + + /** Synchronously write `data` to the given `path`, by default creating a new + * file if needed, else overwriting. + * + * ```ts + * const encoder = new TextEncoder(); + * const data = encoder.encode("Hello world\n"); + * Deno.writeFileSync("hello1.txt", data); // overwrite "hello1.txt" or create it + * Deno.writeFileSync("hello2.txt", data, { create: false }); // only works if "hello2.txt" exists + * Deno.writeFileSync("hello3.txt", data, { mode: 0o777 }); // set permissions on new file + * Deno.writeFileSync("hello4.txt", data, { append: true }); // add data to the end of the file + * ``` + * + * Requires `allow-write` permission, and `allow-read` if `options.create` is + * `false`. + * + * @tags allow-read, allow-write + * @category File System + */ + export function writeFileSync( + path: string | URL, + data: Uint8Array, + options?: WriteFileOptions, + ): void; + + /** Write string `data` to the given `path`, by default creating a new file if + * needed, else overwriting. + * + * ```ts + * await Deno.writeTextFile("hello1.txt", "Hello world\n"); // overwrite "hello1.txt" or create it + * ``` + * + * Requires `allow-write` permission, and `allow-read` if `options.create` is + * `false`. + * + * @tags allow-read, allow-write + * @category File System + */ + export function writeTextFile( + path: string | URL, + data: string | ReadableStream, + options?: WriteFileOptions, + ): Promise; + + /** Synchronously write string `data` to the given `path`, by default creating + * a new file if needed, else overwriting. + * + * ```ts + * Deno.writeTextFileSync("hello1.txt", "Hello world\n"); // overwrite "hello1.txt" or create it + * ``` + * + * Requires `allow-write` permission, and `allow-read` if `options.create` is + * `false`. + * + * @tags allow-read, allow-write + * @category File System + */ + export function writeTextFileSync( + path: string | URL, + data: string, + options?: WriteFileOptions, + ): void; + + /** Truncates (or extends) the specified file, to reach the specified `len`. + * If `len` is not specified then the entire file contents are truncated. + * + * ### Truncate the entire file + * ```ts + * await Deno.truncate("my_file.txt"); + * ``` + * + * ### Truncate part of the file + * + * ```ts + * const file = await Deno.makeTempFile(); + * await Deno.writeTextFile(file, "Hello World"); + * await Deno.truncate(file, 7); + * const data = await Deno.readFile(file); + * console.log(new TextDecoder().decode(data)); // "Hello W" + * ``` + * + * Requires `allow-write` permission. + * + * @tags allow-write + * @category File System + */ + export function truncate(name: string, len?: number): Promise; + + /** Synchronously truncates (or extends) the specified file, to reach the + * specified `len`. If `len` is not specified then the entire file contents + * are truncated. + * + * ### Truncate the entire file + * + * ```ts + * Deno.truncateSync("my_file.txt"); + * ``` + * + * ### Truncate part of the file + * + * ```ts + * const file = Deno.makeTempFileSync(); + * Deno.writeFileSync(file, new TextEncoder().encode("Hello World")); + * Deno.truncateSync(file, 7); + * const data = Deno.readFileSync(file); + * console.log(new TextDecoder().decode(data)); + * ``` + * + * Requires `allow-write` permission. + * + * @tags allow-write + * @category File System + */ + export function truncateSync(name: string, len?: number): void; + + /** @category Observability + * + * @deprecated This will be removed in Deno 2.0. + */ + export interface OpMetrics { + opsDispatched: number; + opsDispatchedSync: number; + opsDispatchedAsync: number; + opsDispatchedAsyncUnref: number; + opsCompleted: number; + opsCompletedSync: number; + opsCompletedAsync: number; + opsCompletedAsyncUnref: number; + bytesSentControl: number; + bytesSentData: number; + bytesReceived: number; + } + + /** @category Observability + * + * @deprecated This will be removed in Deno 2.0. + */ + export interface Metrics extends OpMetrics { + ops: Record; + } + + /** Receive metrics from the privileged side of Deno. This is primarily used + * in the development of Deno. _Ops_, also called _bindings_, are the + * go-between between Deno JavaScript sandbox and the rest of Deno. + * + * ```shell + * > console.table(Deno.metrics()) + * ┌─────────────────────────┬────────┐ + * │ (index) │ Values │ + * ├─────────────────────────┼────────┤ + * │ opsDispatched │ 3 │ + * │ opsDispatchedSync │ 2 │ + * │ opsDispatchedAsync │ 1 │ + * │ opsDispatchedAsyncUnref │ 0 │ + * │ opsCompleted │ 3 │ + * │ opsCompletedSync │ 2 │ + * │ opsCompletedAsync │ 1 │ + * │ opsCompletedAsyncUnref │ 0 │ + * │ bytesSentControl │ 73 │ + * │ bytesSentData │ 0 │ + * │ bytesReceived │ 375 │ + * └─────────────────────────┴────────┘ + * ``` + * + * @category Observability + * + * @deprecated This will be removed in Deno 2.0. + */ + export function metrics(): Metrics; + + /** + * A map of open resources that Deno is tracking. The key is the resource ID + * (_rid_) and the value is its representation. + * + * @deprecated This will be removed in Deno 2.0. + * + * @category Observability */ + interface ResourceMap { + [rid: number]: unknown; + } + + /** Returns a map of open resource IDs (_rid_) along with their string + * representations. This is an internal API and as such resource + * representation has `unknown` type; that means it can change any time and + * should not be depended upon. + * + * ```ts + * console.log(Deno.resources()); + * // { 0: "stdin", 1: "stdout", 2: "stderr" } + * Deno.openSync('../test.file'); + * console.log(Deno.resources()); + * // { 0: "stdin", 1: "stdout", 2: "stderr", 3: "fsFile" } + * ``` + * + * @deprecated This will be removed in Deno 2.0. + * + * @category Observability + */ + export function resources(): ResourceMap; + + /** + * Additional information for FsEvent objects with the "other" kind. + * + * - `"rescan"`: rescan notices indicate either a lapse in the events or a + * change in the filesystem such that events received so far can no longer + * be relied on to represent the state of the filesystem now. An + * application that simply reacts to file changes may not care about this. + * An application that keeps an in-memory representation of the filesystem + * will need to care, and will need to refresh that representation directly + * from the filesystem. + * + * @category File System + */ + export type FsEventFlag = "rescan"; + + /** + * Represents a unique file system event yielded by a + * {@linkcode Deno.FsWatcher}. + * + * @category File System */ + export interface FsEvent { + /** The kind/type of the file system event. */ + kind: "any" | "access" | "create" | "modify" | "remove" | "other"; + /** An array of paths that are associated with the file system event. */ + paths: string[]; + /** Any additional flags associated with the event. */ + flag?: FsEventFlag; + } + + /** + * Returned by {@linkcode Deno.watchFs}. It is an async iterator yielding up + * system events. To stop watching the file system by calling `.close()` + * method. + * + * @category File System + */ + export interface FsWatcher extends AsyncIterable, Disposable { + /** + * The resource id. + * + * @deprecated This will be removed in Deno 2.0. See the + * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide} + * for migration instructions. + */ + readonly rid: number; + /** Stops watching the file system and closes the watcher resource. */ + close(): void; + /** + * Stops watching the file system and closes the watcher resource. + * + * @deprecated This will be removed in Deno 2.0. See the + * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide} + * for migration instructions. + */ + return?(value?: any): Promise>; + [Symbol.asyncIterator](): AsyncIterableIterator; + } + + /** Watch for file system events against one or more `paths`, which can be + * files or directories. These paths must exist already. One user action (e.g. + * `touch test.file`) can generate multiple file system events. Likewise, + * one user action can result in multiple file paths in one event (e.g. `mv + * old_name.txt new_name.txt`). + * + * The recursive option is `true` by default and, for directories, will watch + * the specified directory and all sub directories. + * + * Note that the exact ordering of the events can vary between operating + * systems. + * + * ```ts + * const watcher = Deno.watchFs("/"); + * for await (const event of watcher) { + * console.log(">>>> event", event); + * // { kind: "create", paths: [ "/foo.txt" ] } + * } + * ``` + * + * Call `watcher.close()` to stop watching. + * + * ```ts + * const watcher = Deno.watchFs("/"); + * + * setTimeout(() => { + * watcher.close(); + * }, 5000); + * + * for await (const event of watcher) { + * console.log(">>>> event", event); + * } + * ``` + * + * Requires `allow-read` permission. + * + * @tags allow-read + * @category File System + */ + export function watchFs( + paths: string | string[], + options?: { recursive: boolean }, + ): FsWatcher; + + /** + * Options which can be used with {@linkcode Deno.run}. + * + * @deprecated This will be removed in Deno 2.0. See the + * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide} + * for migration instructions. + * + * @category Sub Process */ + export interface RunOptions { + /** Arguments to pass. + * + * _Note_: the first element needs to be a path to the executable that is + * being run. */ + cmd: readonly string[] | [string | URL, ...string[]]; + /** The current working directory that should be used when running the + * sub-process. */ + cwd?: string; + /** Any environment variables to be set when running the sub-process. */ + env?: Record; + /** By default subprocess inherits `stdout` of parent process. To change + * this this option can be set to a resource ID (_rid_) of an open file, + * `"inherit"`, `"piped"`, or `"null"`: + * + * - _number_: the resource ID of an open file/resource. This allows you to + * write to a file. + * - `"inherit"`: The default if unspecified. The subprocess inherits from the + * parent. + * - `"piped"`: A new pipe should be arranged to connect the parent and child + * sub-process. + * - `"null"`: This stream will be ignored. This is the equivalent of attaching + * the stream to `/dev/null`. + */ + stdout?: "inherit" | "piped" | "null" | number; + /** By default subprocess inherits `stderr` of parent process. To change + * this this option can be set to a resource ID (_rid_) of an open file, + * `"inherit"`, `"piped"`, or `"null"`: + * + * - _number_: the resource ID of an open file/resource. This allows you to + * write to a file. + * - `"inherit"`: The default if unspecified. The subprocess inherits from the + * parent. + * - `"piped"`: A new pipe should be arranged to connect the parent and child + * sub-process. + * - `"null"`: This stream will be ignored. This is the equivalent of attaching + * the stream to `/dev/null`. + */ + stderr?: "inherit" | "piped" | "null" | number; + /** By default subprocess inherits `stdin` of parent process. To change + * this this option can be set to a resource ID (_rid_) of an open file, + * `"inherit"`, `"piped"`, or `"null"`: + * + * - _number_: the resource ID of an open file/resource. This allows you to + * read from a file. + * - `"inherit"`: The default if unspecified. The subprocess inherits from the + * parent. + * - `"piped"`: A new pipe should be arranged to connect the parent and child + * sub-process. + * - `"null"`: This stream will be ignored. This is the equivalent of attaching + * the stream to `/dev/null`. + */ + stdin?: "inherit" | "piped" | "null" | number; + } + + /** + * The status resolved from the `.status()` method of a + * {@linkcode Deno.Process} instance. + * + * If `success` is `true`, then `code` will be `0`, but if `success` is + * `false`, the sub-process exit code will be set in `code`. + * + * @deprecated This will be removed in Deno 2.0. See the + * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide} + * for migration instructions. + * + * @category Sub Process */ + export type ProcessStatus = + | { + success: true; + code: 0; + signal?: undefined; + } + | { + success: false; + code: number; + signal?: number; + }; + + /** + * Represents an instance of a sub process that is returned from + * {@linkcode Deno.run} which can be used to manage the sub-process. + * + * @deprecated This will be removed in Deno 2.0. See the + * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide} + * for migration instructions. + * + * @category Sub Process */ + export class Process { + /** The resource ID of the sub-process. */ + readonly rid: number; + /** The operating system's process ID for the sub-process. */ + readonly pid: number; + /** A reference to the sub-processes `stdin`, which allows interacting with + * the sub-process at a low level. */ + readonly stdin: T["stdin"] extends "piped" ? Writer & Closer & { + writable: WritableStream; + } + : (Writer & Closer & { writable: WritableStream }) | null; + /** A reference to the sub-processes `stdout`, which allows interacting with + * the sub-process at a low level. */ + readonly stdout: T["stdout"] extends "piped" ? Reader & Closer & { + readable: ReadableStream; + } + : (Reader & Closer & { readable: ReadableStream }) | null; + /** A reference to the sub-processes `stderr`, which allows interacting with + * the sub-process at a low level. */ + readonly stderr: T["stderr"] extends "piped" ? Reader & Closer & { + readable: ReadableStream; + } + : (Reader & Closer & { readable: ReadableStream }) | null; + /** Wait for the process to exit and return its exit status. + * + * Calling this function multiple times will return the same status. + * + * The `stdin` reference to the process will be closed before waiting to + * avoid a deadlock. + * + * If `stdout` and/or `stderr` were set to `"piped"`, they must be closed + * manually before the process can exit. + * + * To run process to completion and collect output from both `stdout` and + * `stderr` use: + * + * ```ts + * const p = Deno.run({ cmd: [ "echo", "hello world" ], stderr: 'piped', stdout: 'piped' }); + * const [status, stdout, stderr] = await Promise.all([ + * p.status(), + * p.output(), + * p.stderrOutput() + * ]); + * p.close(); + * ``` + */ + status(): Promise; + /** Buffer the stdout until EOF and return it as `Uint8Array`. + * + * You must set `stdout` to `"piped"` when creating the process. + * + * This calls `close()` on stdout after its done. */ + output(): Promise; + /** Buffer the stderr until EOF and return it as `Uint8Array`. + * + * You must set `stderr` to `"piped"` when creating the process. + * + * This calls `close()` on stderr after its done. */ + stderrOutput(): Promise; + /** Clean up resources associated with the sub-process instance. */ + close(): void; + /** Send a signal to process. + * Default signal is `"SIGTERM"`. + * + * ```ts + * const p = Deno.run({ cmd: [ "sleep", "20" ]}); + * p.kill("SIGTERM"); + * p.close(); + * ``` + */ + kill(signo?: Signal): void; + } + + /** Operating signals which can be listened for or sent to sub-processes. What + * signals and what their standard behaviors are OS dependent. + * + * @category Runtime Environment */ + export type Signal = + | "SIGABRT" + | "SIGALRM" + | "SIGBREAK" + | "SIGBUS" + | "SIGCHLD" + | "SIGCONT" + | "SIGEMT" + | "SIGFPE" + | "SIGHUP" + | "SIGILL" + | "SIGINFO" + | "SIGINT" + | "SIGIO" + | "SIGKILL" + | "SIGPIPE" + | "SIGPROF" + | "SIGPWR" + | "SIGQUIT" + | "SIGSEGV" + | "SIGSTKFLT" + | "SIGSTOP" + | "SIGSYS" + | "SIGTERM" + | "SIGTRAP" + | "SIGTSTP" + | "SIGTTIN" + | "SIGTTOU" + | "SIGURG" + | "SIGUSR1" + | "SIGUSR2" + | "SIGVTALRM" + | "SIGWINCH" + | "SIGXCPU" + | "SIGXFSZ"; + + /** Registers the given function as a listener of the given signal event. + * + * ```ts + * Deno.addSignalListener( + * "SIGTERM", + * () => { + * console.log("SIGTERM!") + * } + * ); + * ``` + * + * _Note_: On Windows only `"SIGINT"` (CTRL+C) and `"SIGBREAK"` (CTRL+Break) + * are supported. + * + * @category Runtime Environment + */ + export function addSignalListener(signal: Signal, handler: () => void): void; + + /** Removes the given signal listener that has been registered with + * {@linkcode Deno.addSignalListener}. + * + * ```ts + * const listener = () => { + * console.log("SIGTERM!") + * }; + * Deno.addSignalListener("SIGTERM", listener); + * Deno.removeSignalListener("SIGTERM", listener); + * ``` + * + * _Note_: On Windows only `"SIGINT"` (CTRL+C) and `"SIGBREAK"` (CTRL+Break) + * are supported. + * + * @category Runtime Environment + */ + export function removeSignalListener( + signal: Signal, + handler: () => void, + ): void; + + /** + * Spawns new subprocess. RunOptions must contain at a minimum the `opt.cmd`, + * an array of program arguments, the first of which is the binary. + * + * ```ts + * const p = Deno.run({ + * cmd: ["curl", "https://example.com"], + * }); + * const status = await p.status(); + * ``` + * + * Subprocess uses same working directory as parent process unless `opt.cwd` + * is specified. + * + * Environmental variables from parent process can be cleared using `opt.clearEnv`. + * Doesn't guarantee that only `opt.env` variables are present, + * as the OS may set environmental variables for processes. + * + * Environmental variables for subprocess can be specified using `opt.env` + * mapping. + * + * `opt.uid` sets the child process’s user ID. This translates to a setuid call + * in the child process. Failure in the setuid call will cause the spawn to fail. + * + * `opt.gid` is similar to `opt.uid`, but sets the group ID of the child process. + * This has the same semantics as the uid field. + * + * By default subprocess inherits stdio of parent process. To change + * this this, `opt.stdin`, `opt.stdout`, and `opt.stderr` can be set + * independently to a resource ID (_rid_) of an open file, `"inherit"`, + * `"piped"`, or `"null"`: + * + * - _number_: the resource ID of an open file/resource. This allows you to + * read or write to a file. + * - `"inherit"`: The default if unspecified. The subprocess inherits from the + * parent. + * - `"piped"`: A new pipe should be arranged to connect the parent and child + * sub-process. + * - `"null"`: This stream will be ignored. This is the equivalent of attaching + * the stream to `/dev/null`. + * + * Details of the spawned process are returned as an instance of + * {@linkcode Deno.Process}. + * + * Requires `allow-run` permission. + * + * @deprecated This will be soft-removed in Deno 2.0. See the + * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide} + * for migration instructions. + * + * @tags allow-run + * @category Sub Process + */ + export function run(opt: T): Process; + + /** Create a child process. + * + * If any stdio options are not set to `"piped"`, accessing the corresponding + * field on the `Command` or its `CommandOutput` will throw a `TypeError`. + * + * If `stdin` is set to `"piped"`, the `stdin` {@linkcode WritableStream} + * needs to be closed manually. + * + * @example Spawn a subprocess and pipe the output to a file + * + * ```ts + * const command = new Deno.Command(Deno.execPath(), { + * args: [ + * "eval", + * "console.log('Hello World')", + * ], + * stdin: "piped", + * stdout: "piped", + * }); + * const child = command.spawn(); + * + * // open a file and pipe the subprocess output to it. + * child.stdout.pipeTo( + * Deno.openSync("output", { write: true, create: true }).writable, + * ); + * + * // manually close stdin + * child.stdin.close(); + * const status = await child.status; + * ``` + * + * @example Spawn a subprocess and collect its output + * + * ```ts + * const command = new Deno.Command(Deno.execPath(), { + * args: [ + * "eval", + * "console.log('hello'); console.error('world')", + * ], + * }); + * const { code, stdout, stderr } = await command.output(); + * console.assert(code === 0); + * console.assert("hello\n" === new TextDecoder().decode(stdout)); + * console.assert("world\n" === new TextDecoder().decode(stderr)); + * ``` + * + * @example Spawn a subprocess and collect its output synchronously + * + * ```ts + * const command = new Deno.Command(Deno.execPath(), { + * args: [ + * "eval", + * "console.log('hello'); console.error('world')", + * ], + * }); + * const { code, stdout, stderr } = command.outputSync(); + * console.assert(code === 0); + * console.assert("hello\n" === new TextDecoder().decode(stdout)); + * console.assert("world\n" === new TextDecoder().decode(stderr)); + * ``` + * + * @tags allow-run + * @category Sub Process + */ + export class Command { + constructor(command: string | URL, options?: CommandOptions); + /** + * Executes the {@linkcode Deno.Command}, waiting for it to finish and + * collecting all of its output. + * If `spawn()` was called, calling this function will collect the remaining + * output. + * + * Will throw an error if `stdin: "piped"` is set. + * + * If options `stdout` or `stderr` are not set to `"piped"`, accessing the + * corresponding field on {@linkcode Deno.CommandOutput} will throw a `TypeError`. + */ + output(): Promise; + /** + * Synchronously executes the {@linkcode Deno.Command}, waiting for it to + * finish and collecting all of its output. + * + * Will throw an error if `stdin: "piped"` is set. + * + * If options `stdout` or `stderr` are not set to `"piped"`, accessing the + * corresponding field on {@linkcode Deno.CommandOutput} will throw a `TypeError`. + */ + outputSync(): CommandOutput; + /** + * Spawns a streamable subprocess, allowing to use the other methods. + */ + spawn(): ChildProcess; + } + + /** + * The interface for handling a child process returned from + * {@linkcode Deno.Command.spawn}. + * + * @category Sub Process + */ + export class ChildProcess implements AsyncDisposable { + get stdin(): WritableStream; + get stdout(): ReadableStream; + get stderr(): ReadableStream; + readonly pid: number; + /** Get the status of the child. */ + readonly status: Promise; + + /** Waits for the child to exit completely, returning all its output and + * status. */ + output(): Promise; + /** Kills the process with given {@linkcode Deno.Signal}. + * + * Defaults to `SIGTERM` if no signal is provided. + * + * @param [signo="SIGTERM"] + */ + kill(signo?: Signal): void; + + /** Ensure that the status of the child process prevents the Deno process + * from exiting. */ + ref(): void; + /** Ensure that the status of the child process does not block the Deno + * process from exiting. */ + unref(): void; + + [Symbol.asyncDispose](): Promise; + } + + /** + * Options which can be set when calling {@linkcode Deno.Command}. + * + * @category Sub Process + */ + export interface CommandOptions { + /** Arguments to pass to the process. */ + args?: string[]; + /** + * The working directory of the process. + * + * If not specified, the `cwd` of the parent process is used. + */ + cwd?: string | URL; + /** + * Clear environmental variables from parent process. + * + * Doesn't guarantee that only `env` variables are present, as the OS may + * set environmental variables for processes. + * + * @default {false} + */ + clearEnv?: boolean; + /** Environmental variables to pass to the subprocess. */ + env?: Record; + /** + * Sets the child process’s user ID. This translates to a setuid call in the + * child process. Failure in the set uid call will cause the spawn to fail. + */ + uid?: number; + /** Similar to `uid`, but sets the group ID of the child process. */ + gid?: number; + /** + * An {@linkcode AbortSignal} that allows closing the process using the + * corresponding {@linkcode AbortController} by sending the process a + * SIGTERM signal. + * + * Not supported in {@linkcode Deno.Command.outputSync}. + */ + signal?: AbortSignal; + + /** How `stdin` of the spawned process should be handled. + * + * Defaults to `"inherit"` for `output` & `outputSync`, + * and `"inherit"` for `spawn`. */ + stdin?: "piped" | "inherit" | "null"; + /** How `stdout` of the spawned process should be handled. + * + * Defaults to `"piped"` for `output` & `outputSync`, + * and `"inherit"` for `spawn`. */ + stdout?: "piped" | "inherit" | "null"; + /** How `stderr` of the spawned process should be handled. + * + * Defaults to `"piped"` for `output` & `outputSync`, + * and `"inherit"` for `spawn`. */ + stderr?: "piped" | "inherit" | "null"; + + /** Skips quoting and escaping of the arguments on windows. This option + * is ignored on non-windows platforms. + * + * @default {false} */ + windowsRawArguments?: boolean; + } + + /** + * @category Sub Process + */ + export interface CommandStatus { + /** If the child process exits with a 0 status code, `success` will be set + * to `true`, otherwise `false`. */ + success: boolean; + /** The exit code of the child process. */ + code: number; + /** The signal associated with the child process. */ + signal: Signal | null; + } + + /** + * The interface returned from calling {@linkcode Deno.Command.output} or + * {@linkcode Deno.Command.outputSync} which represents the result of spawning the + * child process. + * + * @category Sub Process + */ + export interface CommandOutput extends CommandStatus { + /** The buffered output from the child process' `stdout`. */ + readonly stdout: Uint8Array; + /** The buffered output from the child process' `stderr`. */ + readonly stderr: Uint8Array; + } + + /** Option which can be specified when performing {@linkcode Deno.inspect}. + * + * @category Console and Debugging */ + export interface InspectOptions { + /** Stylize output with ANSI colors. + * + * @default {false} */ + colors?: boolean; + /** Try to fit more than one entry of a collection on the same line. + * + * @default {true} */ + compact?: boolean; + /** Traversal depth for nested objects. + * + * @default {4} */ + depth?: number; + /** The maximum length for an inspection to take up a single line. + * + * @default {80} */ + breakLength?: number; + /** Whether or not to escape sequences. + * + * @default {true} */ + escapeSequences?: boolean; + /** The maximum number of iterable entries to print. + * + * @default {100} */ + iterableLimit?: number; + /** Show a Proxy's target and handler. + * + * @default {false} */ + showProxy?: boolean; + /** Sort Object, Set and Map entries by key. + * + * @default {false} */ + sorted?: boolean; + /** Add a trailing comma for multiline collections. + * + * @default {false} */ + trailingComma?: boolean; + /** Evaluate the result of calling getters. + * + * @default {false} */ + getters?: boolean; + /** Show an object's non-enumerable properties. + * + * @default {false} */ + showHidden?: boolean; + /** The maximum length of a string before it is truncated with an + * ellipsis. */ + strAbbreviateSize?: number; + } + + /** Converts the input into a string that has the same format as printed by + * `console.log()`. + * + * ```ts + * const obj = { + * a: 10, + * b: "hello", + * }; + * const objAsString = Deno.inspect(obj); // { a: 10, b: "hello" } + * console.log(obj); // prints same value as objAsString, e.g. { a: 10, b: "hello" } + * ``` + * + * A custom inspect functions can be registered on objects, via the symbol + * `Symbol.for("Deno.customInspect")`, to control and customize the output + * of `inspect()` or when using `console` logging: + * + * ```ts + * class A { + * x = 10; + * y = "hello"; + * [Symbol.for("Deno.customInspect")]() { + * return `x=${this.x}, y=${this.y}`; + * } + * } + * + * const inStringFormat = Deno.inspect(new A()); // "x=10, y=hello" + * console.log(inStringFormat); // prints "x=10, y=hello" + * ``` + * + * A depth can be specified by using the `depth` option: + * + * ```ts + * Deno.inspect({a: {b: {c: {d: 'hello'}}}}, {depth: 2}); // { a: { b: [Object] } } + * ``` + * + * @category Console and Debugging + */ + export function inspect(value: unknown, options?: InspectOptions): string; + + /** The name of a privileged feature which needs permission. + * + * @category Permissions + */ + export type PermissionName = + | "run" + | "read" + | "write" + | "net" + | "env" + | "sys" + | "ffi" + | "hrtime"; + + /** The current status of the permission: + * + * - `"granted"` - the permission has been granted. + * - `"denied"` - the permission has been explicitly denied. + * - `"prompt"` - the permission has not explicitly granted nor denied. + * + * @category Permissions + */ + export type PermissionState = + | "granted" + | "denied" + | "prompt"; + + /** The permission descriptor for the `allow-run` and `deny-run` permissions, which controls + * access to what sub-processes can be executed by Deno. The option `command` + * allows scoping the permission to a specific executable. + * + * **Warning, in practice, `allow-run` is effectively the same as `allow-all` + * in the sense that malicious code could execute any arbitrary code on the + * host.** + * + * @category Permissions */ + export interface RunPermissionDescriptor { + name: "run"; + /** An `allow-run` or `deny-run` permission can be scoped to a specific executable, + * which would be relative to the start-up CWD of the Deno CLI. */ + command?: string | URL; + } + + /** The permission descriptor for the `allow-read` and `deny-read` permissions, which controls + * access to reading resources from the local host. The option `path` allows + * scoping the permission to a specific path (and if the path is a directory + * any sub paths). + * + * Permission granted under `allow-read` only allows runtime code to attempt + * to read, the underlying operating system may apply additional permissions. + * + * @category Permissions */ + export interface ReadPermissionDescriptor { + name: "read"; + /** An `allow-read` or `deny-read` permission can be scoped to a specific path (and if + * the path is a directory, any sub paths). */ + path?: string | URL; + } + + /** The permission descriptor for the `allow-write` and `deny-write` permissions, which + * controls access to writing to resources from the local host. The option + * `path` allow scoping the permission to a specific path (and if the path is + * a directory any sub paths). + * + * Permission granted under `allow-write` only allows runtime code to attempt + * to write, the underlying operating system may apply additional permissions. + * + * @category Permissions */ + export interface WritePermissionDescriptor { + name: "write"; + /** An `allow-write` or `deny-write` permission can be scoped to a specific path (and if + * the path is a directory, any sub paths). */ + path?: string | URL; + } + + /** The permission descriptor for the `allow-net` and `deny-net` permissions, which controls + * access to opening network ports and connecting to remote hosts via the + * network. The option `host` allows scoping the permission for outbound + * connection to a specific host and port. + * + * @category Permissions */ + export interface NetPermissionDescriptor { + name: "net"; + /** Optional host string of the form `"[:]"`. Examples: + * + * "github.com" + * "deno.land:8080" + */ + host?: string; + } + + /** The permission descriptor for the `allow-env` and `deny-env` permissions, which controls + * access to being able to read and write to the process environment variables + * as well as access other information about the environment. The option + * `variable` allows scoping the permission to a specific environment + * variable. + * + * @category Permissions */ + export interface EnvPermissionDescriptor { + name: "env"; + /** Optional environment variable name (e.g. `PATH`). */ + variable?: string; + } + + /** The permission descriptor for the `allow-sys` and `deny-sys` permissions, which controls + * access to sensitive host system information, which malicious code might + * attempt to exploit. The option `kind` allows scoping the permission to a + * specific piece of information. + * + * @category Permissions */ + export interface SysPermissionDescriptor { + name: "sys"; + /** The specific information to scope the permission to. */ + kind?: + | "loadavg" + | "hostname" + | "systemMemoryInfo" + | "networkInterfaces" + | "osRelease" + | "osUptime" + | "uid" + | "gid" + | "cpus"; + } + + /** The permission descriptor for the `allow-ffi` and `deny-ffi` permissions, which controls + * access to loading _foreign_ code and interfacing with it via the + * [Foreign Function Interface API](https://deno.land/manual/runtime/ffi_api) + * available in Deno. The option `path` allows scoping the permission to a + * specific path on the host. + * + * @category Permissions */ + export interface FfiPermissionDescriptor { + name: "ffi"; + /** Optional path on the local host to scope the permission to. */ + path?: string | URL; + } + + /** The permission descriptor for the `allow-hrtime` and `deny-hrtime` permissions, which + * controls if the runtime code has access to high resolution time. High + * resolution time is considered sensitive information, because it can be used + * by malicious code to gain information about the host that it might not + * otherwise have access to. + * + * @category Permissions */ + export interface HrtimePermissionDescriptor { + name: "hrtime"; + } + + /** Permission descriptors which define a permission and can be queried, + * requested, or revoked. + * + * View the specifics of the individual descriptors for more information about + * each permission kind. + * + * @category Permissions + */ + export type PermissionDescriptor = + | RunPermissionDescriptor + | ReadPermissionDescriptor + | WritePermissionDescriptor + | NetPermissionDescriptor + | EnvPermissionDescriptor + | SysPermissionDescriptor + | FfiPermissionDescriptor + | HrtimePermissionDescriptor; + + /** The interface which defines what event types are supported by + * {@linkcode PermissionStatus} instances. + * + * @category Permissions */ + export interface PermissionStatusEventMap { + "change": Event; + } + + /** An {@linkcode EventTarget} returned from the {@linkcode Deno.permissions} + * API which can provide updates to any state changes of the permission. + * + * @category Permissions */ + export class PermissionStatus extends EventTarget { + // deno-lint-ignore no-explicit-any + onchange: ((this: PermissionStatus, ev: Event) => any) | null; + readonly state: PermissionState; + /** + * Describes if permission is only granted partially, eg. an access + * might be granted to "/foo" directory, but denied for "/foo/bar". + * In such case this field will be set to `true` when querying for + * read permissions of "/foo" directory. + */ + readonly partial: boolean; + addEventListener( + type: K, + listener: ( + this: PermissionStatus, + ev: PermissionStatusEventMap[K], + ) => any, + options?: boolean | AddEventListenerOptions, + ): void; + addEventListener( + type: string, + listener: EventListenerOrEventListenerObject, + options?: boolean | AddEventListenerOptions, + ): void; + removeEventListener( + type: K, + listener: ( + this: PermissionStatus, + ev: PermissionStatusEventMap[K], + ) => any, + options?: boolean | EventListenerOptions, + ): void; + removeEventListener( + type: string, + listener: EventListenerOrEventListenerObject, + options?: boolean | EventListenerOptions, + ): void; + } + + /** + * Deno's permission management API. + * + * The class which provides the interface for the {@linkcode Deno.permissions} + * global instance and is based on the web platform + * [Permissions API](https://developer.mozilla.org/en-US/docs/Web/API/Permissions_API), + * though some proposed parts of the API which are useful in a server side + * runtime context were removed or abandoned in the web platform specification + * which is why it was chosen to locate it in the {@linkcode Deno} namespace + * instead. + * + * By default, if the `stdin`/`stdout` is TTY for the Deno CLI (meaning it can + * send and receive text), then the CLI will prompt the user to grant + * permission when an un-granted permission is requested. This behavior can + * be changed by using the `--no-prompt` command at startup. When prompting + * the CLI will request the narrowest permission possible, potentially making + * it annoying to the user. The permissions APIs allow the code author to + * request a wider set of permissions at one time in order to provide a better + * user experience. + * + * @category Permissions */ + export class Permissions { + /** Resolves to the current status of a permission. + * + * Note, if the permission is already granted, `request()` will not prompt + * the user again, therefore `query()` is only necessary if you are going + * to react differently existing permissions without wanting to modify them + * or prompt the user to modify them. + * + * ```ts + * const status = await Deno.permissions.query({ name: "read", path: "/etc" }); + * console.log(status.state); + * ``` + */ + query(desc: PermissionDescriptor): Promise; + + /** Returns the current status of a permission. + * + * Note, if the permission is already granted, `request()` will not prompt + * the user again, therefore `querySync()` is only necessary if you are going + * to react differently existing permissions without wanting to modify them + * or prompt the user to modify them. + * + * ```ts + * const status = Deno.permissions.querySync({ name: "read", path: "/etc" }); + * console.log(status.state); + * ``` + */ + querySync(desc: PermissionDescriptor): PermissionStatus; + + /** Revokes a permission, and resolves to the state of the permission. + * + * ```ts + * import { assert } from "jsr:@std/assert"; + * + * const status = await Deno.permissions.revoke({ name: "run" }); + * assert(status.state !== "granted") + * ``` + */ + revoke(desc: PermissionDescriptor): Promise; + + /** Revokes a permission, and returns the state of the permission. + * + * ```ts + * import { assert } from "jsr:@std/assert"; + * + * const status = Deno.permissions.revokeSync({ name: "run" }); + * assert(status.state !== "granted") + * ``` + */ + revokeSync(desc: PermissionDescriptor): PermissionStatus; + + /** Requests the permission, and resolves to the state of the permission. + * + * If the permission is already granted, the user will not be prompted to + * grant the permission again. + * + * ```ts + * const status = await Deno.permissions.request({ name: "env" }); + * if (status.state === "granted") { + * console.log("'env' permission is granted."); + * } else { + * console.log("'env' permission is denied."); + * } + * ``` + */ + request(desc: PermissionDescriptor): Promise; + + /** Requests the permission, and returns the state of the permission. + * + * If the permission is already granted, the user will not be prompted to + * grant the permission again. + * + * ```ts + * const status = Deno.permissions.requestSync({ name: "env" }); + * if (status.state === "granted") { + * console.log("'env' permission is granted."); + * } else { + * console.log("'env' permission is denied."); + * } + * ``` + */ + requestSync(desc: PermissionDescriptor): PermissionStatus; + } + + /** Deno's permission management API. + * + * It is a singleton instance of the {@linkcode Permissions} object and is + * based on the web platform + * [Permissions API](https://developer.mozilla.org/en-US/docs/Web/API/Permissions_API), + * though some proposed parts of the API which are useful in a server side + * runtime context were removed or abandoned in the web platform specification + * which is why it was chosen to locate it in the {@linkcode Deno} namespace + * instead. + * + * By default, if the `stdin`/`stdout` is TTY for the Deno CLI (meaning it can + * send and receive text), then the CLI will prompt the user to grant + * permission when an un-granted permission is requested. This behavior can + * be changed by using the `--no-prompt` command at startup. When prompting + * the CLI will request the narrowest permission possible, potentially making + * it annoying to the user. The permissions APIs allow the code author to + * request a wider set of permissions at one time in order to provide a better + * user experience. + * + * Requesting already granted permissions will not prompt the user and will + * return that the permission was granted. + * + * ### Querying + * + * ```ts + * const status = await Deno.permissions.query({ name: "read", path: "/etc" }); + * console.log(status.state); + * ``` + * + * ```ts + * const status = Deno.permissions.querySync({ name: "read", path: "/etc" }); + * console.log(status.state); + * ``` + * + * ### Revoking + * + * ```ts + * import { assert } from "jsr:@std/assert"; + * + * const status = await Deno.permissions.revoke({ name: "run" }); + * assert(status.state !== "granted") + * ``` + * + * ```ts + * import { assert } from "jsr:@std/assert"; + * + * const status = Deno.permissions.revokeSync({ name: "run" }); + * assert(status.state !== "granted") + * ``` + * + * ### Requesting + * + * ```ts + * const status = await Deno.permissions.request({ name: "env" }); + * if (status.state === "granted") { + * console.log("'env' permission is granted."); + * } else { + * console.log("'env' permission is denied."); + * } + * ``` + * + * ```ts + * const status = Deno.permissions.requestSync({ name: "env" }); + * if (status.state === "granted") { + * console.log("'env' permission is granted."); + * } else { + * console.log("'env' permission is denied."); + * } + * ``` + * + * @category Permissions + */ + export const permissions: Permissions; + + /** Information related to the build of the current Deno runtime. + * + * Users are discouraged from code branching based on this information, as + * assumptions about what is available in what build environment might change + * over time. Developers should specifically sniff out the features they + * intend to use. + * + * The intended use for the information is for logging and debugging purposes. + * + * @category Runtime Environment + */ + export const build: { + /** The [LLVM](https://llvm.org/) target triple, which is the combination + * of `${arch}-${vendor}-${os}` and represent the specific build target that + * the current runtime was built for. */ + target: string; + /** Instruction set architecture that the Deno CLI was built for. */ + arch: "x86_64" | "aarch64"; + /** The operating system that the Deno CLI was built for. `"darwin"` is + * also known as OSX or MacOS. */ + os: + | "darwin" + | "linux" + | "android" + | "windows" + | "freebsd" + | "netbsd" + | "aix" + | "solaris" + | "illumos"; + /** The computer vendor that the Deno CLI was built for. */ + vendor: string; + /** Optional environment flags that were set for this build of Deno CLI. */ + env?: string; + }; + + /** Version information related to the current Deno CLI runtime environment. + * + * Users are discouraged from code branching based on this information, as + * assumptions about what is available in what build environment might change + * over time. Developers should specifically sniff out the features they + * intend to use. + * + * The intended use for the information is for logging and debugging purposes. + * + * @category Runtime Environment + */ + export const version: { + /** Deno CLI's version. For example: `"1.26.0"`. */ + deno: string; + /** The V8 version used by Deno. For example: `"10.7.100.0"`. + * + * V8 is the underlying JavaScript runtime platform that Deno is built on + * top of. */ + v8: string; + /** The TypeScript version used by Deno. For example: `"4.8.3"`. + * + * A version of the TypeScript type checker and language server is built-in + * to the Deno CLI. */ + typescript: string; + }; + + /** Returns the script arguments to the program. + * + * Give the following command line invocation of Deno: + * + * ```sh + * deno run --allow-read https://examples.deno.land/command-line-arguments.ts Sushi + * ``` + * + * Then `Deno.args` will contain: + * + * ```ts + * [ "Sushi" ] + * ``` + * + * If you are looking for a structured way to parse arguments, there is + * [`parseArgs()`](https://jsr.io/@std/cli/doc/parse-args/~/parseArgs) from + * the Deno Standard Library. + * + * @category Runtime Environment + */ + export const args: string[]; + + /** + * A symbol which can be used as a key for a custom method which will be + * called when `Deno.inspect()` is called, or when the object is logged to + * the console. + * + * @deprecated This will be removed in Deno 2.0. See the + * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide} + * for migration instructions. + * + * @category Console and Debugging + */ + export const customInspect: unique symbol; + + /** The URL of the entrypoint module entered from the command-line. It + * requires read permission to the CWD. + * + * Also see {@linkcode ImportMeta} for other related information. + * + * @tags allow-read + * @category Runtime Environment + */ + export const mainModule: string; + + /** Options that can be used with {@linkcode symlink} and + * {@linkcode symlinkSync}. + * + * @category File System */ + export interface SymlinkOptions { + /** If the symbolic link should be either a file or directory. This option + * only applies to Windows and is ignored on other operating systems. */ + type: "file" | "dir"; + } + + /** + * Creates `newpath` as a symbolic link to `oldpath`. + * + * The `options.type` parameter can be set to `"file"` or `"dir"`. This + * argument is only available on Windows and ignored on other platforms. + * + * ```ts + * await Deno.symlink("old/name", "new/name"); + * ``` + * + * Requires full `allow-read` and `allow-write` permissions. + * + * @tags allow-read, allow-write + * @category File System + */ + export function symlink( + oldpath: string | URL, + newpath: string | URL, + options?: SymlinkOptions, + ): Promise; + + /** + * Creates `newpath` as a symbolic link to `oldpath`. + * + * The `options.type` parameter can be set to `"file"` or `"dir"`. This + * argument is only available on Windows and ignored on other platforms. + * + * ```ts + * Deno.symlinkSync("old/name", "new/name"); + * ``` + * + * Requires full `allow-read` and `allow-write` permissions. + * + * @tags allow-read, allow-write + * @category File System + */ + export function symlinkSync( + oldpath: string | URL, + newpath: string | URL, + options?: SymlinkOptions, + ): void; + + /** + * Truncates or extends the specified file stream, to reach the specified + * `len`. + * + * If `len` is not specified then the entire file contents are truncated as if + * `len` was set to `0`. + * + * If the file previously was larger than this new length, the extra data is + * lost. + * + * If the file previously was shorter, it is extended, and the extended part + * reads as null bytes ('\0'). + * + * ### Truncate the entire file + * + * ```ts + * const file = await Deno.open( + * "my_file.txt", + * { read: true, write: true, create: true } + * ); + * await Deno.ftruncate(file.rid); + * ``` + * + * ### Truncate part of the file + * + * ```ts + * const file = await Deno.open( + * "my_file.txt", + * { read: true, write: true, create: true } + * ); + * await file.write(new TextEncoder().encode("Hello World")); + * await Deno.ftruncate(file.rid, 7); + * const data = new Uint8Array(32); + * await Deno.read(file.rid, data); + * console.log(new TextDecoder().decode(data)); // Hello W + * ``` + * + * @deprecated This will be removed in Deno 2.0. See the + * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide} + * for migration instructions. + * + * @category File System + */ + export function ftruncate(rid: number, len?: number): Promise; + + /** + * Synchronously truncates or extends the specified file stream, to reach the + * specified `len`. + * + * If `len` is not specified then the entire file contents are truncated as if + * `len` was set to `0`. + * + * If the file previously was larger than this new length, the extra data is + * lost. + * + * If the file previously was shorter, it is extended, and the extended part + * reads as null bytes ('\0'). + * + * ### Truncate the entire file + * + * ```ts + * const file = Deno.openSync( + * "my_file.txt", + * { read: true, write: true, truncate: true, create: true } + * ); + * Deno.ftruncateSync(file.rid); + * ``` + * + * ### Truncate part of the file + * + * ```ts + * const file = Deno.openSync( + * "my_file.txt", + * { read: true, write: true, create: true } + * ); + * file.writeSync(new TextEncoder().encode("Hello World")); + * Deno.ftruncateSync(file.rid, 7); + * Deno.seekSync(file.rid, 0, Deno.SeekMode.Start); + * const data = new Uint8Array(32); + * Deno.readSync(file.rid, data); + * console.log(new TextDecoder().decode(data)); // Hello W + * ``` + * + * @deprecated This will be removed in Deno 2.0. See the + * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide} + * for migration instructions. + * + * @category File System + */ + export function ftruncateSync(rid: number, len?: number): void; + + /** + * Synchronously changes the access (`atime`) and modification (`mtime`) times + * of a file stream resource referenced by `rid`. Given times are either in + * seconds (UNIX epoch time) or as `Date` objects. + * + * ```ts + * const file = Deno.openSync("file.txt", { create: true, write: true }); + * Deno.futimeSync(file.rid, 1556495550, new Date()); + * ``` + * + * @deprecated This will be removed in Deno 2.0. See the + * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide} + * for migration instructions. + * + * @category File System + */ + export function futimeSync( + rid: number, + atime: number | Date, + mtime: number | Date, + ): void; + + /** + * Changes the access (`atime`) and modification (`mtime`) times of a file + * stream resource referenced by `rid`. Given times are either in seconds + * (UNIX epoch time) or as `Date` objects. + * + * ```ts + * const file = await Deno.open("file.txt", { create: true, write: true }); + * await Deno.futime(file.rid, 1556495550, new Date()); + * ``` + * + * @deprecated This will be removed in Deno 2.0. See the + * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide} + * for migration instructions. + * + * @category File System + */ + export function futime( + rid: number, + atime: number | Date, + mtime: number | Date, + ): Promise; + + /** + * Returns a `Deno.FileInfo` for the given file stream. + * + * ```ts + * import { assert } from "jsr:@std/assert"; + * + * const file = await Deno.open("file.txt", { read: true }); + * const fileInfo = await Deno.fstat(file.rid); + * assert(fileInfo.isFile); + * ``` + * + * @deprecated This will be removed in Deno 2.0. See the + * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide} + * for migration instructions. + * + * @category File System + */ + export function fstat(rid: number): Promise; + + /** + * Synchronously returns a {@linkcode Deno.FileInfo} for the given file + * stream. + * + * ```ts + * import { assert } from "jsr:@std/assert"; + * + * const file = Deno.openSync("file.txt", { read: true }); + * const fileInfo = Deno.fstatSync(file.rid); + * assert(fileInfo.isFile); + * ``` + * + * @deprecated This will be removed in Deno 2.0. See the + * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide} + * for migration instructions. + * + * @category File System + */ + export function fstatSync(rid: number): FileInfo; + + /** + * Synchronously changes the access (`atime`) and modification (`mtime`) times + * of a file system object referenced by `path`. Given times are either in + * seconds (UNIX epoch time) or as `Date` objects. + * + * ```ts + * Deno.utimeSync("myfile.txt", 1556495550, new Date()); + * ``` + * + * Requires `allow-write` permission. + * + * @tags allow-write + * @category File System + */ + export function utimeSync( + path: string | URL, + atime: number | Date, + mtime: number | Date, + ): void; + + /** + * Changes the access (`atime`) and modification (`mtime`) times of a file + * system object referenced by `path`. Given times are either in seconds + * (UNIX epoch time) or as `Date` objects. + * + * ```ts + * await Deno.utime("myfile.txt", 1556495550, new Date()); + * ``` + * + * Requires `allow-write` permission. + * + * @tags allow-write + * @category File System + */ + export function utime( + path: string | URL, + atime: number | Date, + mtime: number | Date, + ): Promise; + + /** The event yielded from an {@linkcode HttpConn} which represents an HTTP + * request from a remote client. + * + * @category HTTP Server + * + * @deprecated This will be removed in Deno 2.0. See the + * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide} + * for migration instructions. + */ + export interface RequestEvent { + /** The request from the client in the form of the web platform + * {@linkcode Request}. */ + readonly request: Request; + /** The method to be used to respond to the event. The response needs to + * either be an instance of {@linkcode Response} or a promise that resolves + * with an instance of `Response`. + * + * When the response is successfully processed then the promise returned + * will be resolved. If there are any issues with sending the response, + * the promise will be rejected. */ + respondWith(r: Response | PromiseLike): Promise; + } + + /** + * The async iterable that is returned from {@linkcode serveHttp} which + * yields up {@linkcode RequestEvent} events, representing individual + * requests on the HTTP server connection. + * + * @category HTTP Server + * + * @deprecated This will be removed in Deno 2.0. See the + * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide} + * for migration instructions. + */ + export interface HttpConn extends AsyncIterable, Disposable { + /** The resource ID associated with this connection. Generally users do not + * need to be aware of this identifier. */ + readonly rid: number; + + /** An alternative to the async iterable interface which provides promises + * which resolve with either a {@linkcode RequestEvent} when there is + * another request or `null` when the client has closed the connection. */ + nextRequest(): Promise; + /** Initiate a server side closure of the connection, indicating to the + * client that you refuse to accept any more requests on this connection. + * + * Typically the client closes the connection, which will result in the + * async iterable terminating or the `nextRequest()` method returning + * `null`. */ + close(): void; + } + + /** + * Provides an interface to handle HTTP request and responses over TCP or TLS + * connections. The method returns an {@linkcode HttpConn} which yields up + * {@linkcode RequestEvent} events, which utilize the web platform standard + * {@linkcode Request} and {@linkcode Response} objects to handle the request. + * + * ```ts + * const conn = Deno.listen({ port: 80 }); + * const httpConn = Deno.serveHttp(await conn.accept()); + * const e = await httpConn.nextRequest(); + * if (e) { + * e.respondWith(new Response("Hello World")); + * } + * ``` + * + * Alternatively, you can also use the async iterator approach: + * + * ```ts + * async function handleHttp(conn: Deno.Conn) { + * for await (const e of Deno.serveHttp(conn)) { + * e.respondWith(new Response("Hello World")); + * } + * } + * + * for await (const conn of Deno.listen({ port: 80 })) { + * handleHttp(conn); + * } + * ``` + * + * If `httpConn.nextRequest()` encounters an error or returns `null` then the + * underlying {@linkcode HttpConn} resource is closed automatically. + * + * Also see the experimental Flash HTTP server {@linkcode Deno.serve} which + * provides a ground up rewrite of handling of HTTP requests and responses + * within the Deno CLI. + * + * Note that this function *consumes* the given connection passed to it, thus + * the original connection will be unusable after calling this. Additionally, + * you need to ensure that the connection is not being used elsewhere when + * calling this function in order for the connection to be consumed properly. + * + * For instance, if there is a `Promise` that is waiting for read operation on + * the connection to complete, it is considered that the connection is being + * used elsewhere. In such a case, this function will fail. + * + * @category HTTP Server + * @deprecated This will be soft-removed in Deno 2.0. See the + * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide} + * for migration instructions. + */ + export function serveHttp(conn: Conn): HttpConn; + + /** The object that is returned from a {@linkcode Deno.upgradeWebSocket} + * request. + * + * @category Web Sockets */ + export interface WebSocketUpgrade { + /** The response object that represents the HTTP response to the client, + * which should be used to the {@linkcode RequestEvent} `.respondWith()` for + * the upgrade to be successful. */ + response: Response; + /** The {@linkcode WebSocket} interface to communicate to the client via a + * web socket. */ + socket: WebSocket; + } + + /** Options which can be set when performing a + * {@linkcode Deno.upgradeWebSocket} upgrade of a {@linkcode Request} + * + * @category Web Sockets */ + export interface UpgradeWebSocketOptions { + /** Sets the `.protocol` property on the client side web socket to the + * value provided here, which should be one of the strings specified in the + * `protocols` parameter when requesting the web socket. This is intended + * for clients and servers to specify sub-protocols to use to communicate to + * each other. */ + protocol?: string; + /** If the client does not respond to this frame with a + * `pong` within the timeout specified, the connection is deemed + * unhealthy and is closed. The `close` and `error` event will be emitted. + * + * The unit is seconds, with a default of 120. + * Set to `0` to disable timeouts. */ + idleTimeout?: number; + } + + /** + * Upgrade an incoming HTTP request to a WebSocket. + * + * Given a {@linkcode Request}, returns a pair of {@linkcode WebSocket} and + * {@linkcode Response} instances. The original request must be responded to + * with the returned response for the websocket upgrade to be successful. + * + * ```ts + * const conn = Deno.listen({ port: 80 }); + * const httpConn = Deno.serveHttp(await conn.accept()); + * const e = await httpConn.nextRequest(); + * if (e) { + * const { socket, response } = Deno.upgradeWebSocket(e.request); + * socket.onopen = () => { + * socket.send("Hello World!"); + * }; + * socket.onmessage = (e) => { + * console.log(e.data); + * socket.close(); + * }; + * socket.onclose = () => console.log("WebSocket has been closed."); + * socket.onerror = (e) => console.error("WebSocket error:", e); + * e.respondWith(response); + * } + * ``` + * + * If the request body is disturbed (read from) before the upgrade is + * completed, upgrading fails. + * + * This operation does not yet consume the request or open the websocket. This + * only happens once the returned response has been passed to `respondWith()`. + * + * @category Web Sockets + */ + export function upgradeWebSocket( + request: Request, + options?: UpgradeWebSocketOptions, + ): WebSocketUpgrade; + + /** Send a signal to process under given `pid`. The value and meaning of the + * `signal` to the process is operating system and process dependant. + * {@linkcode Signal} provides the most common signals. Default signal + * is `"SIGTERM"`. + * + * The term `kill` is adopted from the UNIX-like command line command `kill` + * which also signals processes. + * + * If `pid` is negative, the signal will be sent to the process group + * identified by `pid`. An error will be thrown if a negative `pid` is used on + * Windows. + * + * ```ts + * const p = Deno.run({ + * cmd: ["sleep", "10000"] + * }); + * + * Deno.kill(p.pid, "SIGINT"); + * ``` + * + * Requires `allow-run` permission. + * + * @tags allow-run + * @category Sub Process + */ + export function kill(pid: number, signo?: Signal): void; + + /** The type of the resource record to resolve via DNS using + * {@linkcode Deno.resolveDns}. + * + * Only the listed types are supported currently. + * + * @category Network + */ + export type RecordType = + | "A" + | "AAAA" + | "ANAME" + | "CAA" + | "CNAME" + | "MX" + | "NAPTR" + | "NS" + | "PTR" + | "SOA" + | "SRV" + | "TXT"; + + /** + * Options which can be set when using {@linkcode Deno.resolveDns}. + * + * @category Network */ + export interface ResolveDnsOptions { + /** The name server to be used for lookups. + * + * If not specified, defaults to the system configuration. For example + * `/etc/resolv.conf` on Unix-like systems. */ + nameServer?: { + /** The IP address of the name server. */ + ipAddr: string; + /** The port number the query will be sent to. + * + * @default {53} */ + port?: number; + }; + /** + * An abort signal to allow cancellation of the DNS resolution operation. + * If the signal becomes aborted the resolveDns operation will be stopped + * and the promise returned will be rejected with an AbortError. + */ + signal?: AbortSignal; + } + + /** If {@linkcode Deno.resolveDns} is called with `"CAA"` record type + * specified, it will resolve with an array of objects with this interface. + * + * @category Network + */ + export interface CAARecord { + /** If `true`, indicates that the corresponding property tag **must** be + * understood if the semantics of the CAA record are to be correctly + * interpreted by an issuer. + * + * Issuers **must not** issue certificates for a domain if the relevant CAA + * Resource Record set contains unknown property tags that have `critical` + * set. */ + critical: boolean; + /** An string that represents the identifier of the property represented by + * the record. */ + tag: string; + /** The value associated with the tag. */ + value: string; + } + + /** If {@linkcode Deno.resolveDns} is called with `"MX"` record type + * specified, it will return an array of objects with this interface. + * + * @category Network */ + export interface MXRecord { + /** A priority value, which is a relative value compared to the other + * preferences of MX records for the domain. */ + preference: number; + /** The server that mail should be delivered to. */ + exchange: string; + } + + /** If {@linkcode Deno.resolveDns} is called with `"NAPTR"` record type + * specified, it will return an array of objects with this interface. + * + * @category Network */ + export interface NAPTRRecord { + order: number; + preference: number; + flags: string; + services: string; + regexp: string; + replacement: string; + } + + /** If {@linkcode Deno.resolveDns} is called with `"SOA"` record type + * specified, it will return an array of objects with this interface. + * + * @category Network */ + export interface SOARecord { + mname: string; + rname: string; + serial: number; + refresh: number; + retry: number; + expire: number; + minimum: number; + } + + /** If {@linkcode Deno.resolveDns} is called with `"SRV"` record type + * specified, it will return an array of objects with this interface. + * + * @category Network + */ + export interface SRVRecord { + priority: number; + weight: number; + port: number; + target: string; + } + + /** + * Performs DNS resolution against the given query, returning resolved + * records. + * + * Fails in the cases such as: + * + * - the query is in invalid format. + * - the options have an invalid parameter. For example `nameServer.port` is + * beyond the range of 16-bit unsigned integer. + * - the request timed out. + * + * ```ts + * const a = await Deno.resolveDns("example.com", "A"); + * + * const aaaa = await Deno.resolveDns("example.com", "AAAA", { + * nameServer: { ipAddr: "8.8.8.8", port: 53 }, + * }); + * ``` + * + * Requires `allow-net` permission. + * + * @tags allow-net + * @category Network + */ + export function resolveDns( + query: string, + recordType: "A" | "AAAA" | "ANAME" | "CNAME" | "NS" | "PTR", + options?: ResolveDnsOptions, + ): Promise; + + /** + * Performs DNS resolution against the given query, returning resolved + * records. + * + * Fails in the cases such as: + * + * - the query is in invalid format. + * - the options have an invalid parameter. For example `nameServer.port` is + * beyond the range of 16-bit unsigned integer. + * - the request timed out. + * + * ```ts + * const a = await Deno.resolveDns("example.com", "A"); + * + * const aaaa = await Deno.resolveDns("example.com", "AAAA", { + * nameServer: { ipAddr: "8.8.8.8", port: 53 }, + * }); + * ``` + * + * Requires `allow-net` permission. + * + * @tags allow-net + * @category Network + */ + export function resolveDns( + query: string, + recordType: "CAA", + options?: ResolveDnsOptions, + ): Promise; + + /** + * Performs DNS resolution against the given query, returning resolved + * records. + * + * Fails in the cases such as: + * + * - the query is in invalid format. + * - the options have an invalid parameter. For example `nameServer.port` is + * beyond the range of 16-bit unsigned integer. + * - the request timed out. + * + * ```ts + * const a = await Deno.resolveDns("example.com", "A"); + * + * const aaaa = await Deno.resolveDns("example.com", "AAAA", { + * nameServer: { ipAddr: "8.8.8.8", port: 53 }, + * }); + * ``` + * + * Requires `allow-net` permission. + * + * @tags allow-net + * @category Network + */ + export function resolveDns( + query: string, + recordType: "MX", + options?: ResolveDnsOptions, + ): Promise; + + /** + * Performs DNS resolution against the given query, returning resolved + * records. + * + * Fails in the cases such as: + * + * - the query is in invalid format. + * - the options have an invalid parameter. For example `nameServer.port` is + * beyond the range of 16-bit unsigned integer. + * - the request timed out. + * + * ```ts + * const a = await Deno.resolveDns("example.com", "A"); + * + * const aaaa = await Deno.resolveDns("example.com", "AAAA", { + * nameServer: { ipAddr: "8.8.8.8", port: 53 }, + * }); + * ``` + * + * Requires `allow-net` permission. + * + * @tags allow-net + * @category Network + */ + export function resolveDns( + query: string, + recordType: "NAPTR", + options?: ResolveDnsOptions, + ): Promise; + + /** + * Performs DNS resolution against the given query, returning resolved + * records. + * + * Fails in the cases such as: + * + * - the query is in invalid format. + * - the options have an invalid parameter. For example `nameServer.port` is + * beyond the range of 16-bit unsigned integer. + * - the request timed out. + * + * ```ts + * const a = await Deno.resolveDns("example.com", "A"); + * + * const aaaa = await Deno.resolveDns("example.com", "AAAA", { + * nameServer: { ipAddr: "8.8.8.8", port: 53 }, + * }); + * ``` + * + * Requires `allow-net` permission. + * + * @tags allow-net + * @category Network + */ + export function resolveDns( + query: string, + recordType: "SOA", + options?: ResolveDnsOptions, + ): Promise; + + /** + * Performs DNS resolution against the given query, returning resolved + * records. + * + * Fails in the cases such as: + * + * - the query is in invalid format. + * - the options have an invalid parameter. For example `nameServer.port` is + * beyond the range of 16-bit unsigned integer. + * - the request timed out. + * + * ```ts + * const a = await Deno.resolveDns("example.com", "A"); + * + * const aaaa = await Deno.resolveDns("example.com", "AAAA", { + * nameServer: { ipAddr: "8.8.8.8", port: 53 }, + * }); + * ``` + * + * Requires `allow-net` permission. + * + * @tags allow-net + * @category Network + */ + export function resolveDns( + query: string, + recordType: "SRV", + options?: ResolveDnsOptions, + ): Promise; + + /** + * Performs DNS resolution against the given query, returning resolved + * records. + * + * Fails in the cases such as: + * + * - the query is in invalid format. + * - the options have an invalid parameter. For example `nameServer.port` is + * beyond the range of 16-bit unsigned integer. + * - the request timed out. + * + * ```ts + * const a = await Deno.resolveDns("example.com", "A"); + * + * const aaaa = await Deno.resolveDns("example.com", "AAAA", { + * nameServer: { ipAddr: "8.8.8.8", port: 53 }, + * }); + * ``` + * + * Requires `allow-net` permission. + * + * @tags allow-net + * @category Network + */ + export function resolveDns( + query: string, + recordType: "TXT", + options?: ResolveDnsOptions, + ): Promise; + + /** + * Performs DNS resolution against the given query, returning resolved + * records. + * + * Fails in the cases such as: + * + * - the query is in invalid format. + * - the options have an invalid parameter. For example `nameServer.port` is + * beyond the range of 16-bit unsigned integer. + * - the request timed out. + * + * ```ts + * const a = await Deno.resolveDns("example.com", "A"); + * + * const aaaa = await Deno.resolveDns("example.com", "AAAA", { + * nameServer: { ipAddr: "8.8.8.8", port: 53 }, + * }); + * ``` + * + * Requires `allow-net` permission. + * + * @tags allow-net + * @category Network + */ + export function resolveDns( + query: string, + recordType: RecordType, + options?: ResolveDnsOptions, + ): Promise< + | string[] + | CAARecord[] + | MXRecord[] + | NAPTRRecord[] + | SOARecord[] + | SRVRecord[] + | string[][] + >; + + /** + * Make the timer of the given `id` block the event loop from finishing. + * + * @category Timers + */ + export function refTimer(id: number): void; + + /** + * Make the timer of the given `id` not block the event loop from finishing. + * + * @category Timers + */ + export function unrefTimer(id: number): void; + + /** + * Returns the user id of the process on POSIX platforms. Returns null on Windows. + * + * ```ts + * console.log(Deno.uid()); + * ``` + * + * Requires `allow-sys` permission. + * + * @tags allow-sys + * @category Runtime Environment + */ + export function uid(): number | null; + + /** + * Returns the group id of the process on POSIX platforms. Returns null on windows. + * + * ```ts + * console.log(Deno.gid()); + * ``` + * + * Requires `allow-sys` permission. + * + * @tags allow-sys + * @category Runtime Environment + */ + export function gid(): number | null; + + /** Information for a HTTP request. + * + * @category HTTP Server + */ + export interface ServeHandlerInfo { + /** The remote address of the connection. */ + remoteAddr: Deno.NetAddr; + } + + /** A handler for HTTP requests. Consumes a request and returns a response. + * + * If a handler throws, the server calling the handler will assume the impact + * of the error is isolated to the individual request. It will catch the error + * and if necessary will close the underlying connection. + * + * @category HTTP Server + */ + export type ServeHandler = ( + request: Request, + info: ServeHandlerInfo, + ) => Response | Promise; + + /** Options which can be set when calling {@linkcode Deno.serve}. + * + * @category HTTP Server + */ + export interface ServeOptions { + /** The port to listen on. + * + * @default {8000} */ + port?: number; + + /** A literal IP address or host name that can be resolved to an IP address. + * + * __Note about `0.0.0.0`__ While listening `0.0.0.0` works on all platforms, + * the browsers on Windows don't work with the address `0.0.0.0`. + * You should show the message like `server running on localhost:8080` instead of + * `server running on 0.0.0.0:8080` if your program supports Windows. + * + * @default {"0.0.0.0"} */ + hostname?: string; + + /** An {@linkcode AbortSignal} to close the server and all connections. */ + signal?: AbortSignal; + + /** Sets `SO_REUSEPORT` on POSIX systems. */ + reusePort?: boolean; + + /** The handler to invoke when route handlers throw an error. */ + onError?: (error: unknown) => Response | Promise; + + /** The callback which is called when the server starts listening. */ + onListen?: (params: { hostname: string; port: number }) => void; + } + + /** Additional options which are used when opening a TLS (HTTPS) server. + * + * @category HTTP Server + */ + export interface ServeTlsOptions extends ServeOptions { + /** Server private key in PEM format */ + cert: string; + + /** Cert chain in PEM format */ + key: string; + } + + /** + * @category HTTP Server + */ + export interface ServeInit { + /** The handler to invoke to process each incoming request. */ + handler: ServeHandler; + } + + /** @category HTTP Server */ + export interface ServeUnixOptions { + /** The unix domain socket path to listen on. */ + path: string; + + /** An {@linkcode AbortSignal} to close the server and all connections. */ + signal?: AbortSignal; + + /** The handler to invoke when route handlers throw an error. */ + onError?: (error: unknown) => Response | Promise; + + /** The callback which is called when the server starts listening. */ + onListen?: (params: { path: string }) => void; + } + + /** Information for a unix domain socket HTTP request. + * + * @category HTTP Server + */ + export interface ServeUnixHandlerInfo { + /** The remote address of the connection. */ + remoteAddr: Deno.UnixAddr; + } + + /** A handler for unix domain socket HTTP requests. Consumes a request and returns a response. + * + * If a handler throws, the server calling the handler will assume the impact + * of the error is isolated to the individual request. It will catch the error + * and if necessary will close the underlying connection. + * + * @category HTTP Server + */ + export type ServeUnixHandler = ( + request: Request, + info: ServeUnixHandlerInfo, + ) => Response | Promise; + + /** + * @category HTTP Server + */ + export interface ServeUnixInit { + /** The handler to invoke to process each incoming request. */ + handler: ServeUnixHandler; + } + + /** An instance of the server created using `Deno.serve()` API. + * + * @category HTTP Server + */ + export interface HttpServer extends AsyncDisposable { + /** A promise that resolves once server finishes - eg. when aborted using + * the signal passed to {@linkcode ServeOptions.signal}. + */ + finished: Promise; + + /** + * Make the server block the event loop from finishing. + * + * Note: the server blocks the event loop from finishing by default. + * This method is only meaningful after `.unref()` is called. + */ + ref(): void; + + /** Make the server not block the event loop from finishing. */ + unref(): void; + + /** Gracefully close the server. No more new connections will be accepted, + * while pending requests will be allowed to finish. + */ + shutdown(): Promise; + } + + /** + * @category HTTP Server + * + * @deprecated This will be removed in Deno 2.0. See the + * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide} + * for migration instructions. + */ + export type Server = HttpServer; + + /** Serves HTTP requests with the given handler. + * + * The below example serves with the port `8000` on hostname `"127.0.0.1"`. + * + * ```ts + * Deno.serve((_req) => new Response("Hello, world")); + * ``` + * + * @category HTTP Server + */ + export function serve(handler: ServeHandler): HttpServer; + /** Serves HTTP requests with the given option bag and handler. + * + * You can specify the socket path with `path` option. + * + * ```ts + * Deno.serve( + * { path: "path/to/socket" }, + * (_req) => new Response("Hello, world") + * ); + * ``` + * + * You can stop the server with an {@linkcode AbortSignal}. The abort signal + * needs to be passed as the `signal` option in the options bag. The server + * aborts when the abort signal is aborted. To wait for the server to close, + * await the promise returned from the `Deno.serve` API. + * + * ```ts + * const ac = new AbortController(); + * + * const server = Deno.serve( + * { signal: ac.signal, path: "path/to/socket" }, + * (_req) => new Response("Hello, world") + * ); + * server.finished.then(() => console.log("Server closed")); + * + * console.log("Closing server..."); + * ac.abort(); + * ``` + * + * By default `Deno.serve` prints the message + * `Listening on path/to/socket` on listening. If you like to + * change this behavior, you can specify a custom `onListen` callback. + * + * ```ts + * Deno.serve({ + * onListen({ path }) { + * console.log(`Server started at ${path}`); + * // ... more info specific to your server .. + * }, + * path: "path/to/socket", + * }, (_req) => new Response("Hello, world")); + * ``` + * + * @category HTTP Server + */ + export function serve( + options: ServeUnixOptions, + handler: ServeUnixHandler, + ): HttpServer; + /** Serves HTTP requests with the given option bag and handler. + * + * You can specify an object with a port and hostname option, which is the + * address to listen on. The default is port `8000` on hostname `"127.0.0.1"`. + * + * You can change the address to listen on using the `hostname` and `port` + * options. The below example serves on port `3000` and hostname `"0.0.0.0"`. + * + * ```ts + * Deno.serve( + * { port: 3000, hostname: "0.0.0.0" }, + * (_req) => new Response("Hello, world") + * ); + * ``` + * + * You can stop the server with an {@linkcode AbortSignal}. The abort signal + * needs to be passed as the `signal` option in the options bag. The server + * aborts when the abort signal is aborted. To wait for the server to close, + * await the promise returned from the `Deno.serve` API. + * + * ```ts + * const ac = new AbortController(); + * + * const server = Deno.serve( + * { signal: ac.signal }, + * (_req) => new Response("Hello, world") + * ); + * server.finished.then(() => console.log("Server closed")); + * + * console.log("Closing server..."); + * ac.abort(); + * ``` + * + * By default `Deno.serve` prints the message + * `Listening on http://:/` on listening. If you like to + * change this behavior, you can specify a custom `onListen` callback. + * + * ```ts + * Deno.serve({ + * onListen({ port, hostname }) { + * console.log(`Server started at http://${hostname}:${port}`); + * // ... more info specific to your server .. + * }, + * }, (_req) => new Response("Hello, world")); + * ``` + * + * To enable TLS you must specify the `key` and `cert` options. + * + * ```ts + * const cert = "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n"; + * const key = "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n"; + * Deno.serve({ cert, key }, (_req) => new Response("Hello, world")); + * ``` + * + * @category HTTP Server + */ + export function serve( + options: ServeOptions | ServeTlsOptions, + handler: ServeHandler, + ): HttpServer; + /** Serves HTTP requests with the given option bag. + * + * You can specify an object with the path option, which is the + * unix domain socket to listen on. + * + * ```ts + * const ac = new AbortController(); + * + * const server = Deno.serve({ + * path: "path/to/socket", + * handler: (_req) => new Response("Hello, world"), + * signal: ac.signal, + * onListen({ path }) { + * console.log(`Server started at ${path}`); + * }, + * }); + * server.finished.then(() => console.log("Server closed")); + * + * console.log("Closing server..."); + * ac.abort(); + * ``` + * + * @category HTTP Server + */ + export function serve( + options: ServeUnixInit & ServeUnixOptions, + ): HttpServer; + /** Serves HTTP requests with the given option bag. + * + * You can specify an object with a port and hostname option, which is the + * address to listen on. The default is port `8000` on hostname `"127.0.0.1"`. + * + * ```ts + * const ac = new AbortController(); + * + * const server = Deno.serve({ + * port: 3000, + * hostname: "0.0.0.0", + * handler: (_req) => new Response("Hello, world"), + * signal: ac.signal, + * onListen({ port, hostname }) { + * console.log(`Server started at http://${hostname}:${port}`); + * }, + * }); + * server.finished.then(() => console.log("Server closed")); + * + * console.log("Closing server..."); + * ac.abort(); + * ``` + * + * @category HTTP Server + */ + export function serve( + options: ServeInit & (ServeOptions | ServeTlsOptions), + ): HttpServer; + + /** **UNSTABLE**: New API, yet to be vetted. + * + * Retrieve the process umask. If `mask` is provided, sets the process umask. + * This call always returns what the umask was before the call. + * + * ```ts + * console.log(Deno.umask()); // e.g. 18 (0o022) + * const prevUmaskValue = Deno.umask(0o077); // e.g. 18 (0o022) + * console.log(Deno.umask()); // e.g. 63 (0o077) + * ``` + * + * This API is under consideration to determine if permissions are required to + * call it. + * + * *Note*: This API is not implemented on Windows + * + * @category File System + */ + export function umask(mask?: number): number; + + /** **UNSTABLE**: New API, yet to be vetted. + * + * All plain number types for interfacing with foreign functions. + * + * @category FFI + */ + type NativeNumberType = + | "u8" + | "i8" + | "u16" + | "i16" + | "u32" + | "i32" + | "f32" + | "f64"; + + /** **UNSTABLE**: New API, yet to be vetted. + * + * All BigInt number types for interfacing with foreign functions. + * + * @category FFI + */ + type NativeBigIntType = + | "u64" + | "i64" + | "usize" + | "isize"; + + /** **UNSTABLE**: New API, yet to be vetted. + * + * The native boolean type for interfacing to foreign functions. + * + * @category FFI + */ + type NativeBooleanType = "bool"; + + /** **UNSTABLE**: New API, yet to be vetted. + * + * The native pointer type for interfacing to foreign functions. + * + * @category FFI + */ + type NativePointerType = "pointer"; + + /** **UNSTABLE**: New API, yet to be vetted. + * + * The native buffer type for interfacing to foreign functions. + * + * @category FFI + */ + type NativeBufferType = "buffer"; + + /** **UNSTABLE**: New API, yet to be vetted. + * + * The native function type for interfacing with foreign functions. + * + * @category FFI + */ + type NativeFunctionType = "function"; + + /** **UNSTABLE**: New API, yet to be vetted. + * + * The native void type for interfacing with foreign functions. + * + * @category FFI + */ + type NativeVoidType = "void"; + + /** **UNSTABLE**: New API, yet to be vetted. + * + * The native struct type for interfacing with foreign functions. + * + * @category FFI + */ + type NativeStructType = { readonly struct: readonly NativeType[] }; + + /** @category FFI */ + const brand: unique symbol; + + /** @category FFI */ + export type NativeU8Enum = "u8" & { [brand]: T }; + /** @category FFI */ + export type NativeI8Enum = "i8" & { [brand]: T }; + /** @category FFI */ + export type NativeU16Enum = "u16" & { [brand]: T }; + /** @category FFI */ + export type NativeI16Enum = "i16" & { [brand]: T }; + /** @category FFI */ + export type NativeU32Enum = "u32" & { [brand]: T }; + /** @category FFI */ + export type NativeI32Enum = "i32" & { [brand]: T }; + /** @category FFI */ + export type NativeTypedPointer = "pointer" & { + [brand]: T; + }; + /** @category FFI */ + export type NativeTypedFunction = + & "function" + & { + [brand]: T; + }; + + /** **UNSTABLE**: New API, yet to be vetted. + * + * All supported types for interfacing with foreign functions. + * + * @category FFI + */ + export type NativeType = + | NativeNumberType + | NativeBigIntType + | NativeBooleanType + | NativePointerType + | NativeBufferType + | NativeFunctionType + | NativeStructType; + + /** **UNSTABLE**: New API, yet to be vetted. + * + * @category FFI + */ + export type NativeResultType = NativeType | NativeVoidType; + + /** **UNSTABLE**: New API, yet to be vetted. + * + * Type conversion for foreign symbol parameters and unsafe callback return + * types. + * + * @category FFI + */ + type ToNativeType = T extends NativeStructType ? BufferSource + : T extends NativeNumberType ? T extends NativeU8Enum ? U + : T extends NativeI8Enum ? U + : T extends NativeU16Enum ? U + : T extends NativeI16Enum ? U + : T extends NativeU32Enum ? U + : T extends NativeI32Enum ? U + : number + : T extends NativeBigIntType ? number | bigint + : T extends NativeBooleanType ? boolean + : T extends NativePointerType ? T extends NativeTypedPointer ? U | null : PointerValue + : T extends NativeFunctionType ? T extends NativeTypedFunction ? PointerValue | null + : PointerValue + : T extends NativeBufferType ? BufferSource | null + : never; + + /** **UNSTABLE**: New API, yet to be vetted. + * + * Type conversion for unsafe callback return types. + * + * @category FFI + */ + type ToNativeResultType = T extends NativeStructType ? BufferSource + : T extends NativeNumberType ? T extends NativeU8Enum ? U + : T extends NativeI8Enum ? U + : T extends NativeU16Enum ? U + : T extends NativeI16Enum ? U + : T extends NativeU32Enum ? U + : T extends NativeI32Enum ? U + : number + : T extends NativeBigIntType ? number | bigint + : T extends NativeBooleanType ? boolean + : T extends NativePointerType ? T extends NativeTypedPointer ? U | null : PointerValue + : T extends NativeFunctionType ? T extends NativeTypedFunction ? PointerObject | null + : PointerValue + : T extends NativeBufferType ? BufferSource | null + : T extends NativeVoidType ? void + : never; + + /** **UNSTABLE**: New API, yet to be vetted. + * + * A utility type for conversion of parameter types of foreign functions. + * + * @category FFI + */ + type ToNativeParameterTypes = + // + [(T[number])[]] extends [T] ? ToNativeType[] + : [readonly (T[number])[]] extends [T] ? readonly ToNativeType[] + : T extends readonly [...NativeType[]] ? { + [K in keyof T]: ToNativeType; + } + : never; + + /** **UNSTABLE**: New API, yet to be vetted. + * + * Type conversion for foreign symbol return types and unsafe callback + * parameters. + * + * @category FFI + */ + type FromNativeType = T extends NativeStructType ? Uint8Array + : T extends NativeNumberType ? T extends NativeU8Enum ? U + : T extends NativeI8Enum ? U + : T extends NativeU16Enum ? U + : T extends NativeI16Enum ? U + : T extends NativeU32Enum ? U + : T extends NativeI32Enum ? U + : number + : T extends NativeBigIntType ? number | bigint + : T extends NativeBooleanType ? boolean + : T extends NativePointerType ? T extends NativeTypedPointer ? U | null : PointerValue + : T extends NativeBufferType ? PointerValue + : T extends NativeFunctionType ? T extends NativeTypedFunction ? PointerObject | null + : PointerValue + : never; + + /** **UNSTABLE**: New API, yet to be vetted. + * + * Type conversion for foreign symbol return types. + * + * @category FFI + */ + type FromNativeResultType = T extends NativeStructType ? Uint8Array + : T extends NativeNumberType ? T extends NativeU8Enum ? U + : T extends NativeI8Enum ? U + : T extends NativeU16Enum ? U + : T extends NativeI16Enum ? U + : T extends NativeU32Enum ? U + : T extends NativeI32Enum ? U + : number + : T extends NativeBigIntType ? number | bigint + : T extends NativeBooleanType ? boolean + : T extends NativePointerType ? T extends NativeTypedPointer ? U | null : PointerValue + : T extends NativeBufferType ? PointerValue + : T extends NativeFunctionType ? T extends NativeTypedFunction ? PointerObject | null + : PointerValue + : T extends NativeVoidType ? void + : never; + + /** **UNSTABLE**: New API, yet to be vetted. + * + * @category FFI + */ + type FromNativeParameterTypes< + T extends readonly NativeType[], + > = + // + [(T[number])[]] extends [T] ? FromNativeType[] + : [readonly (T[number])[]] extends [T] ? readonly FromNativeType[] + : T extends readonly [...NativeType[]] ? { + [K in keyof T]: FromNativeType; + } + : never; + + /** **UNSTABLE**: New API, yet to be vetted. + * + * The interface for a foreign function as defined by its parameter and result + * types. + * + * @category FFI + */ + export interface ForeignFunction< + Parameters extends readonly NativeType[] = readonly NativeType[], + Result extends NativeResultType = NativeResultType, + NonBlocking extends boolean = boolean, + > { + /** Name of the symbol. + * + * Defaults to the key name in symbols object. */ + name?: string; + /** The parameters of the foreign function. */ + parameters: Parameters; + /** The result (return value) of the foreign function. */ + result: Result; + /** When `true`, function calls will run on a dedicated blocking thread and + * will return a `Promise` resolving to the `result`. */ + nonblocking?: NonBlocking; + /** When `true`, function calls can safely callback into JavaScript or + * trigger a garbage collection event. + * + * @default {false} */ + callback?: boolean; + /** When `true`, dlopen will not fail if the symbol is not found. + * Instead, the symbol will be set to `null`. + * + * @default {false} */ + optional?: boolean; + } + + /** **UNSTABLE**: New API, yet to be vetted. + * + * @category FFI + */ + export interface ForeignStatic { + /** Name of the symbol, defaults to the key name in symbols object. */ + name?: string; + /** The type of the foreign static value. */ + type: Type; + /** When `true`, dlopen will not fail if the symbol is not found. + * Instead, the symbol will be set to `null`. + * + * @default {false} */ + optional?: boolean; + } + + /** **UNSTABLE**: New API, yet to be vetted. + * + * A foreign library interface descriptor. + * + * @category FFI + */ + export interface ForeignLibraryInterface { + [name: string]: ForeignFunction | ForeignStatic; + } + + /** **UNSTABLE**: New API, yet to be vetted. + * + * A utility type that infers a foreign symbol. + * + * @category FFI + */ + type StaticForeignSymbol = T extends ForeignFunction + ? FromForeignFunction + : T extends ForeignStatic ? FromNativeType + : never; + + /** **UNSTABLE**: New API, yet to be vetted. + * + * @category FFI + */ + type FromForeignFunction = T["parameters"] extends readonly [] + ? () => StaticForeignSymbolReturnType + : ( + ...args: ToNativeParameterTypes + ) => StaticForeignSymbolReturnType; + + /** **UNSTABLE**: New API, yet to be vetted. + * + * @category FFI + */ + type StaticForeignSymbolReturnType = ConditionalAsync< + T["nonblocking"], + FromNativeResultType + >; + + /** **UNSTABLE**: New API, yet to be vetted. + * + * @category FFI + */ + type ConditionalAsync = IsAsync extends true ? Promise : T; + + /** **UNSTABLE**: New API, yet to be vetted. + * + * A utility type that infers a foreign library interface. + * + * @category FFI + */ + type StaticForeignLibraryInterface = { + [K in keyof T]: T[K]["optional"] extends true ? StaticForeignSymbol | null + : StaticForeignSymbol; + }; + + /** **UNSTABLE**: New API, yet to be vetted. + * + * A non-null pointer, represented as an object + * at runtime. The object's prototype is `null` + * and cannot be changed. The object cannot be + * assigned to either and is thus entirely read-only. + * + * To interact with memory through a pointer use the + * {@linkcode UnsafePointerView} class. To create a + * pointer from an address or the get the address of + * a pointer use the static methods of the + * {@linkcode UnsafePointer} class. + * + * @category FFI + */ + export type PointerObject = { [brand]: T }; + + /** **UNSTABLE**: New API, yet to be vetted. + * + * Pointers are represented either with a {@linkcode PointerObject} + * object or a `null` if the pointer is null. + * + * @category FFI + */ + export type PointerValue = null | PointerObject; + + /** **UNSTABLE**: New API, yet to be vetted. + * + * A collection of static functions for interacting with pointer objects. + * + * @category FFI + */ + export class UnsafePointer { + /** Create a pointer from a numeric value. This one is really dangerous! */ + static create(value: number | bigint): PointerValue; + /** Returns `true` if the two pointers point to the same address. */ + static equals(a: PointerValue, b: PointerValue): boolean; + /** Return the direct memory pointer to the typed array in memory. */ + static of( + value: Deno.UnsafeCallback | BufferSource, + ): PointerValue; + /** Return a new pointer offset from the original by `offset` bytes. */ + static offset( + value: PointerObject, + offset: number, + ): PointerValue; + /** Get the numeric value of a pointer */ + static value(value: PointerValue): number | bigint; + } + + /** **UNSTABLE**: New API, yet to be vetted. + * + * An unsafe pointer view to a memory location as specified by the `pointer` + * value. The `UnsafePointerView` API follows the standard built in interface + * {@linkcode DataView} for accessing the underlying types at an memory + * location (numbers, strings and raw bytes). + * + * @category FFI + */ + export class UnsafePointerView { + constructor(pointer: PointerObject); + + pointer: PointerObject; + + /** Gets a boolean at the specified byte offset from the pointer. */ + getBool(offset?: number): boolean; + /** Gets an unsigned 8-bit integer at the specified byte offset from the + * pointer. */ + getUint8(offset?: number): number; + /** Gets a signed 8-bit integer at the specified byte offset from the + * pointer. */ + getInt8(offset?: number): number; + /** Gets an unsigned 16-bit integer at the specified byte offset from the + * pointer. */ + getUint16(offset?: number): number; + /** Gets a signed 16-bit integer at the specified byte offset from the + * pointer. */ + getInt16(offset?: number): number; + /** Gets an unsigned 32-bit integer at the specified byte offset from the + * pointer. */ + getUint32(offset?: number): number; + /** Gets a signed 32-bit integer at the specified byte offset from the + * pointer. */ + getInt32(offset?: number): number; + /** Gets an unsigned 64-bit integer at the specified byte offset from the + * pointer. */ + getBigUint64(offset?: number): number | bigint; + /** Gets a signed 64-bit integer at the specified byte offset from the + * pointer. */ + getBigInt64(offset?: number): number | bigint; + /** Gets a signed 32-bit float at the specified byte offset from the + * pointer. */ + getFloat32(offset?: number): number; + /** Gets a signed 64-bit float at the specified byte offset from the + * pointer. */ + getFloat64(offset?: number): number; + /** Gets a pointer at the specified byte offset from the pointer */ + getPointer(offset?: number): PointerValue; + /** Gets a C string (`null` terminated string) at the specified byte offset + * from the pointer. */ + getCString(offset?: number): string; + /** Gets a C string (`null` terminated string) at the specified byte offset + * from the specified pointer. */ + static getCString( + pointer: PointerObject, + offset?: number, + ): string; + /** Gets an `ArrayBuffer` of length `byteLength` at the specified byte + * offset from the pointer. */ + getArrayBuffer(byteLength: number, offset?: number): ArrayBuffer; + /** Gets an `ArrayBuffer` of length `byteLength` at the specified byte + * offset from the specified pointer. */ + static getArrayBuffer( + pointer: PointerObject, + byteLength: number, + offset?: number, + ): ArrayBuffer; + /** Copies the memory of the pointer into a typed array. + * + * Length is determined from the typed array's `byteLength`. + * + * Also takes optional byte offset from the pointer. */ + copyInto(destination: BufferSource, offset?: number): void; + /** Copies the memory of the specified pointer into a typed array. + * + * Length is determined from the typed array's `byteLength`. + * + * Also takes optional byte offset from the pointer. */ + static copyInto( + pointer: PointerObject, + destination: BufferSource, + offset?: number, + ): void; + } + + /** **UNSTABLE**: New API, yet to be vetted. + * + * An unsafe pointer to a function, for calling functions that are not present + * as symbols. + * + * @category FFI + */ + export class UnsafeFnPointer { + /** The pointer to the function. */ + pointer: PointerObject; + /** The definition of the function. */ + definition: Fn; + + constructor(pointer: PointerObject>, definition: Fn); + /** @deprecated Properly type {@linkcode pointer} using {@linkcode NativeTypedFunction} or {@linkcode UnsafeCallbackDefinition} types. */ + constructor(pointer: PointerObject, definition: Fn); + + /** Call the foreign function. */ + call: FromForeignFunction; + } + + /** **UNSTABLE**: New API, yet to be vetted. + * + * Definition of a unsafe callback function. + * + * @category FFI + */ + export interface UnsafeCallbackDefinition< + Parameters extends readonly NativeType[] = readonly NativeType[], + Result extends NativeResultType = NativeResultType, + > { + /** The parameters of the callbacks. */ + parameters: Parameters; + /** The current result of the callback. */ + result: Result; + } + + /** **UNSTABLE**: New API, yet to be vetted. + * + * An unsafe callback function. + * + * @category FFI + */ + type UnsafeCallbackFunction< + Parameters extends readonly NativeType[] = readonly NativeType[], + Result extends NativeResultType = NativeResultType, + > = Parameters extends readonly [] ? () => ToNativeResultType : ( + ...args: FromNativeParameterTypes + ) => ToNativeResultType; + + /** **UNSTABLE**: New API, yet to be vetted. + * + * An unsafe function pointer for passing JavaScript functions as C function + * pointers to foreign function calls. + * + * The function pointer remains valid until the `close()` method is called. + * + * All `UnsafeCallback` are always thread safe in that they can be called from + * foreign threads without crashing. However, they do not wake up the Deno event + * loop by default. + * + * If a callback is to be called from foreign threads, use the `threadSafe()` + * static constructor or explicitly call `ref()` to have the callback wake up + * the Deno event loop when called from foreign threads. This also stops + * Deno's process from exiting while the callback still exists and is not + * unref'ed. + * + * Use `deref()` to then allow Deno's process to exit. Calling `deref()` on + * a ref'ed callback does not stop it from waking up the Deno event loop when + * called from foreign threads. + * + * @category FFI + */ + export class UnsafeCallback< + const Definition extends UnsafeCallbackDefinition = UnsafeCallbackDefinition, + > { + constructor( + definition: Definition, + callback: UnsafeCallbackFunction< + Definition["parameters"], + Definition["result"] + >, + ); + + /** The pointer to the unsafe callback. */ + readonly pointer: PointerObject; + /** The definition of the unsafe callback. */ + readonly definition: Definition; + /** The callback function. */ + readonly callback: UnsafeCallbackFunction< + Definition["parameters"], + Definition["result"] + >; + + /** + * Creates an {@linkcode UnsafeCallback} and calls `ref()` once to allow it to + * wake up the Deno event loop when called from foreign threads. + * + * This also stops Deno's process from exiting while the callback still + * exists and is not unref'ed. + */ + static threadSafe< + Definition extends UnsafeCallbackDefinition = UnsafeCallbackDefinition, + >( + definition: Definition, + callback: UnsafeCallbackFunction< + Definition["parameters"], + Definition["result"] + >, + ): UnsafeCallback; + + /** + * Increments the callback's reference counting and returns the new + * reference count. + * + * After `ref()` has been called, the callback always wakes up the + * Deno event loop when called from foreign threads. + * + * If the callback's reference count is non-zero, it keeps Deno's + * process from exiting. + */ + ref(): number; + + /** + * Decrements the callback's reference counting and returns the new + * reference count. + * + * Calling `unref()` does not stop a callback from waking up the Deno + * event loop when called from foreign threads. + * + * If the callback's reference counter is zero, it no longer keeps + * Deno's process from exiting. + */ + unref(): number; + + /** + * Removes the C function pointer associated with this instance. + * + * Continuing to use the instance or the C function pointer after closing + * the `UnsafeCallback` will lead to errors and crashes. + * + * Calling this method sets the callback's reference counting to zero, + * stops the callback from waking up the Deno event loop when called from + * foreign threads and no longer keeps Deno's process from exiting. + */ + close(): void; + } + + /** **UNSTABLE**: New API, yet to be vetted. + * + * A dynamic library resource. Use {@linkcode Deno.dlopen} to load a dynamic + * library and return this interface. + * + * @category FFI + */ + export interface DynamicLibrary { + /** All of the registered library along with functions for calling them. */ + symbols: StaticForeignLibraryInterface; + /** Removes the pointers associated with the library symbols. + * + * Continuing to use symbols that are part of the library will lead to + * errors and crashes. + * + * Calling this method will also immediately set any references to zero and + * will no longer keep Deno's process from exiting. + */ + close(): void; + } + + /** **UNSTABLE**: New API, yet to be vetted. + * + * Opens an external dynamic library and registers symbols, making foreign + * functions available to be called. + * + * Requires `allow-ffi` permission. Loading foreign dynamic libraries can in + * theory bypass all of the sandbox permissions. While it is a separate + * permission users should acknowledge in practice that is effectively the + * same as running with the `allow-all` permission. + * + * @example Given a C library which exports a foreign function named `add()` + * + * ```ts + * // Determine library extension based on + * // your OS. + * let libSuffix = ""; + * switch (Deno.build.os) { + * case "windows": + * libSuffix = "dll"; + * break; + * case "darwin": + * libSuffix = "dylib"; + * break; + * default: + * libSuffix = "so"; + * break; + * } + * + * const libName = `./libadd.${libSuffix}`; + * // Open library and define exported symbols + * const dylib = Deno.dlopen( + * libName, + * { + * "add": { parameters: ["isize", "isize"], result: "isize" }, + * } as const, + * ); + * + * // Call the symbol `add` + * const result = dylib.symbols.add(35, 34); // 69 + * + * console.log(`Result from external addition of 35 and 34: ${result}`); + * ``` + * + * @tags allow-ffi + * @category FFI + */ + export function dlopen( + filename: string | URL, + symbols: S, + ): DynamicLibrary; + + /** **UNSTABLE**: New API, yet to be vetted. + * + * Creates a presentable WebGPU surface from given window and + * display handles. + * + * The parameters correspond to the table below: + * + * | system | winHandle | displayHandle | + * | ----------------- | ------------- | --------------- | + * | "cocoa" (macOS) | `NSView*` | - | + * | "win32" (Windows) | `HWND` | `HINSTANCE` | + * | "x11" (Linux) | Xlib `Window` | Xlib `Display*` | + * + * @category WebGPU + */ + export class UnsafeWindowSurface { + constructor( + system: "cocoa" | "win32" | "x11", + windowHandle: Deno.PointerValue, + displayHandle: Deno.PointerValue, + ); + getContext(context: "webgpu"): GPUCanvasContext; + present(): void; + } + + /** **UNSTABLE**: New API, yet to be vetted. + * + * These are unstable options which can be used with {@linkcode Deno.run}. + * + * @category Sub Process + */ + interface UnstableRunOptions extends RunOptions { + /** If `true`, clears the environment variables before executing the + * sub-process. + * + * @default {false} */ + clearEnv?: boolean; + /** For POSIX systems, sets the group ID for the sub process. */ + gid?: number; + /** For POSIX systems, sets the user ID for the sub process. */ + uid?: number; + } + + /** **UNSTABLE**: New API, yet to be vetted. + * + * Spawns new subprocess. RunOptions must contain at a minimum the `opt.cmd`, + * an array of program arguments, the first of which is the binary. + * + * ```ts + * const p = Deno.run({ + * cmd: ["curl", "https://example.com"], + * }); + * const status = await p.status(); + * ``` + * + * Subprocess uses same working directory as parent process unless `opt.cwd` + * is specified. + * + * Environmental variables from parent process can be cleared using `opt.clearEnv`. + * Doesn't guarantee that only `opt.env` variables are present, + * as the OS may set environmental variables for processes. + * + * Environmental variables for subprocess can be specified using `opt.env` + * mapping. + * + * `opt.uid` sets the child process’s user ID. This translates to a setuid call + * in the child process. Failure in the setuid call will cause the spawn to fail. + * + * `opt.gid` is similar to `opt.uid`, but sets the group ID of the child process. + * This has the same semantics as the uid field. + * + * By default subprocess inherits stdio of parent process. To change + * this this, `opt.stdin`, `opt.stdout`, and `opt.stderr` can be set + * independently to a resource ID (_rid_) of an open file, `"inherit"`, + * `"piped"`, or `"null"`: + * + * - _number_: the resource ID of an open file/resource. This allows you to + * read or write to a file. + * - `"inherit"`: The default if unspecified. The subprocess inherits from the + * parent. + * - `"piped"`: A new pipe should be arranged to connect the parent and child + * sub-process. + * - `"null"`: This stream will be ignored. This is the equivalent of attaching + * the stream to `/dev/null`. + * + * Details of the spawned process are returned as an instance of + * {@linkcode Deno.Process}. + * + * Requires `allow-run` permission. + * + * @tags allow-run + * @category Sub Process + */ + export function run( + opt: T, + ): Process; + + /** **UNSTABLE**: New API, yet to be vetted. + * + * A custom `HttpClient` for use with {@linkcode fetch} function. This is + * designed to allow custom certificates or proxies to be used with `fetch()`. + * + * @example ```ts + * const caCert = await Deno.readTextFile("./ca.pem"); + * const client = Deno.createHttpClient({ caCerts: [ caCert ] }); + * const req = await fetch("https://myserver.com", { client }); + * ``` + * + * @category Fetch API + */ + export interface HttpClient extends Disposable { + /** Close the HTTP client. */ + close(): void; + } + + /** **UNSTABLE**: New API, yet to be vetted. + * + * The options used when creating a {@linkcode Deno.HttpClient}. + * + * @category Fetch API + */ + export interface CreateHttpClientOptions { + /** A list of root certificates that will be used in addition to the + * default root certificates to verify the peer's certificate. + * + * Must be in PEM format. */ + caCerts?: string[]; + /** A HTTP proxy to use for new connections. */ + proxy?: Proxy; + /** Cert chain in PEM format. */ + cert?: string; + /** Server private key in PEM format. */ + key?: string; + /** Sets the maximum numer of idle connections per host allowed in the pool. */ + poolMaxIdlePerHost?: number; + /** Set an optional timeout for idle sockets being kept-alive. + * Set to false to disable the timeout. */ + poolIdleTimeout?: number | false; + /** + * Whether HTTP/1.1 is allowed or not. + * + * @default {true} + */ + http1?: boolean; + /** Whether HTTP/2 is allowed or not. + * + * @default {true} + */ + http2?: boolean; + /** Whether setting the host header is allowed or not. + * + * @default {false} + */ + allowHost?: boolean; + } + + /** **UNSTABLE**: New API, yet to be vetted. + * + * The definition of a proxy when specifying + * {@linkcode Deno.CreateHttpClientOptions}. + * + * @category Fetch API + */ + export interface Proxy { + /** The string URL of the proxy server to use. */ + url: string; + /** The basic auth credentials to be used against the proxy server. */ + basicAuth?: BasicAuth; + } + + /** **UNSTABLE**: New API, yet to be vetted. + * + * Basic authentication credentials to be used with a {@linkcode Deno.Proxy} + * server when specifying {@linkcode Deno.CreateHttpClientOptions}. + * + * @category Fetch API + */ + export interface BasicAuth { + /** The username to be used against the proxy server. */ + username: string; + /** The password to be used against the proxy server. */ + password: string; + } + + /** **UNSTABLE**: New API, yet to be vetted. + * + * Create a custom HttpClient to use with {@linkcode fetch}. This is an + * extension of the web platform Fetch API which allows Deno to use custom + * TLS certificates and connect via a proxy while using `fetch()`. + * + * @example ```ts + * const caCert = await Deno.readTextFile("./ca.pem"); + * const client = Deno.createHttpClient({ caCerts: [ caCert ] }); + * const response = await fetch("https://myserver.com", { client }); + * ``` + * + * @example ```ts + * const client = Deno.createHttpClient({ + * proxy: { url: "http://myproxy.com:8080" } + * }); + * const response = await fetch("https://myserver.com", { client }); + * ``` + * + * @category Fetch API + */ + export function createHttpClient( + options: CreateHttpClientOptions, + ): HttpClient; + + /** **UNSTABLE**: New API, yet to be vetted. + * + * Represents membership of a IPv4 multicast group. + * + * @category Network + */ + interface MulticastV4Membership { + /** Leaves the multicast group. */ + leave: () => Promise; + /** Sets the multicast loopback option. If enabled, multicast packets will be looped back to the local socket. */ + setLoopback: (loopback: boolean) => Promise; + /** Sets the time-to-live of outgoing multicast packets for this socket. */ + setTTL: (ttl: number) => Promise; + } + + /** **UNSTABLE**: New API, yet to be vetted. + * + * Represents membership of a IPv6 multicast group. + * + * @category Network + */ + interface MulticastV6Membership { + /** Leaves the multicast group. */ + leave: () => Promise; + /** Sets the multicast loopback option. If enabled, multicast packets will be looped back to the local socket. */ + setLoopback: (loopback: boolean) => Promise; + } + + /** **UNSTABLE**: New API, yet to be vetted. + * + * A generic transport listener for message-oriented protocols. + * + * @category Network + */ + export interface DatagramConn extends AsyncIterable<[Uint8Array, Addr]> { + /** Joins an IPv4 multicast group. */ + joinMulticastV4( + address: string, + networkInterface: string, + ): Promise; + + /** Joins an IPv6 multicast group. */ + joinMulticastV6( + address: string, + networkInterface: number, + ): Promise; + + /** Waits for and resolves to the next message to the instance. + * + * Messages are received in the format of a tuple containing the data array + * and the address information. + */ + receive(p?: Uint8Array): Promise<[Uint8Array, Addr]>; + /** Sends a message to the target via the connection. The method resolves + * with the number of bytes sent. */ + send(p: Uint8Array, addr: Addr): Promise; + /** Close closes the socket. Any pending message promises will be rejected + * with errors. */ + close(): void; + /** Return the address of the instance. */ + readonly addr: Addr; + [Symbol.asyncIterator](): AsyncIterableIterator<[Uint8Array, Addr]>; + } + + /** + * @category Network + */ + export interface TcpListenOptions extends ListenOptions { + /** When `true` the SO_REUSEPORT flag will be set on the listener. This + * allows multiple processes to listen on the same address and port. + * + * On Linux this will cause the kernel to distribute incoming connections + * across the different processes that are listening on the same address and + * port. + * + * This flag is only supported on Linux. It is silently ignored on other + * platforms. + * + * @default {false} */ + reusePort?: boolean; + } + + /** **UNSTABLE**: New API, yet to be vetted. + * + * Unstable options which can be set when opening a datagram listener via + * {@linkcode Deno.listenDatagram}. + * + * @category Network + */ + export interface UdpListenOptions extends ListenOptions { + /** When `true` the specified address will be reused, even if another + * process has already bound a socket on it. This effectively steals the + * socket from the listener. + * + * @default {false} */ + reuseAddress?: boolean; + + /** When `true`, sent multicast packets will be looped back to the local socket. + * + * @default {false} */ + loopback?: boolean; + } + + /** **UNSTABLE**: New API, yet to be vetted. + * + * Listen announces on the local transport address. + * + * ```ts + * const listener1 = Deno.listenDatagram({ + * port: 80, + * transport: "udp" + * }); + * const listener2 = Deno.listenDatagram({ + * hostname: "golang.org", + * port: 80, + * transport: "udp" + * }); + * ``` + * + * Requires `allow-net` permission. + * + * @tags allow-net + * @category Network + */ + export function listenDatagram( + options: UdpListenOptions & { transport: "udp" }, + ): DatagramConn; + + /** **UNSTABLE**: New API, yet to be vetted. + * + * Listen announces on the local transport address. + * + * ```ts + * const listener = Deno.listenDatagram({ + * path: "/foo/bar.sock", + * transport: "unixpacket" + * }); + * ``` + * + * Requires `allow-read` and `allow-write` permission. + * + * @tags allow-read, allow-write + * @category Network + */ + export function listenDatagram( + options: UnixListenOptions & { transport: "unixpacket" }, + ): DatagramConn; + + /** **UNSTABLE**: New API, yet to be vetted. + * + * Acquire an advisory file-system lock for the provided file. + * + * @param [exclusive=false] + * @category File System + */ + export function flock(rid: number, exclusive?: boolean): Promise; + + /** **UNSTABLE**: New API, yet to be vetted. + * + * Acquire an advisory file-system lock synchronously for the provided file. + * + * @param [exclusive=false] + * @category File System + */ + export function flockSync(rid: number, exclusive?: boolean): void; + + /** **UNSTABLE**: New API, yet to be vetted. + * + * Release an advisory file-system lock for the provided file. + * + * @category File System + */ + export function funlock(rid: number): Promise; + + /** **UNSTABLE**: New API, yet to be vetted. + * + * Release an advisory file-system lock for the provided file synchronously. + * + * @category File System + */ + export function funlockSync(rid: number): void; + + /** **UNSTABLE**: New API, yet to be vetted. + * + * Open a new {@linkcode Deno.Kv} connection to persist data. + * + * When a path is provided, the database will be persisted to disk at that + * path. Read and write access to the file is required. + * + * When no path is provided, the database will be opened in a default path for + * the current script. This location is persistent across script runs and is + * keyed on the origin storage key (the same key that is used to determine + * `localStorage` persistence). More information about the origin storage key + * can be found in the Deno Manual. + * + * @tags allow-read, allow-write + * @category KV + */ + export function openKv(path?: string): Promise; + + /** **UNSTABLE**: New API, yet to be vetted. + * + * CronScheduleExpression is used as the type of `minute`, `hour`, + * `dayOfMonth`, `month`, and `dayOfWeek` in {@linkcode CronSchedule}. + * @category Cron + */ + type CronScheduleExpression = number | { exact: number | number[] } | { + start?: number; + end?: number; + every?: number; + }; + + /** **UNSTABLE**: New API, yet to be vetted. + * + * CronSchedule is the interface used for JSON format + * cron `schedule`. + * @category Cron + */ + export interface CronSchedule { + minute?: CronScheduleExpression; + hour?: CronScheduleExpression; + dayOfMonth?: CronScheduleExpression; + month?: CronScheduleExpression; + dayOfWeek?: CronScheduleExpression; + } + + /** **UNSTABLE**: New API, yet to be vetted. + * + * Create a cron job that will periodically execute the provided handler + * callback based on the specified schedule. + * + * ```ts + * Deno.cron("sample cron", "20 * * * *", () => { + * console.log("cron job executed"); + * }); + * ``` + * + * ```ts + * Deno.cron("sample cron", { hour: { every: 6 } }, () => { + * console.log("cron job executed"); + * }); + * ``` + * + * `schedule` can be a string in the Unix cron format or in JSON format + * as specified by interface {@linkcode CronSchedule}, where time is specified + * using UTC time zone. + * + * @category Cron + */ + export function cron( + name: string, + schedule: string | CronSchedule, + handler: () => Promise | void, + ): Promise; + + /** **UNSTABLE**: New API, yet to be vetted. + * + * Create a cron job that will periodically execute the provided handler + * callback based on the specified schedule. + * + * ```ts + * Deno.cron("sample cron", "20 * * * *", { + * backoffSchedule: [10, 20] + * }, () => { + * console.log("cron job executed"); + * }); + * ``` + * + * `schedule` can be a string in the Unix cron format or in JSON format + * as specified by interface {@linkcode CronSchedule}, where time is specified + * using UTC time zone. + * + * `backoffSchedule` option can be used to specify the retry policy for failed + * executions. Each element in the array represents the number of milliseconds + * to wait before retrying the execution. For example, `[1000, 5000, 10000]` + * means that a failed execution will be retried at most 3 times, with 1 + * second, 5 seconds, and 10 seconds delay between each retry. + * + * @category Cron + */ + export function cron( + name: string, + schedule: string | CronSchedule, + options: { backoffSchedule?: number[]; signal?: AbortSignal }, + handler: () => Promise | void, + ): Promise; + + /** **UNSTABLE**: New API, yet to be vetted. + * + * A key to be persisted in a {@linkcode Deno.Kv}. A key is a sequence + * of {@linkcode Deno.KvKeyPart}s. + * + * Keys are ordered lexicographically by their parts. The first part is the + * most significant, and the last part is the least significant. The order of + * the parts is determined by both the type and the value of the part. The + * relative significance of the types can be found in documentation for the + * {@linkcode Deno.KvKeyPart} type. + * + * Keys have a maximum size of 2048 bytes serialized. If the size of the key + * exceeds this limit, an error will be thrown on the operation that this key + * was passed to. + * + * @category KV + */ + export type KvKey = readonly KvKeyPart[]; + + /** **UNSTABLE**: New API, yet to be vetted. + * + * A single part of a {@linkcode Deno.KvKey}. Parts are ordered + * lexicographically, first by their type, and within a given type by their + * value. + * + * The ordering of types is as follows: + * + * 1. `Uint8Array` + * 2. `string` + * 3. `number` + * 4. `bigint` + * 5. `boolean` + * + * Within a given type, the ordering is as follows: + * + * - `Uint8Array` is ordered by the byte ordering of the array + * - `string` is ordered by the byte ordering of the UTF-8 encoding of the + * string + * - `number` is ordered following this pattern: `-NaN` + * < `-Infinity` < `-100.0` < `-1.0` < -`0.5` < `-0.0` < `0.0` < `0.5` + * < `1.0` < `100.0` < `Infinity` < `NaN` + * - `bigint` is ordered by mathematical ordering, with the largest negative + * number being the least first value, and the largest positive number + * being the last value + * - `boolean` is ordered by `false` < `true` + * + * This means that the part `1.0` (a number) is ordered before the part `2.0` + * (also a number), but is greater than the part `0n` (a bigint), because + * `1.0` is a number and `0n` is a bigint, and type ordering has precedence + * over the ordering of values within a type. + * + * @category KV + */ + export type KvKeyPart = + | Uint8Array + | string + | number + | bigint + | boolean + | symbol; + + /** **UNSTABLE**: New API, yet to be vetted. + * + * Consistency level of a KV operation. + * + * - `strong` - This operation must be strongly-consistent. + * - `eventual` - Eventually-consistent behavior is allowed. + * + * @category KV + */ + export type KvConsistencyLevel = "strong" | "eventual"; + + /** **UNSTABLE**: New API, yet to be vetted. + * + * A selector that selects the range of data returned by a list operation on a + * {@linkcode Deno.Kv}. + * + * The selector can either be a prefix selector or a range selector. A prefix + * selector selects all keys that start with the given prefix (optionally + * starting at a given key). A range selector selects all keys that are + * lexicographically between the given start and end keys. + * + * @category KV + */ + export type KvListSelector = + | { prefix: KvKey } + | { prefix: KvKey; start: KvKey } + | { prefix: KvKey; end: KvKey } + | { start: KvKey; end: KvKey }; + + /** **UNSTABLE**: New API, yet to be vetted. + * + * A mutation to a key in a {@linkcode Deno.Kv}. A mutation is a + * combination of a key, a value, and a type. The type determines how the + * mutation is applied to the key. + * + * - `set` - Sets the value of the key to the given value, overwriting any + * existing value. Optionally an `expireIn` option can be specified to + * set a time-to-live (TTL) for the key. The TTL is specified in + * milliseconds, and the key will be deleted from the database at earliest + * after the specified number of milliseconds have elapsed. Once the + * specified duration has passed, the key may still be visible for some + * additional time. If the `expireIn` option is not specified, the key will + * not expire. + * - `delete` - Deletes the key from the database. The mutation is a no-op if + * the key does not exist. + * - `sum` - Adds the given value to the existing value of the key. Both the + * value specified in the mutation, and any existing value must be of type + * `Deno.KvU64`. If the key does not exist, the value is set to the given + * value (summed with 0). If the result of the sum overflows an unsigned + * 64-bit integer, the result is wrapped around. + * - `max` - Sets the value of the key to the maximum of the existing value + * and the given value. Both the value specified in the mutation, and any + * existing value must be of type `Deno.KvU64`. If the key does not exist, + * the value is set to the given value. + * - `min` - Sets the value of the key to the minimum of the existing value + * and the given value. Both the value specified in the mutation, and any + * existing value must be of type `Deno.KvU64`. If the key does not exist, + * the value is set to the given value. + * + * @category KV + */ + export type KvMutation = + & { key: KvKey } + & ( + | { type: "set"; value: unknown; expireIn?: number } + | { type: "delete" } + | { type: "sum"; value: KvU64 } + | { type: "max"; value: KvU64 } + | { type: "min"; value: KvU64 } + ); + + /** **UNSTABLE**: New API, yet to be vetted. + * + * An iterator over a range of data entries in a {@linkcode Deno.Kv}. + * + * The cursor getter returns the cursor that can be used to resume the + * iteration from the current position in the future. + * + * @category KV + */ + export class KvListIterator implements AsyncIterableIterator> { + /** + * Returns the cursor of the current position in the iteration. This cursor + * can be used to resume the iteration from the current position in the + * future by passing it to the `cursor` option of the `list` method. + */ + get cursor(): string; + + next(): Promise, undefined>>; + [Symbol.asyncIterator](): AsyncIterableIterator>; + } + + /** **UNSTABLE**: New API, yet to be vetted. + * + * A versioned pair of key and value in a {@linkcode Deno.Kv}. + * + * The `versionstamp` is a string that represents the current version of the + * key-value pair. It can be used to perform atomic operations on the KV store + * by passing it to the `check` method of a {@linkcode Deno.AtomicOperation}. + * + * @category KV + */ + export type KvEntry = { key: KvKey; value: T; versionstamp: string }; + + /** + * **UNSTABLE**: New API, yet to be vetted. + * + * An optional versioned pair of key and value in a {@linkcode Deno.Kv}. + * + * This is the same as a {@linkcode KvEntry}, but the `value` and `versionstamp` + * fields may be `null` if no value exists for the given key in the KV store. + * + * @category KV + */ + export type KvEntryMaybe = KvEntry | { + key: KvKey; + value: null; + versionstamp: null; + }; + + /** **UNSTABLE**: New API, yet to be vetted. + * + * Options for listing key-value pairs in a {@linkcode Deno.Kv}. + * + * @category KV + */ + export interface KvListOptions { + /** + * The maximum number of key-value pairs to return. If not specified, all + * matching key-value pairs will be returned. + */ + limit?: number; + /** + * The cursor to resume the iteration from. If not specified, the iteration + * will start from the beginning. + */ + cursor?: string; + /** + * Whether to reverse the order of the returned key-value pairs. If not + * specified, the order will be ascending from the start of the range as per + * the lexicographical ordering of the keys. If `true`, the order will be + * descending from the end of the range. + * + * The default value is `false`. + */ + reverse?: boolean; + /** + * The consistency level of the list operation. The default consistency + * level is "strong". Some use cases can benefit from using a weaker + * consistency level. For more information on consistency levels, see the + * documentation for {@linkcode Deno.KvConsistencyLevel}. + * + * List operations are performed in batches (in sizes specified by the + * `batchSize` option). The consistency level of the list operation is + * applied to each batch individually. This means that while each batch is + * guaranteed to be consistent within itself, the entire list operation may + * not be consistent across batches because a mutation may be applied to a + * key-value pair between batches, in a batch that has already been returned + * by the list operation. + */ + consistency?: KvConsistencyLevel; + /** + * The size of the batches in which the list operation is performed. Larger + * or smaller batch sizes may positively or negatively affect the + * performance of a list operation depending on the specific use case and + * iteration behavior. Slow iterating queries may benefit from using a + * smaller batch size for increased overall consistency, while fast + * iterating queries may benefit from using a larger batch size for better + * performance. + * + * The default batch size is equal to the `limit` option, or 100 if this is + * unset. The maximum value for this option is 500. Larger values will be + * clamped. + */ + batchSize?: number; + } + + /** @category KV */ + export interface KvCommitResult { + ok: true; + /** The versionstamp of the value committed to KV. */ + versionstamp: string; + } + + /** @category KV */ + export interface KvCommitError { + ok: false; + } + + /** **UNSTABLE**: New API, yet to be vetted. + * + * A check to perform as part of a {@linkcode Deno.AtomicOperation}. The check + * will fail if the versionstamp for the key-value pair in the KV store does + * not match the given versionstamp. A check with a `null` versionstamp checks + * that the key-value pair does not currently exist in the KV store. + * + * @category KV + */ + export interface AtomicCheck { + key: KvKey; + versionstamp: string | null; + } + + /** **UNSTABLE**: New API, yet to be vetted. + * + * An operation on a {@linkcode Deno.Kv} that can be performed + * atomically. Atomic operations do not auto-commit, and must be committed + * explicitly by calling the `commit` method. + * + * Atomic operations can be used to perform multiple mutations on the KV store + * in a single atomic transaction. They can also be used to perform + * conditional mutations by specifying one or more + * {@linkcode Deno.AtomicCheck}s that ensure that a mutation is only performed + * if the key-value pair in the KV has a specific versionstamp. If any of the + * checks fail, the entire operation will fail and no mutations will be made. + * + * The ordering of mutations is guaranteed to be the same as the ordering of + * the mutations specified in the operation. Checks are performed before any + * mutations are performed. The ordering of checks is unobservable. + * + * Atomic operations can be used to implement optimistic locking, where a + * mutation is only performed if the key-value pair in the KV store has not + * been modified since the last read. This can be done by specifying a check + * that ensures that the versionstamp of the key-value pair matches the + * versionstamp that was read. If the check fails, the mutation will not be + * performed and the operation will fail. One can then retry the read-modify- + * write operation in a loop until it succeeds. + * + * The `commit` method of an atomic operation returns a value indicating + * whether checks passed and mutations were performed. If the operation failed + * because of a failed check, the return value will be a + * {@linkcode Deno.KvCommitError} with an `ok: false` property. If the + * operation failed for any other reason (storage error, invalid value, etc.), + * an exception will be thrown. If the operation succeeded, the return value + * will be a {@linkcode Deno.KvCommitResult} object with a `ok: true` property + * and the versionstamp of the value committed to KV. + + * + * @category KV + */ + export class AtomicOperation { + /** + * Add to the operation a check that ensures that the versionstamp of the + * key-value pair in the KV store matches the given versionstamp. If the + * check fails, the entire operation will fail and no mutations will be + * performed during the commit. + */ + check(...checks: AtomicCheck[]): this; + /** + * Add to the operation a mutation that performs the specified mutation on + * the specified key if all checks pass during the commit. The types and + * semantics of all available mutations are described in the documentation + * for {@linkcode Deno.KvMutation}. + */ + mutate(...mutations: KvMutation[]): this; + /** + * Shortcut for creating a `sum` mutation. This method wraps `n` in a + * {@linkcode Deno.KvU64}, so the value of `n` must be in the range + * `[0, 2^64-1]`. + */ + sum(key: KvKey, n: bigint): this; + /** + * Shortcut for creating a `min` mutation. This method wraps `n` in a + * {@linkcode Deno.KvU64}, so the value of `n` must be in the range + * `[0, 2^64-1]`. + */ + min(key: KvKey, n: bigint): this; + /** + * Shortcut for creating a `max` mutation. This method wraps `n` in a + * {@linkcode Deno.KvU64}, so the value of `n` must be in the range + * `[0, 2^64-1]`. + */ + max(key: KvKey, n: bigint): this; + /** + * Add to the operation a mutation that sets the value of the specified key + * to the specified value if all checks pass during the commit. + * + * Optionally an `expireIn` option can be specified to set a time-to-live + * (TTL) for the key. The TTL is specified in milliseconds, and the key will + * be deleted from the database at earliest after the specified number of + * milliseconds have elapsed. Once the specified duration has passed, the + * key may still be visible for some additional time. If the `expireIn` + * option is not specified, the key will not expire. + */ + set(key: KvKey, value: unknown, options?: { expireIn?: number }): this; + /** + * Add to the operation a mutation that deletes the specified key if all + * checks pass during the commit. + */ + delete(key: KvKey): this; + /** + * Add to the operation a mutation that enqueues a value into the queue + * if all checks pass during the commit. + */ + enqueue( + value: unknown, + options?: { + delay?: number; + keysIfUndelivered?: Deno.KvKey[]; + backoffSchedule?: number[]; + }, + ): this; + /** + * Commit the operation to the KV store. Returns a value indicating whether + * checks passed and mutations were performed. If the operation failed + * because of a failed check, the return value will be a {@linkcode + * Deno.KvCommitError} with an `ok: false` property. If the operation failed + * for any other reason (storage error, invalid value, etc.), an exception + * will be thrown. If the operation succeeded, the return value will be a + * {@linkcode Deno.KvCommitResult} object with a `ok: true` property and the + * versionstamp of the value committed to KV. + * + * If the commit returns `ok: false`, one may create a new atomic operation + * with updated checks and mutations and attempt to commit it again. See the + * note on optimistic locking in the documentation for + * {@linkcode Deno.AtomicOperation}. + */ + commit(): Promise; + } + + /** **UNSTABLE**: New API, yet to be vetted. + * + * A key-value database that can be used to store and retrieve data. + * + * Data is stored as key-value pairs, where the key is a {@linkcode Deno.KvKey} + * and the value is an arbitrary structured-serializable JavaScript value. + * Keys are ordered lexicographically as described in the documentation for + * {@linkcode Deno.KvKey}. Keys are unique within a database, and the last + * value set for a given key is the one that is returned when reading the + * key. Keys can be deleted from the database, in which case they will no + * longer be returned when reading keys. + * + * Values can be any structured-serializable JavaScript value (objects, + * arrays, strings, numbers, etc.). The special value {@linkcode Deno.KvU64} + * can be used to store 64-bit unsigned integers in the database. This special + * value can not be nested within other objects or arrays. In addition to the + * regular database mutation operations, the unsigned 64-bit integer value + * also supports `sum`, `max`, and `min` mutations. + * + * Keys are versioned on write by assigning the key an ever-increasing + * "versionstamp". The versionstamp represents the version of a key-value pair + * in the database at some point in time, and can be used to perform + * transactional operations on the database without requiring any locking. + * This is enabled by atomic operations, which can have conditions that ensure + * that the operation only succeeds if the versionstamp of the key-value pair + * matches an expected versionstamp. + * + * Keys have a maximum length of 2048 bytes after serialization. Values have a + * maximum length of 64 KiB after serialization. Serialization of both keys + * and values is somewhat opaque, but one can usually assume that the + * serialization of any value is about the same length as the resulting string + * of a JSON serialization of that same value. If theses limits are exceeded, + * an exception will be thrown. + * + * @category KV + */ + export class Kv implements Disposable { + /** + * Retrieve the value and versionstamp for the given key from the database + * in the form of a {@linkcode Deno.KvEntryMaybe}. If no value exists for + * the key, the returned entry will have a `null` value and versionstamp. + * + * ```ts + * const db = await Deno.openKv(); + * const result = await db.get(["foo"]); + * result.key; // ["foo"] + * result.value; // "bar" + * result.versionstamp; // "00000000000000010000" + * ``` + * + * The `consistency` option can be used to specify the consistency level + * for the read operation. The default consistency level is "strong". Some + * use cases can benefit from using a weaker consistency level. For more + * information on consistency levels, see the documentation for + * {@linkcode Deno.KvConsistencyLevel}. + */ + get( + key: KvKey, + options?: { consistency?: KvConsistencyLevel }, + ): Promise>; + + /** + * Retrieve multiple values and versionstamps from the database in the form + * of an array of {@linkcode Deno.KvEntryMaybe} objects. The returned array + * will have the same length as the `keys` array, and the entries will be in + * the same order as the keys. If no value exists for a given key, the + * returned entry will have a `null` value and versionstamp. + * + * ```ts + * const db = await Deno.openKv(); + * const result = await db.getMany([["foo"], ["baz"]]); + * result[0].key; // ["foo"] + * result[0].value; // "bar" + * result[0].versionstamp; // "00000000000000010000" + * result[1].key; // ["baz"] + * result[1].value; // null + * result[1].versionstamp; // null + * ``` + * + * The `consistency` option can be used to specify the consistency level + * for the read operation. The default consistency level is "strong". Some + * use cases can benefit from using a weaker consistency level. For more + * information on consistency levels, see the documentation for + * {@linkcode Deno.KvConsistencyLevel}. + */ + getMany( + keys: readonly [...{ [K in keyof T]: KvKey }], + options?: { consistency?: KvConsistencyLevel }, + ): Promise<{ [K in keyof T]: KvEntryMaybe }>; + /** + * Set the value for the given key in the database. If a value already + * exists for the key, it will be overwritten. + * + * ```ts + * const db = await Deno.openKv(); + * await db.set(["foo"], "bar"); + * ``` + * + * Optionally an `expireIn` option can be specified to set a time-to-live + * (TTL) for the key. The TTL is specified in milliseconds, and the key will + * be deleted from the database at earliest after the specified number of + * milliseconds have elapsed. Once the specified duration has passed, the + * key may still be visible for some additional time. If the `expireIn` + * option is not specified, the key will not expire. + */ + set( + key: KvKey, + value: unknown, + options?: { expireIn?: number }, + ): Promise; + + /** + * Delete the value for the given key from the database. If no value exists + * for the key, this operation is a no-op. + * + * ```ts + * const db = await Deno.openKv(); + * await db.delete(["foo"]); + * ``` + */ + delete(key: KvKey): Promise; + + /** + * Retrieve a list of keys in the database. The returned list is an + * {@linkcode Deno.KvListIterator} which can be used to iterate over the + * entries in the database. + * + * Each list operation must specify a selector which is used to specify the + * range of keys to return. The selector can either be a prefix selector, or + * a range selector: + * + * - A prefix selector selects all keys that start with the given prefix of + * key parts. For example, the selector `["users"]` will select all keys + * that start with the prefix `["users"]`, such as `["users", "alice"]` + * and `["users", "bob"]`. Note that you can not partially match a key + * part, so the selector `["users", "a"]` will not match the key + * `["users", "alice"]`. A prefix selector may specify a `start` key that + * is used to skip over keys that are lexicographically less than the + * start key. + * - A range selector selects all keys that are lexicographically between + * the given start and end keys (including the start, and excluding the + * end). For example, the selector `["users", "a"], ["users", "n"]` will + * select all keys that start with the prefix `["users"]` and have a + * second key part that is lexicographically between `a` and `n`, such as + * `["users", "alice"]`, `["users", "bob"]`, and `["users", "mike"]`, but + * not `["users", "noa"]` or `["users", "zoe"]`. + * + * ```ts + * const db = await Deno.openKv(); + * const entries = db.list({ prefix: ["users"] }); + * for await (const entry of entries) { + * entry.key; // ["users", "alice"] + * entry.value; // { name: "Alice" } + * entry.versionstamp; // "00000000000000010000" + * } + * ``` + * + * The `options` argument can be used to specify additional options for the + * list operation. See the documentation for {@linkcode Deno.KvListOptions} + * for more information. + */ + list( + selector: KvListSelector, + options?: KvListOptions, + ): KvListIterator; + + /** + * Add a value into the database queue to be delivered to the queue + * listener via {@linkcode Deno.Kv.listenQueue}. + * + * ```ts + * const db = await Deno.openKv(); + * await db.enqueue("bar"); + * ``` + * + * The `delay` option can be used to specify the delay (in milliseconds) + * of the value delivery. The default delay is 0, which means immediate + * delivery. + * + * ```ts + * const db = await Deno.openKv(); + * await db.enqueue("bar", { delay: 60000 }); + * ``` + * + * The `keysIfUndelivered` option can be used to specify the keys to + * be set if the value is not successfully delivered to the queue + * listener after several attempts. The values are set to the value of + * the queued message. + * + * The `backoffSchedule` option can be used to specify the retry policy for + * failed message delivery. Each element in the array represents the number of + * milliseconds to wait before retrying the delivery. For example, + * `[1000, 5000, 10000]` means that a failed delivery will be retried + * at most 3 times, with 1 second, 5 seconds, and 10 seconds delay + * between each retry. + * + * ```ts + * const db = await Deno.openKv(); + * await db.enqueue("bar", { + * keysIfUndelivered: [["foo", "bar"]], + * backoffSchedule: [1000, 5000, 10000], + * }); + * ``` + */ + enqueue( + value: unknown, + options?: { + delay?: number; + keysIfUndelivered?: Deno.KvKey[]; + backoffSchedule?: number[]; + }, + ): Promise; + + /** + * Listen for queue values to be delivered from the database queue, which + * were enqueued with {@linkcode Deno.Kv.enqueue}. The provided handler + * callback is invoked on every dequeued value. A failed callback + * invocation is automatically retried multiple times until it succeeds + * or until the maximum number of retries is reached. + * + * ```ts + * const db = await Deno.openKv(); + * db.listenQueue(async (msg: unknown) => { + * await db.set(["foo"], msg); + * }); + * ``` + */ + // deno-lint-ignore no-explicit-any + listenQueue(handler: (value: any) => Promise | void): Promise; + + /** + * Create a new {@linkcode Deno.AtomicOperation} object which can be used to + * perform an atomic transaction on the database. This does not perform any + * operations on the database - the atomic transaction must be committed + * explicitly using the {@linkcode Deno.AtomicOperation.commit} method once + * all checks and mutations have been added to the operation. + */ + atomic(): AtomicOperation; + + /** + * Watch for changes to the given keys in the database. The returned stream + * is a {@linkcode ReadableStream} that emits a new value whenever any of + * the watched keys change their versionstamp. The emitted value is an array + * of {@linkcode Deno.KvEntryMaybe} objects, with the same length and order + * as the `keys` array. If no value exists for a given key, the returned + * entry will have a `null` value and versionstamp. + * + * The returned stream does not return every single intermediate state of + * the watched keys, but rather only keeps you up to date with the latest + * state of the keys. This means that if a key is modified multiple times + * quickly, you may not receive a notification for every single change, but + * rather only the latest state of the key. + * + * ```ts + * const db = await Deno.openKv(); + * + * const stream = db.watch([["foo"], ["bar"]]); + * for await (const entries of stream) { + * entries[0].key; // ["foo"] + * entries[0].value; // "bar" + * entries[0].versionstamp; // "00000000000000010000" + * entries[1].key; // ["bar"] + * entries[1].value; // null + * entries[1].versionstamp; // null + * } + * ``` + * + * The `options` argument can be used to specify additional options for the + * watch operation. The `raw` option can be used to specify whether a new + * value should be emitted whenever a mutation occurs on any of the watched + * keys (even if the value of the key does not change, such as deleting a + * deleted key), or only when entries have observably changed in some way. + * When `raw: true` is used, it is possible for the stream to occasionally + * emit values even if no mutations have occurred on any of the watched + * keys. The default value for this option is `false`. + */ + watch( + keys: readonly [...{ [K in keyof T]: KvKey }], + options?: { raw?: boolean }, + ): ReadableStream<{ [K in keyof T]: KvEntryMaybe }>; + + /** + * Close the database connection. This will prevent any further operations + * from being performed on the database, and interrupt any in-flight + * operations immediately. + */ + close(): void; + + /** + * Get a symbol that represents the versionstamp of the current atomic + * operation. This symbol can be used as the last part of a key in + * `.set()`, both directly on the `Kv` object and on an `AtomicOperation` + * object created from this `Kv` instance. + */ + commitVersionstamp(): symbol; + + [Symbol.dispose](): void; + } + + /** **UNSTABLE**: New API, yet to be vetted. + * + * Wrapper type for 64-bit unsigned integers for use as values in a + * {@linkcode Deno.Kv}. + * + * @category KV + */ + export class KvU64 { + /** Create a new `KvU64` instance from the given bigint value. If the value + * is signed or greater than 64-bits, an error will be thrown. */ + constructor(value: bigint); + /** The value of this unsigned 64-bit integer, represented as a bigint. */ + readonly value: bigint; + } + + /** + * A namespace containing runtime APIs available in Jupyter notebooks. + * + * When accessed outside of Jupyter notebook context an error will be thrown. + * + * @category Jupyter */ + export namespace jupyter { + /** @category Jupyter */ + export interface DisplayOptions { + raw?: boolean; + update?: boolean; + display_id?: string; + } + + /** @category Jupyter */ + type VegaObject = { + $schema: string; + [key: string]: unknown; + }; + + /** + * A collection of supported media types and data for Jupyter frontends. + * + * @category Jupyter + */ + export type MediaBundle = { + "text/plain"?: string; + "text/html"?: string; + "image/svg+xml"?: string; + "text/markdown"?: string; + "application/javascript"?: string; + + // Images (per Jupyter spec) must be base64 encoded. We could _allow_ + // accepting Uint8Array or ArrayBuffer within `display` calls, however we still + // must encode them for jupyter. + "image/png"?: string; // WISH: Uint8Array | ArrayBuffer + "image/jpeg"?: string; // WISH: Uint8Array | ArrayBuffer + "image/gif"?: string; // WISH: Uint8Array | ArrayBuffer + "application/pdf"?: string; // WISH: Uint8Array | ArrayBuffer + + // NOTE: all JSON types must be objects at the top level (no arrays, strings, or other primitives) + "application/json"?: object; + "application/geo+json"?: object; + "application/vdom.v1+json"?: object; + "application/vnd.plotly.v1+json"?: object; + "application/vnd.vega.v5+json"?: VegaObject; + "application/vnd.vegalite.v4+json"?: VegaObject; + "application/vnd.vegalite.v5+json"?: VegaObject; + + // Must support a catch all for custom media types / mimetypes + [key: string]: string | object | undefined; + }; + + /** @category Jupyter */ + export const $display: unique symbol; + + /** @category Jupyter */ + export type Displayable = { + [$display]: () => MediaBundle | Promise; + }; + + /** + * Display function for Jupyter Deno Kernel. + * Mimics the behavior of IPython's `display(obj, raw=True)` function to allow + * asynchronous displaying of objects in Jupyter. + * + * @param obj - The object to be displayed + * @param options - Display options with a default { raw: true } + * @category Jupyter + */ + export function display(obj: unknown, options?: DisplayOptions): void; + + /** + * Show Markdown in Jupyter frontends with a tagged template function. + * + * Takes a template string and returns a displayable object for Jupyter frontends. + * + * @example + * Create a Markdown view. + * + * ```typescript + * const { md } = Deno.jupyter; + * md`# Notebooks in TypeScript via Deno ![Deno logo](https://github.com/denoland.png?size=32) + * + * * TypeScript ${Deno.version.typescript} + * * V8 ${Deno.version.v8} + * * Deno ${Deno.version.deno} + * + * Interactive compute with Jupyter _built into Deno_! + * ` + * ``` + * + * @category Jupyter + */ + export function md( + strings: TemplateStringsArray, + ...values: unknown[] + ): Displayable; + + /** + * Show HTML in Jupyter frontends with a tagged template function. + * + * Takes a template string and returns a displayable object for Jupyter frontends. + * + * @example + * Create an HTML view. + * ```typescript + * const { html } = Deno.jupyter; + * html`

Hello, world!

` + * ``` + * + * @category Jupyter + */ + export function html( + strings: TemplateStringsArray, + ...values: unknown[] + ): Displayable; + + /** + * SVG Tagged Template Function. + * + * Takes a template string and returns a displayable object for Jupyter frontends. + * + * Example usage: + * + * svg` + * + * ` + * + * @category Jupyter + */ + export function svg( + strings: TemplateStringsArray, + ...values: unknown[] + ): Displayable; + + /** + * Format an object for displaying in Deno + * + * @param obj - The object to be displayed + * @returns MediaBundle + * + * @category Jupyter + */ + export function format(obj: unknown): MediaBundle; + + /** + * Broadcast a message on IO pub channel. + * + * ``` + * await Deno.jupyter.broadcast("display_data", { + * data: { "text/html": "Processing." }, + * metadata: {}, + * transient: { display_id: "progress" } + * }); + * + * await new Promise((resolve) => setTimeout(resolve, 500)); + * + * await Deno.jupyter.broadcast("update_display_data", { + * data: { "text/html": "Processing.." }, + * metadata: {}, + * transient: { display_id: "progress" } + * }); + * ``` + * + * @category Jupyter */ + export function broadcast( + msgType: string, + content: Record, + extra?: { + metadata?: Record; + buffers?: Uint8Array[]; + }, + ): Promise; + } + + /** @category Network */ + export interface NetAddr { + transport: "tcp" | "udp"; + hostname: string; + port: number; + } + + /** @category Network */ + export interface UnixAddr { + transport: "unix" | "unixpacket"; + path: string; + } + + /** @category Network */ + export type Addr = NetAddr | UnixAddr; + + /** A generic network listener for stream-oriented protocols. + * + * @category Network + */ + export interface Listener extends AsyncIterable, Disposable { + /** Waits for and resolves to the next connection to the `Listener`. */ + accept(): Promise; + /** Close closes the listener. Any pending accept promises will be rejected + * with errors. */ + close(): void; + /** Return the address of the `Listener`. */ + readonly addr: A; + + /** + * Return the rid of the `Listener`. + * + * @deprecated This will be removed in Deno 2.0. See the + * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide} + * for migration instructions. + */ + readonly rid: number; + + [Symbol.asyncIterator](): AsyncIterableIterator; + + /** + * Make the listener block the event loop from finishing. + * + * Note: the listener blocks the event loop from finishing by default. + * This method is only meaningful after `.unref()` is called. + */ + ref(): void; + + /** Make the listener not block the event loop from finishing. */ + unref(): void; + } + + /** Specialized listener that accepts TLS connections. + * + * @category Network + */ + export type TlsListener = Listener; + + /** Specialized listener that accepts TCP connections. + * + * @category Network + */ + export type TcpListener = Listener; + + /** Specialized listener that accepts Unix connections. + * + * @category Network + */ + export type UnixListener = Listener; + + /** @category Network */ + export interface Conn extends Reader, Writer, Closer, Disposable { + /** The local address of the connection. */ + readonly localAddr: A; + /** The remote address of the connection. */ + readonly remoteAddr: A; + /** + * The resource ID of the connection. + * + * @deprecated This will be removed in Deno 2.0. See the + * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide} + * for migration instructions. + */ + readonly rid: number; + /** Shuts down (`shutdown(2)`) the write side of the connection. Most + * callers should just use `close()`. */ + closeWrite(): Promise; + + /** Make the connection block the event loop from finishing. + * + * Note: the connection blocks the event loop from finishing by default. + * This method is only meaningful after `.unref()` is called. + */ + ref(): void; + /** Make the connection not block the event loop from finishing. */ + unref(): void; + + readonly readable: ReadableStream; + readonly writable: WritableStream; + } + + /** @category Network */ + export interface TlsHandshakeInfo { + /** + * Contains the ALPN protocol selected during negotiation with the server. + * If no ALPN protocol selected, returns `null`. + */ + alpnProtocol: string | null; + } + + /** @category Network */ + export interface TlsConn extends Conn { + /** Runs the client or server handshake protocol to completion if that has + * not happened yet. Calling this method is optional; the TLS handshake + * will be completed automatically as soon as data is sent or received. */ + handshake(): Promise; + /** + * The resource ID of the connection. + * + * @deprecated This will be removed in Deno 2.0. See the + * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide} + * for migration instructions. + */ + readonly rid: number; + } + + /** @category Network */ + export interface ListenOptions { + /** The port to listen on. */ + port: number; + /** A literal IP address or host name that can be resolved to an IP address. + * + * __Note about `0.0.0.0`__ While listening `0.0.0.0` works on all platforms, + * the browsers on Windows don't work with the address `0.0.0.0`. + * You should show the message like `server running on localhost:8080` instead of + * `server running on 0.0.0.0:8080` if your program supports Windows. + * + * @default {"0.0.0.0"} */ + hostname?: string; + } + + /** @category Network */ + // deno-lint-ignore no-empty-interface + export interface TcpListenOptions extends ListenOptions { + } + + /** Listen announces on the local transport address. + * + * ```ts + * const listener1 = Deno.listen({ port: 80 }) + * const listener2 = Deno.listen({ hostname: "192.0.2.1", port: 80 }) + * const listener3 = Deno.listen({ hostname: "[2001:db8::1]", port: 80 }); + * const listener4 = Deno.listen({ hostname: "golang.org", port: 80, transport: "tcp" }); + * ``` + * + * Requires `allow-net` permission. + * + * @tags allow-net + * @category Network + */ + export function listen( + options: TcpListenOptions & { transport?: "tcp" }, + ): TcpListener; + + /** Options which can be set when opening a Unix listener via + * {@linkcode Deno.listen} or {@linkcode Deno.listenDatagram}. + * + * @category Network + */ + export interface UnixListenOptions { + /** A path to the Unix Socket. */ + path: string; + } + + /** Listen announces on the local transport address. + * + * ```ts + * const listener = Deno.listen({ path: "/foo/bar.sock", transport: "unix" }) + * ``` + * + * Requires `allow-read` and `allow-write` permission. + * + * @tags allow-read, allow-write + * @category Network + */ + // deno-lint-ignore adjacent-overload-signatures + export function listen( + options: UnixListenOptions & { transport: "unix" }, + ): UnixListener; + + /** Provides TLS certified keys, ie: a key that has been certified by a trusted certificate authority. + * A certified key generally consists of a private key and certificate part. + * + * @category Network + */ + export type TlsCertifiedKeyOptions = + | TlsCertifiedKeyPem + | TlsCertifiedKeyFromFile + | TlsCertifiedKeyConnectTls; + + /** + * Provides certified key material from strings. The key material is provided in + * `PEM`-format (Privacy Enhanced Mail, https://www.rfc-editor.org/rfc/rfc1422) which can be identified by having + * `-----BEGIN-----` and `-----END-----` markers at the beginning and end of the strings. This type of key is not compatible + * with `DER`-format keys which are binary. + * + * Deno supports RSA, EC, and PKCS8-format keys. + * + * ```ts + * const key = { + * key: "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n", + * cert: "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n" } + * }; + * ``` + * + * @category Network + */ + export interface TlsCertifiedKeyPem { + /** The format of this key material, which must be PEM. */ + keyFormat?: "pem"; + /** Private key in `PEM` format. RSA, EC, and PKCS8-format keys are supported. */ + key: string; + /** Certificate chain in `PEM` format. */ + cert: string; + } + + /** + * @deprecated This will be removed in Deno 2.0. See the + * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide} + * for migration instructions. + * + * @category Network + */ + export interface TlsCertifiedKeyFromFile { + /** Path to a file containing a PEM formatted CA certificate. Requires + * `--allow-read`. + * + * @tags allow-read + * @deprecated This will be removed in Deno 2.0. See the + * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide} + * for migration instructions. + */ + certFile: string; + /** Path to a file containing a private key file. Requires `--allow-read`. + * + * @tags allow-read + * @deprecated This will be removed in Deno 2.0. See the + * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide} + * for migration instructions. + */ + keyFile: string; + } + + /** + * @deprecated This will be removed in Deno 2.0. See the + * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide} + * for migration instructions. + * + * @category Network + */ + export interface TlsCertifiedKeyConnectTls { + /** + * Certificate chain in `PEM` format. + * + * @deprecated This will be removed in Deno 2.0. See the + * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide} + * for migration instructions. + */ + certChain: string; + /** + * Private key in `PEM` format. RSA, EC, and PKCS8-format keys are supported. + * + * @deprecated This will be removed in Deno 2.0. See the + * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide} + * for migration instructions. + */ + privateKey: string; + } + + /** @category Network */ + export interface ListenTlsOptions extends TcpListenOptions { + transport?: "tcp"; + + /** Application-Layer Protocol Negotiation (ALPN) protocols to announce to + * the client. If not specified, no ALPN extension will be included in the + * TLS handshake. + */ + alpnProtocols?: string[]; + } + + /** Listen announces on the local transport address over TLS (transport layer + * security). + * + * ```ts + * using listener = Deno.listenTls({ + * port: 443, + * cert: Deno.readTextFileSync("./server.crt"), + * key: Deno.readTextFileSync("./server.key"), + * }); + * ``` + * + * Requires `allow-net` permission. + * + * @tags allow-net + * @category Network + */ + export function listenTls( + options: ListenTlsOptions & TlsCertifiedKeyOptions, + ): TlsListener; + + /** @category Network */ + export interface ConnectOptions { + /** The port to connect to. */ + port: number; + /** A literal IP address or host name that can be resolved to an IP address. + * If not specified, + * + * @default {"127.0.0.1"} */ + hostname?: string; + transport?: "tcp"; + } + + /** + * Connects to the hostname (default is "127.0.0.1") and port on the named + * transport (default is "tcp"), and resolves to the connection (`Conn`). + * + * ```ts + * const conn1 = await Deno.connect({ port: 80 }); + * const conn2 = await Deno.connect({ hostname: "192.0.2.1", port: 80 }); + * const conn3 = await Deno.connect({ hostname: "[2001:db8::1]", port: 80 }); + * const conn4 = await Deno.connect({ hostname: "golang.org", port: 80, transport: "tcp" }); + * ``` + * + * Requires `allow-net` permission for "tcp". + * + * @tags allow-net + * @category Network + */ + export function connect(options: ConnectOptions): Promise; + + /** @category Network */ + export interface TcpConn extends Conn { + /** + * Enable/disable the use of Nagle's algorithm. + * + * @param [noDelay=true] + */ + setNoDelay(noDelay?: boolean): void; + /** Enable/disable keep-alive functionality. */ + setKeepAlive(keepAlive?: boolean): void; + /** + * The resource ID of the connection. + * + * @deprecated This will be removed in Deno 2.0. See the + * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide} + * for migration instructions. + */ + readonly rid: number; + } + + /** @category Network */ + export interface UnixConnectOptions { + transport: "unix"; + path: string; + } + + /** @category Network */ + export interface UnixConn extends Conn { + /** + * The resource ID of the connection. + * + * @deprecated This will be removed in Deno 2.0. See the + * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide} + * for migration instructions. + */ + readonly rid: number; + } + + /** Connects to the hostname (default is "127.0.0.1") and port on the named + * transport (default is "tcp"), and resolves to the connection (`Conn`). + * + * ```ts + * const conn1 = await Deno.connect({ port: 80 }); + * const conn2 = await Deno.connect({ hostname: "192.0.2.1", port: 80 }); + * const conn3 = await Deno.connect({ hostname: "[2001:db8::1]", port: 80 }); + * const conn4 = await Deno.connect({ hostname: "golang.org", port: 80, transport: "tcp" }); + * const conn5 = await Deno.connect({ path: "/foo/bar.sock", transport: "unix" }); + * ``` + * + * Requires `allow-net` permission for "tcp" and `allow-read` for "unix". + * + * @tags allow-net, allow-read + * @category Network + */ + // deno-lint-ignore adjacent-overload-signatures + export function connect(options: UnixConnectOptions): Promise; + + /** @category Network */ + export interface ConnectTlsOptions { + /** The port to connect to. */ + port: number; + /** A literal IP address or host name that can be resolved to an IP address. + * + * @default {"127.0.0.1"} */ + hostname?: string; + /** Path to a file containing a PEM formatted list of root certificates that will + * be used in addition to the default root certificates to verify the peer's certificate. Requires + * `--allow-read`. + * + * @tags allow-read + * @deprecated This will be removed in Deno 2.0. See the + * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide} + * for migration instructions. + */ + certFile?: string; + /** A list of root certificates that will be used in addition to the + * default root certificates to verify the peer's certificate. + * + * Must be in PEM format. */ + caCerts?: string[]; + /** Application-Layer Protocol Negotiation (ALPN) protocols supported by + * the client. If not specified, no ALPN extension will be included in the + * TLS handshake. + */ + alpnProtocols?: string[]; + } + + /** Establishes a secure connection over TLS (transport layer security) using + * an optional cert file, hostname (default is "127.0.0.1") and port. The + * cert file is optional and if not included Mozilla's root certificates will + * be used (see also https://github.com/ctz/webpki-roots for specifics) + * + * ```ts + * const caCert = await Deno.readTextFile("./certs/my_custom_root_CA.pem"); + * const conn1 = await Deno.connectTls({ port: 80 }); + * const conn2 = await Deno.connectTls({ caCerts: [caCert], hostname: "192.0.2.1", port: 80 }); + * const conn3 = await Deno.connectTls({ hostname: "[2001:db8::1]", port: 80 }); + * const conn4 = await Deno.connectTls({ caCerts: [caCert], hostname: "golang.org", port: 80}); + * ``` + * + * Requires `allow-net` permission. + * + * @tags allow-net + * @category Network + */ + export function connectTls(options: ConnectTlsOptions): Promise; + + /** Establishes a secure connection over TLS (transport layer security) using + * an optional cert file, client certificate, hostname (default is "127.0.0.1") and + * port. The cert file is optional and if not included Mozilla's root certificates will + * be used (see also https://github.com/ctz/webpki-roots for specifics) + * + * ```ts + * const caCert = await Deno.readTextFile("./certs/my_custom_root_CA.pem"); + * const key = "----BEGIN PRIVATE KEY----..."; + * const cert = "----BEGIN CERTIFICATE----..."; + * const conn1 = await Deno.connectTls({ port: 80, key, cert }); + * const conn2 = await Deno.connectTls({ caCerts: [caCert], hostname: "192.0.2.1", port: 80, key, cert }); + * const conn3 = await Deno.connectTls({ hostname: "[2001:db8::1]", port: 80, key, cert }); + * const conn4 = await Deno.connectTls({ caCerts: [caCert], hostname: "golang.org", port: 80, key, cert }); + * ``` + * + * Requires `allow-net` permission. + * + * @tags allow-net + * @category Network + */ + export function connectTls( + options: ConnectTlsOptions & TlsCertifiedKeyOptions, + ): Promise; + + /** @category Network */ + export interface StartTlsOptions { + /** A literal IP address or host name that can be resolved to an IP address. + * + * @default {"127.0.0.1"} */ + hostname?: string; + /** A list of root certificates that will be used in addition to the + * default root certificates to verify the peer's certificate. + * + * Must be in PEM format. */ + caCerts?: string[]; + /** Application-Layer Protocol Negotiation (ALPN) protocols to announce to + * the client. If not specified, no ALPN extension will be included in the + * TLS handshake. + */ + alpnProtocols?: string[]; + } + + /** Start TLS handshake from an existing connection using an optional list of + * CA certificates, and hostname (default is "127.0.0.1"). Specifying CA certs + * is optional. By default the configured root certificates are used. Using + * this function requires that the other end of the connection is prepared for + * a TLS handshake. + * + * Note that this function *consumes* the TCP connection passed to it, thus the + * original TCP connection will be unusable after calling this. Additionally, + * you need to ensure that the TCP connection is not being used elsewhere when + * calling this function in order for the TCP connection to be consumed properly. + * For instance, if there is a `Promise` that is waiting for read operation on + * the TCP connection to complete, it is considered that the TCP connection is + * being used elsewhere. In such a case, this function will fail. + * + * ```ts + * const conn = await Deno.connect({ port: 80, hostname: "127.0.0.1" }); + * const caCert = await Deno.readTextFile("./certs/my_custom_root_CA.pem"); + * // `conn` becomes unusable after calling `Deno.startTls` + * const tlsConn = await Deno.startTls(conn, { caCerts: [caCert], hostname: "localhost" }); + * ``` + * + * Requires `allow-net` permission. + * + * @tags allow-net + * @category Network + */ + export function startTls( + conn: TcpConn, + options?: StartTlsOptions, + ): Promise; + + /** Shutdown socket send operations. + * + * Matches behavior of POSIX shutdown(3). + * + * ```ts + * const listener = Deno.listen({ port: 80 }); + * const conn = await listener.accept(); + * Deno.shutdown(conn.rid); + * ``` + * + * @deprecated This will be removed in Deno 2.0. See the + * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide} + * for migration instructions. + * + * @category Network + */ + export function shutdown(rid: number): Promise; +} From 341e8e9d3e620ac3051282ddad095a79ef68ea84 Mon Sep 17 00:00:00 2001 From: alina sireneva Date: Mon, 29 Apr 2024 16:42:58 +0300 Subject: [PATCH 04/10] docs: fixed some namings --- packages/bun/src/client.ts | 2 +- packages/deno/README.md | 2 +- packages/deno/src/client.ts | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/packages/bun/src/client.ts b/packages/bun/src/client.ts index ee3f66f2..7ab5e88d 100644 --- a/packages/bun/src/client.ts +++ b/packages/bun/src/client.ts @@ -56,7 +56,7 @@ export class BaseTelegramClient extends BaseTelegramClientBase { } /** - * Telegram client for use in Node.js + * Telegram client for use in Bun */ export class TelegramClient extends TelegramClientBase { constructor(opts: TelegramClientOptions) { diff --git a/packages/deno/README.md b/packages/deno/README.md index 2d2baff9..8c3dec62 100644 --- a/packages/deno/README.md +++ b/packages/deno/README.md @@ -1,4 +1,4 @@ -# @mtcute/bun +# @mtcute/deno 📖 [API Reference](https://ref.mtcute.dev/modules/_mtcute_deno.html) diff --git a/packages/deno/src/client.ts b/packages/deno/src/client.ts index e36e1b21..75040a49 100644 --- a/packages/deno/src/client.ts +++ b/packages/deno/src/client.ts @@ -56,7 +56,7 @@ export class BaseTelegramClient extends BaseTelegramClientBase { } /** - * Telegram client for use in Node.js + * Telegram client for use in Deno */ export class TelegramClient extends TelegramClientBase { constructor(opts: TelegramClientOptions) { From 33515169ff741d8027160c3b0a81a25c4055d2ff Mon Sep 17 00:00:00 2001 From: alina sireneva Date: Mon, 29 Apr 2024 17:44:00 +0300 Subject: [PATCH 05/10] fix(deno): lazily import @db/sqlite --- packages/deno/src/sqlite/driver.ts | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/packages/deno/src/sqlite/driver.ts b/packages/deno/src/sqlite/driver.ts index e983f027..fd58c458 100644 --- a/packages/deno/src/sqlite/driver.ts +++ b/packages/deno/src/sqlite/driver.ts @@ -1,6 +1,6 @@ import { BaseSqliteStorageDriver, ISqliteDatabase } from '@mtcute/core' -import { Database } from '@db/sqlite' +let Database: typeof import('@db/sqlite').Database export interface SqliteStorageDriverOptions { /** @@ -24,6 +24,15 @@ export class SqliteStorageDriver extends BaseSqliteStorageDriver { super() } + async _load(): Promise { + if (!Database) { + // we load this lazily to avoid loading ffi if it's not needed, + // in case the user doesn't use sqlite storage + Database = (await import('@db/sqlite')).Database + } + super._load() + } + _createDatabase(): ISqliteDatabase { const db = new Database(this.filename, { int64: true, From dc56deb08a3f6c689dedc5b4faef2855d48732fa Mon Sep 17 00:00:00 2001 From: alina sireneva Date: Mon, 29 Apr 2024 18:09:56 +0300 Subject: [PATCH 06/10] fix: check for listener count before emitting error --- packages/bun/src/utils/tcp.ts | 11 +++++++++-- packages/deno/src/utils/tcp.ts | 5 ++++- packages/node/src/utils/tcp.ts | 5 ++++- 3 files changed, 17 insertions(+), 4 deletions(-) diff --git a/packages/bun/src/utils/tcp.ts b/packages/bun/src/utils/tcp.ts index 5bfcc7b5..e8141d8b 100644 --- a/packages/bun/src/utils/tcp.ts +++ b/packages/bun/src/utils/tcp.ts @@ -91,7 +91,10 @@ export abstract class BaseTcpTransport extends EventEmitter implements ITelegram handleError(socket: unknown, error: Error): void { this.log.error('error: %s', error.stack) - this.emit('error', error) + + if (this.listenerCount('error') > 0) { + this.emit('error', error) + } } handleConnect(socket: Socket): void { @@ -109,7 +112,11 @@ export abstract class BaseTcpTransport extends EventEmitter implements ITelegram this.emit('ready') } }) - .catch((err) => this.emit('error', err)) + .catch((err) => { + if (this.listenerCount('error') > 0) { + this.emit('error', err) + } + }) } async send(bytes: Uint8Array): Promise { diff --git a/packages/deno/src/utils/tcp.ts b/packages/deno/src/utils/tcp.ts index 848ded1e..f1a3faab 100644 --- a/packages/deno/src/utils/tcp.ts +++ b/packages/deno/src/utils/tcp.ts @@ -87,7 +87,10 @@ export abstract class BaseTcpTransport extends EventEmitter implements ITelegram handleError(error: unknown): void { this.log.error('error: %s', error) - this.emit('error', error) + + if (this.listenerCount('error') > 0) { + this.emit('error', error) + } } async handleConnect(socket: Deno.TcpConn): Promise { diff --git a/packages/node/src/utils/tcp.ts b/packages/node/src/utils/tcp.ts index 3fadbeb2..56d952ba 100644 --- a/packages/node/src/utils/tcp.ts +++ b/packages/node/src/utils/tcp.ts @@ -84,7 +84,10 @@ export abstract class BaseTcpTransport extends EventEmitter implements ITelegram handleError(error: Error): void { this.log.error('error: %s', error.stack) - this.emit('error', error) + + if (this.listenerCount('error') > 0) { + this.emit('error', error) + } } handleConnect(): void { From ac398e657a69bc03ed7e98a61d6b323495511d95 Mon Sep 17 00:00:00 2001 From: alina sireneva Date: Mon, 29 Apr 2024 18:10:43 +0300 Subject: [PATCH 07/10] test(e2e-deno): use @mtcute/deno in tests --- e2e/deno/cli.sh | 4 ++-- e2e/deno/deno.json | 3 ++- e2e/deno/utils.ts | 8 ++++---- packages/deno/src/sqlite/sqlite.test.ts | 3 +++ packages/node/src/utils/tcp.test.ts | 5 +++-- 5 files changed, 14 insertions(+), 9 deletions(-) diff --git a/e2e/deno/cli.sh b/e2e/deno/cli.sh index e314f000..07c64d6a 100755 --- a/e2e/deno/cli.sh +++ b/e2e/deno/cli.sh @@ -45,7 +45,7 @@ case "$method" in source .env fi - if [ -n "$DOCKER" ]; then + if [ ! -z ${DOCKER+x} ]; then # running behind a socat proxy seems to fix some of the docker networking issues (thx kamillaova) socat TCP-LISTEN:4873,fork,reuseaddr TCP4:jsr:80 & socat_pid=$! @@ -54,7 +54,7 @@ case "$method" in fi export JSR_URL=http://localhost:4873 - if [ -z "$@" ]; then + if [ $# -eq 0 ]; then deno test -A tests/**/*.ts else deno test -A $@ diff --git a/e2e/deno/deno.json b/e2e/deno/deno.json index f1651f62..71f4e17a 100644 --- a/e2e/deno/deno.json +++ b/e2e/deno/deno.json @@ -4,6 +4,7 @@ "@mtcute/wasm": "jsr:@mtcute/wasm@*", "@mtcute/tl": "jsr:@mtcute/tl@*", "@mtcute/tl-runtime": "jsr:@mtcute/tl-runtime@*", - "@mtcute/core": "jsr:@mtcute/core@*" + "@mtcute/core": "jsr:@mtcute/core@*", + "@mtcute/deno": "jsr:@mtcute/deno@*" } } \ No newline at end of file diff --git a/e2e/deno/utils.ts b/e2e/deno/utils.ts index 25711aa8..8714b990 100644 --- a/e2e/deno/utils.ts +++ b/e2e/deno/utils.ts @@ -1,7 +1,7 @@ import { MaybePromise, MemoryStorage } from '@mtcute/core' import { setPlatform } from '@mtcute/core/platform.js' import { LogManager, sleep } from '@mtcute/core/utils.js' -import { WebCryptoProvider, WebPlatform, WebSocketTransport } from '@mtcute/web' +import { DenoCryptoProvider, DenoPlatform, TcpTransport } from '@mtcute/deno' export const getApiParams = (storage?: string) => { if (storage) throw new Error('unsupported yet') @@ -10,7 +10,7 @@ export const getApiParams = (storage?: string) => { throw new Error('API_ID and API_HASH env variables must be set') } - setPlatform(new WebPlatform()) + setPlatform(new DenoPlatform()) return { apiId: parseInt(Deno.env.get('API_ID')!), @@ -18,8 +18,8 @@ export const getApiParams = (storage?: string) => { testMode: true, storage: new MemoryStorage(), logLevel: LogManager.VERBOSE, - transport: () => new WebSocketTransport(), - crypto: new WebCryptoProvider(), + transport: () => new TcpTransport(), + crypto: new DenoCryptoProvider(), } } diff --git a/packages/deno/src/sqlite/sqlite.test.ts b/packages/deno/src/sqlite/sqlite.test.ts index 0a9d9924..499fd46d 100644 --- a/packages/deno/src/sqlite/sqlite.test.ts +++ b/packages/deno/src/sqlite/sqlite.test.ts @@ -9,6 +9,9 @@ import { } from '@mtcute/test' if (import.meta.env.TEST_ENV === 'deno') { + // load sqlite in advance so test runner doesn't complain about us leaking the library + // (it's not on us, @db/sqlite doesn't provide an api to unload the library) + await import('@db/sqlite') const { SqliteStorage } = await import('./index.js') describe('SqliteStorage', () => { diff --git a/packages/node/src/utils/tcp.test.ts b/packages/node/src/utils/tcp.test.ts index 684e3cf4..88b71e3e 100644 --- a/packages/node/src/utils/tcp.test.ts +++ b/packages/node/src/utils/tcp.test.ts @@ -134,7 +134,8 @@ if (import.meta.env.TEST_ENV === 'node') { it('should propagate errors', async () => { const t = await create() - const spyEmit = vi.spyOn(t, 'emit').mockImplementation(() => true) + const spyEmit = vi.fn() + t.on('error', spyEmit) t.connect(defaultProductionDc.main, false) await vi.waitFor(() => expect(t.state()).toEqual(TransportState.Ready)) @@ -147,7 +148,7 @@ if (import.meta.env.TEST_ENV === 'node') { ] onErrorCall[1](new Error('test error')) - expect(spyEmit).toHaveBeenCalledWith('error', new Error('test error')) + expect(spyEmit).toHaveBeenCalledWith(new Error('test error')) }) }) } else { From 3553abc5345c00f9aa2da5995806dc81ee0635df Mon Sep 17 00:00:00 2001 From: alina sireneva Date: Tue, 30 Apr 2024 04:20:56 +0300 Subject: [PATCH 08/10] build: use @teidesu/deno-types for deno typings --- package.json | 3 +- pnpm-lock.yaml | 7 + scripts/install-deno-dts.mjs | 16 - scripts/lib.deno.d.ts | 9038 ---------------------------------- tsconfig.json | 2 +- 5 files changed, 10 insertions(+), 9056 deletions(-) delete mode 100644 scripts/install-deno-dts.mjs delete mode 100644 scripts/lib.deno.d.ts diff --git a/package.json b/package.json index c77fef8c..a336e2fb 100644 --- a/package.json +++ b/package.json @@ -10,7 +10,7 @@ ], "scripts": { "prepare": "husky install .config/husky", - "postinstall": "node scripts/validate-deps-versions.mjs && node scripts/install-deno-dts.mjs && node scripts/remove-jsr-sourcefiles.mjs", + "postinstall": "node scripts/validate-deps-versions.mjs && node scripts/remove-jsr-sourcefiles.mjs", "test": "pnpm run -r test && vitest --config .config/vite.mts run", "test:dev": "vitest --config .config/vite.mts watch", "test:ui": "vitest --config .config/vite.mts --ui", @@ -37,6 +37,7 @@ "@commitlint/config-conventional": "17.6.5", "@teidesu/slow-types-compiler": "1.1.0", "@types/node": "20.10.0", + "@types/deno": "npm:@teidesu/deno-types@1.42.4", "@types/ws": "8.5.4", "@typescript-eslint/eslint-plugin": "6.4.0", "@typescript-eslint/parser": "6.4.0", diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index f4902c33..5fb4187d 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -21,6 +21,9 @@ importers: '@teidesu/slow-types-compiler': specifier: 1.1.0 version: 1.1.0(typescript@5.4.3) + '@types/deno': + specifier: npm:@teidesu/deno-types@1.42.4 + version: /@teidesu/deno-types@1.42.4 '@types/node': specifier: 20.10.0 version: 20.10.0 @@ -1467,6 +1470,10 @@ packages: /@sinclair/typebox@0.27.8: resolution: {integrity: sha512-+Fj43pSMwJs4KRrH/938Uf+uAELIgVBmQzg/q1YG10djyfA3TnrU8N8XzqCh/okZdszqBQTZf96idMfE5lnwTA==} + /@teidesu/deno-types@1.42.4: + resolution: {integrity: sha512-MMDkfWOsfedYWy+aPK4fAYyZfrBsY6+DeC7DGg6eESzh90zxuf1fSvXRsY8y09Hh4mm04tAf1632S2/JLaTXQg==} + dev: true + /@teidesu/slow-types-compiler@1.1.0(typescript@5.4.3): resolution: {integrity: sha512-+WUHSKh56B32Jk5aJgXf07E2EOkMX1yilvgKLKBCJPFAJZ4xeo1U5aDu3wwHX3lrFl7AiVGXUP+FfuHy8X43BA==} hasBin: true diff --git a/scripts/install-deno-dts.mjs b/scripts/install-deno-dts.mjs deleted file mode 100644 index 514ee596..00000000 --- a/scripts/install-deno-dts.mjs +++ /dev/null @@ -1,16 +0,0 @@ -import * as fs from 'fs/promises' -import { dirname } from 'path' -import { fileURLToPath } from 'url' - -const LIB_SOURCE = fileURLToPath(new URL('./lib.deno.d.ts', import.meta.url)) -const LIB_TARGET = fileURLToPath(new URL('../node_modules/@types/deno/index.d.ts', import.meta.url)) - -await fs.mkdir(dirname(LIB_TARGET), { recursive: true }) - -if (await fs.stat(LIB_TARGET).catch(() => null)) { - await fs.unlink(LIB_TARGET) -} - -await fs.symlink(LIB_SOURCE, LIB_TARGET) - -console.log('lib.deno.d.ts linked') diff --git a/scripts/lib.deno.d.ts b/scripts/lib.deno.d.ts deleted file mode 100644 index 5145934a..00000000 --- a/scripts/lib.deno.d.ts +++ /dev/null @@ -1,9038 +0,0 @@ -/* eslint-disable */ -// Copyright 2018-2024 the Deno authors. All rights reserved. MIT license. - -// this file is a stipped down version of lib.deno.d.ts from 1.42.4 -// original lib.deno.d.ts re-defines web apis, but we want to avoid interfering with the rest of the typings -// and use typescript's lib.dom.d.ts instead - -/** The global namespace where Deno specific, non-standard APIs are located. */ -declare namespace Deno { - /** A set of error constructors that are raised by Deno APIs. - * - * Can be used to provide more specific handling of failures within code - * which is using Deno APIs. For example, handling attempting to open a file - * which does not exist: - * - * ```ts - * try { - * const file = await Deno.open("./some/file.txt"); - * } catch (error) { - * if (error instanceof Deno.errors.NotFound) { - * console.error("the file was not found"); - * } else { - * // otherwise re-throw - * throw error; - * } - * } - * ``` - * - * @category Errors - */ - export namespace errors { - /** - * Raised when the underlying operating system indicates that the file - * was not found. - * - * @category Errors */ - export class NotFound extends Error {} - /** - * Raised when the underlying operating system indicates the current user - * which the Deno process is running under does not have the appropriate - * permissions to a file or resource, or the user _did not_ provide required - * `--allow-*` flag. - * - * @category Errors */ - export class PermissionDenied extends Error {} - /** - * Raised when the underlying operating system reports that a connection to - * a resource is refused. - * - * @category Errors */ - export class ConnectionRefused extends Error {} - /** - * Raised when the underlying operating system reports that a connection has - * been reset. With network servers, it can be a _normal_ occurrence where a - * client will abort a connection instead of properly shutting it down. - * - * @category Errors */ - export class ConnectionReset extends Error {} - /** - * Raised when the underlying operating system reports an `ECONNABORTED` - * error. - * - * @category Errors */ - export class ConnectionAborted extends Error {} - /** - * Raised when the underlying operating system reports an `ENOTCONN` error. - * - * @category Errors */ - export class NotConnected extends Error {} - /** - * Raised when attempting to open a server listener on an address and port - * that already has a listener. - * - * @category Errors */ - export class AddrInUse extends Error {} - /** - * Raised when the underlying operating system reports an `EADDRNOTAVAIL` - * error. - * - * @category Errors */ - export class AddrNotAvailable extends Error {} - /** - * Raised when trying to write to a resource and a broken pipe error occurs. - * This can happen when trying to write directly to `stdout` or `stderr` - * and the operating system is unable to pipe the output for a reason - * external to the Deno runtime. - * - * @category Errors */ - export class BrokenPipe extends Error {} - /** - * Raised when trying to create a resource, like a file, that already - * exits. - * - * @category Errors */ - export class AlreadyExists extends Error {} - /** - * Raised when an operation to returns data that is invalid for the - * operation being performed. - * - * @category Errors */ - export class InvalidData extends Error {} - /** - * Raised when the underlying operating system reports that an I/O operation - * has timed out (`ETIMEDOUT`). - * - * @category Errors */ - export class TimedOut extends Error {} - /** - * Raised when the underlying operating system reports an `EINTR` error. In - * many cases, this underlying IO error will be handled internally within - * Deno, or result in an @{link BadResource} error instead. - * - * @category Errors */ - export class Interrupted extends Error {} - /** - * Raised when the underlying operating system would need to block to - * complete but an asynchronous (non-blocking) API is used. - * - * @category Errors */ - export class WouldBlock extends Error {} - /** - * Raised when expecting to write to a IO buffer resulted in zero bytes - * being written. - * - * @category Errors */ - export class WriteZero extends Error {} - /** - * Raised when attempting to read bytes from a resource, but the EOF was - * unexpectedly encountered. - * - * @category Errors */ - export class UnexpectedEof extends Error {} - /** - * The underlying IO resource is invalid or closed, and so the operation - * could not be performed. - * - * @category Errors */ - export class BadResource extends Error {} - /** - * Raised in situations where when attempting to load a dynamic import, - * too many redirects were encountered. - * - * @category Errors */ - export class Http extends Error {} - /** - * Raised when the underlying IO resource is not available because it is - * being awaited on in another block of code. - * - * @category Errors */ - export class Busy extends Error {} - /** - * Raised when the underlying Deno API is asked to perform a function that - * is not currently supported. - * - * @category Errors */ - export class NotSupported extends Error {} - /** - * Raised when too many symbolic links were encountered when resolving the - * filename. - * - * @category Errors */ - export class FilesystemLoop extends Error {} - /** - * Raised when trying to open, create or write to a directory. - * - * @category Errors */ - export class IsADirectory extends Error {} - /** - * Raised when performing a socket operation but the remote host is - * not reachable. - * - * @category Errors */ - export class NetworkUnreachable extends Error {} - /** - * Raised when trying to perform an operation on a path that is not a - * directory, when directory is required. - * - * @category Errors */ - export class NotADirectory extends Error {} - } - - /** The current process ID of this instance of the Deno CLI. - * - * ```ts - * console.log(Deno.pid); - * ``` - * - * @category Runtime Environment - */ - export const pid: number; - - /** - * The process ID of parent process of this instance of the Deno CLI. - * - * ```ts - * console.log(Deno.ppid); - * ``` - * - * @category Runtime Environment - */ - export const ppid: number; - - /** @category Runtime Environment */ - export interface MemoryUsage { - /** The number of bytes of the current Deno's process resident set size, - * which is the amount of memory occupied in main memory (RAM). */ - rss: number; - /** The total size of the heap for V8, in bytes. */ - heapTotal: number; - /** The amount of the heap used for V8, in bytes. */ - heapUsed: number; - /** Memory, in bytes, associated with JavaScript objects outside of the - * JavaScript isolate. */ - external: number; - } - - /** - * Returns an object describing the memory usage of the Deno process and the - * V8 subsystem measured in bytes. - * - * @category Runtime Environment - */ - export function memoryUsage(): MemoryUsage; - - /** - * Get the `hostname` of the machine the Deno process is running on. - * - * ```ts - * console.log(Deno.hostname()); - * ``` - * - * Requires `allow-sys` permission. - * - * @tags allow-sys - * @category Runtime Environment - */ - export function hostname(): string; - - /** - * Returns an array containing the 1, 5, and 15 minute load averages. The - * load average is a measure of CPU and IO utilization of the last one, five, - * and 15 minute periods expressed as a fractional number. Zero means there - * is no load. On Windows, the three values are always the same and represent - * the current load, not the 1, 5 and 15 minute load averages. - * - * ```ts - * console.log(Deno.loadavg()); // e.g. [ 0.71, 0.44, 0.44 ] - * ``` - * - * Requires `allow-sys` permission. - * - * On Windows there is no API available to retrieve this information and this method returns `[ 0, 0, 0 ]`. - * - * @tags allow-sys - * @category Observability - */ - export function loadavg(): number[]; - - /** - * The information for a network interface returned from a call to - * {@linkcode Deno.networkInterfaces}. - * - * @category Network - */ - export interface NetworkInterfaceInfo { - /** The network interface name. */ - name: string; - /** The IP protocol version. */ - family: "IPv4" | "IPv6"; - /** The IP address bound to the interface. */ - address: string; - /** The netmask applied to the interface. */ - netmask: string; - /** The IPv6 scope id or `null`. */ - scopeid: number | null; - /** The CIDR range. */ - cidr: string; - /** The MAC address. */ - mac: string; - } - - /** - * Returns an array of the network interface information. - * - * ```ts - * console.log(Deno.networkInterfaces()); - * ``` - * - * Requires `allow-sys` permission. - * - * @tags allow-sys - * @category Network - */ - export function networkInterfaces(): NetworkInterfaceInfo[]; - - /** - * Displays the total amount of free and used physical and swap memory in the - * system, as well as the buffers and caches used by the kernel. - * - * This is similar to the `free` command in Linux - * - * ```ts - * console.log(Deno.systemMemoryInfo()); - * ``` - * - * Requires `allow-sys` permission. - * - * @tags allow-sys - * @category Runtime Environment - */ - export function systemMemoryInfo(): SystemMemoryInfo; - - /** - * Information returned from a call to {@linkcode Deno.systemMemoryInfo}. - * - * @category Runtime Environment - */ - export interface SystemMemoryInfo { - /** Total installed memory in bytes. */ - total: number; - /** Unused memory in bytes. */ - free: number; - /** Estimation of how much memory, in bytes, is available for starting new - * applications, without swapping. Unlike the data provided by the cache or - * free fields, this field takes into account page cache and also that not - * all reclaimable memory will be reclaimed due to items being in use. - */ - available: number; - /** Memory used by kernel buffers. */ - buffers: number; - /** Memory used by the page cache and slabs. */ - cached: number; - /** Total swap memory. */ - swapTotal: number; - /** Unused swap memory. */ - swapFree: number; - } - - /** Reflects the `NO_COLOR` environment variable at program start. - * - * When the value is `true`, the Deno CLI will attempt to not send color codes - * to `stderr` or `stdout` and other command line programs should also attempt - * to respect this value. - * - * See: https://no-color.org/ - * - * @category Runtime Environment - */ - export const noColor: boolean; - - /** - * Returns the release version of the Operating System. - * - * ```ts - * console.log(Deno.osRelease()); - * ``` - * - * Requires `allow-sys` permission. - * Under consideration to possibly move to Deno.build or Deno.versions and if - * it should depend sys-info, which may not be desirable. - * - * @tags allow-sys - * @category Runtime Environment - */ - export function osRelease(): string; - - /** - * Returns the Operating System uptime in number of seconds. - * - * ```ts - * console.log(Deno.osUptime()); - * ``` - * - * Requires `allow-sys` permission. - * - * @tags allow-sys - * @category Runtime Environment - */ - export function osUptime(): number; - - /** - * Options which define the permissions within a test or worker context. - * - * `"inherit"` ensures that all permissions of the parent process will be - * applied to the test context. `"none"` ensures the test context has no - * permissions. A `PermissionOptionsObject` provides a more specific - * set of permissions to the test context. - * - * @category Permissions */ - export type PermissionOptions = - | "inherit" - | "none" - | PermissionOptionsObject; - - /** - * A set of options which can define the permissions within a test or worker - * context at a highly specific level. - * - * @category Permissions */ - export interface PermissionOptionsObject { - /** Specifies if the `env` permission should be requested or revoked. - * If set to `"inherit"`, the current `env` permission will be inherited. - * If set to `true`, the global `env` permission will be requested. - * If set to `false`, the global `env` permission will be revoked. - * - * @default {false} - */ - env?: "inherit" | boolean | string[]; - - /** Specifies if the `sys` permission should be requested or revoked. - * If set to `"inherit"`, the current `sys` permission will be inherited. - * If set to `true`, the global `sys` permission will be requested. - * If set to `false`, the global `sys` permission will be revoked. - * - * @default {false} - */ - sys?: "inherit" | boolean | string[]; - - /** Specifies if the `hrtime` permission should be requested or revoked. - * If set to `"inherit"`, the current `hrtime` permission will be inherited. - * If set to `true`, the global `hrtime` permission will be requested. - * If set to `false`, the global `hrtime` permission will be revoked. - * - * @default {false} - */ - hrtime?: "inherit" | boolean; - - /** Specifies if the `net` permission should be requested or revoked. - * if set to `"inherit"`, the current `net` permission will be inherited. - * if set to `true`, the global `net` permission will be requested. - * if set to `false`, the global `net` permission will be revoked. - * if set to `string[]`, the `net` permission will be requested with the - * specified host strings with the format `"[:]`. - * - * @default {false} - * - * Examples: - * - * ```ts - * import { assertEquals } from "jsr:@std/assert"; - * - * Deno.test({ - * name: "inherit", - * permissions: { - * net: "inherit", - * }, - * async fn() { - * const status = await Deno.permissions.query({ name: "net" }) - * assertEquals(status.state, "granted"); - * }, - * }); - * ``` - * - * ```ts - * import { assertEquals } from "jsr:@std/assert"; - * - * Deno.test({ - * name: "true", - * permissions: { - * net: true, - * }, - * async fn() { - * const status = await Deno.permissions.query({ name: "net" }); - * assertEquals(status.state, "granted"); - * }, - * }); - * ``` - * - * ```ts - * import { assertEquals } from "jsr:@std/assert"; - * - * Deno.test({ - * name: "false", - * permissions: { - * net: false, - * }, - * async fn() { - * const status = await Deno.permissions.query({ name: "net" }); - * assertEquals(status.state, "denied"); - * }, - * }); - * ``` - * - * ```ts - * import { assertEquals } from "jsr:@std/assert"; - * - * Deno.test({ - * name: "localhost:8080", - * permissions: { - * net: ["localhost:8080"], - * }, - * async fn() { - * const status = await Deno.permissions.query({ name: "net", host: "localhost:8080" }); - * assertEquals(status.state, "granted"); - * }, - * }); - * ``` - */ - net?: "inherit" | boolean | string[]; - - /** Specifies if the `ffi` permission should be requested or revoked. - * If set to `"inherit"`, the current `ffi` permission will be inherited. - * If set to `true`, the global `ffi` permission will be requested. - * If set to `false`, the global `ffi` permission will be revoked. - * - * @default {false} - */ - ffi?: "inherit" | boolean | Array; - - /** Specifies if the `read` permission should be requested or revoked. - * If set to `"inherit"`, the current `read` permission will be inherited. - * If set to `true`, the global `read` permission will be requested. - * If set to `false`, the global `read` permission will be revoked. - * If set to `Array`, the `read` permission will be requested with the - * specified file paths. - * - * @default {false} - */ - read?: "inherit" | boolean | Array; - - /** Specifies if the `run` permission should be requested or revoked. - * If set to `"inherit"`, the current `run` permission will be inherited. - * If set to `true`, the global `run` permission will be requested. - * If set to `false`, the global `run` permission will be revoked. - * - * @default {false} - */ - run?: "inherit" | boolean | Array; - - /** Specifies if the `write` permission should be requested or revoked. - * If set to `"inherit"`, the current `write` permission will be inherited. - * If set to `true`, the global `write` permission will be requested. - * If set to `false`, the global `write` permission will be revoked. - * If set to `Array`, the `write` permission will be requested with the - * specified file paths. - * - * @default {false} - */ - write?: "inherit" | boolean | Array; - } - - /** - * Context that is passed to a testing function, which can be used to either - * gain information about the current test, or register additional test - * steps within the current test. - * - * @category Testing */ - export interface TestContext { - /** The current test name. */ - name: string; - /** The string URL of the current test. */ - origin: string; - /** If the current test is a step of another test, the parent test context - * will be set here. */ - parent?: TestContext; - - /** Run a sub step of the parent test or step. Returns a promise - * that resolves to a boolean signifying if the step completed successfully. - * - * The returned promise never rejects unless the arguments are invalid. - * - * If the test was ignored the promise returns `false`. - * - * ```ts - * Deno.test({ - * name: "a parent test", - * async fn(t) { - * console.log("before the step"); - * await t.step({ - * name: "step 1", - * fn(t) { - * console.log("current step:", t.name); - * } - * }); - * console.log("after the step"); - * } - * }); - * ``` - */ - step(definition: TestStepDefinition): Promise; - - /** Run a sub step of the parent test or step. Returns a promise - * that resolves to a boolean signifying if the step completed successfully. - * - * The returned promise never rejects unless the arguments are invalid. - * - * If the test was ignored the promise returns `false`. - * - * ```ts - * Deno.test( - * "a parent test", - * async (t) => { - * console.log("before the step"); - * await t.step( - * "step 1", - * (t) => { - * console.log("current step:", t.name); - * } - * ); - * console.log("after the step"); - * } - * ); - * ``` - */ - step( - name: string, - fn: (t: TestContext) => void | Promise, - ): Promise; - - /** Run a sub step of the parent test or step. Returns a promise - * that resolves to a boolean signifying if the step completed successfully. - * - * The returned promise never rejects unless the arguments are invalid. - * - * If the test was ignored the promise returns `false`. - * - * ```ts - * Deno.test(async function aParentTest(t) { - * console.log("before the step"); - * await t.step(function step1(t) { - * console.log("current step:", t.name); - * }); - * console.log("after the step"); - * }); - * ``` - */ - step(fn: (t: TestContext) => void | Promise): Promise; - } - - /** @category Testing */ - export interface TestStepDefinition { - /** The test function that will be tested when this step is executed. The - * function can take an argument which will provide information about the - * current step's context. */ - fn: (t: TestContext) => void | Promise; - /** The name of the step. */ - name: string; - /** If truthy the current test step will be ignored. - * - * This is a quick way to skip over a step, but also can be used for - * conditional logic, like determining if an environment feature is present. - */ - ignore?: boolean; - /** Check that the number of async completed operations after the test step - * is the same as number of dispatched operations. This ensures that the - * code tested does not start async operations which it then does - * not await. This helps in preventing logic errors and memory leaks - * in the application code. - * - * Defaults to the parent test or step's value. */ - sanitizeOps?: boolean; - /** Ensure the test step does not "leak" resources - like open files or - * network connections - by ensuring the open resources at the start of the - * step match the open resources at the end of the step. - * - * Defaults to the parent test or step's value. */ - sanitizeResources?: boolean; - /** Ensure the test step does not prematurely cause the process to exit, - * for example via a call to {@linkcode Deno.exit}. - * - * Defaults to the parent test or step's value. */ - sanitizeExit?: boolean; - } - - /** @category Testing */ - export interface TestDefinition { - fn: (t: TestContext) => void | Promise; - /** The name of the test. */ - name: string; - /** If truthy the current test step will be ignored. - * - * It is a quick way to skip over a step, but also can be used for - * conditional logic, like determining if an environment feature is present. - */ - ignore?: boolean; - /** If at least one test has `only` set to `true`, only run tests that have - * `only` set to `true` and fail the test suite. */ - only?: boolean; - /** Check that the number of async completed operations after the test step - * is the same as number of dispatched operations. This ensures that the - * code tested does not start async operations which it then does - * not await. This helps in preventing logic errors and memory leaks - * in the application code. - * - * @default {true} */ - sanitizeOps?: boolean; - /** Ensure the test step does not "leak" resources - like open files or - * network connections - by ensuring the open resources at the start of the - * test match the open resources at the end of the test. - * - * @default {true} */ - sanitizeResources?: boolean; - /** Ensure the test case does not prematurely cause the process to exit, - * for example via a call to {@linkcode Deno.exit}. - * - * @default {true} */ - sanitizeExit?: boolean; - /** Specifies the permissions that should be used to run the test. - * - * Set this to "inherit" to keep the calling runtime permissions, set this - * to "none" to revoke all permissions, or set a more specific set of - * permissions using a {@linkcode PermissionOptionsObject}. - * - * @default {"inherit"} */ - permissions?: PermissionOptions; - } - - /** Register a test which will be run when `deno test` is used on the command - * line and the containing module looks like a test module. - * - * `fn` can be async if required. - * - * ```ts - * import { assertEquals } from "jsr:@std/assert"; - * - * Deno.test({ - * name: "example test", - * fn() { - * assertEquals("world", "world"); - * }, - * }); - * - * Deno.test({ - * name: "example ignored test", - * ignore: Deno.build.os === "windows", - * fn() { - * // This test is ignored only on Windows machines - * }, - * }); - * - * Deno.test({ - * name: "example async test", - * async fn() { - * const decoder = new TextDecoder("utf-8"); - * const data = await Deno.readFile("hello_world.txt"); - * assertEquals(decoder.decode(data), "Hello world"); - * } - * }); - * ``` - * - * @category Testing - */ - export const test: DenoTest; - - /** - * @category Testing - */ - interface DenoTest { - /** Register a test which will be run when `deno test` is used on the command - * line and the containing module looks like a test module. - * - * `fn` can be async if required. - * - * ```ts - * import { assertEquals } from "jsr:@std/assert"; - * - * Deno.test({ - * name: "example test", - * fn() { - * assertEquals("world", "world"); - * }, - * }); - * - * Deno.test({ - * name: "example ignored test", - * ignore: Deno.build.os === "windows", - * fn() { - * // This test is ignored only on Windows machines - * }, - * }); - * - * Deno.test({ - * name: "example async test", - * async fn() { - * const decoder = new TextDecoder("utf-8"); - * const data = await Deno.readFile("hello_world.txt"); - * assertEquals(decoder.decode(data), "Hello world"); - * } - * }); - * ``` - * - * @category Testing - */ - (t: TestDefinition): void; - - /** Register a test which will be run when `deno test` is used on the command - * line and the containing module looks like a test module. - * - * `fn` can be async if required. - * - * ```ts - * import { assertEquals } from "jsr:@std/assert"; - * - * Deno.test("My test description", () => { - * assertEquals("hello", "hello"); - * }); - * - * Deno.test("My async test description", async () => { - * const decoder = new TextDecoder("utf-8"); - * const data = await Deno.readFile("hello_world.txt"); - * assertEquals(decoder.decode(data), "Hello world"); - * }); - * ``` - * - * @category Testing - */ - ( - name: string, - fn: (t: TestContext) => void | Promise, - ): void; - - /** Register a test which will be run when `deno test` is used on the command - * line and the containing module looks like a test module. - * - * `fn` can be async if required. Declared function must have a name. - * - * ```ts - * import { assertEquals } from "jsr:@std/assert"; - * - * Deno.test(function myTestName() { - * assertEquals("hello", "hello"); - * }); - * - * Deno.test(async function myOtherTestName() { - * const decoder = new TextDecoder("utf-8"); - * const data = await Deno.readFile("hello_world.txt"); - * assertEquals(decoder.decode(data), "Hello world"); - * }); - * ``` - * - * @category Testing - */ - (fn: (t: TestContext) => void | Promise): void; - - /** Register a test which will be run when `deno test` is used on the command - * line and the containing module looks like a test module. - * - * `fn` can be async if required. - * - * ```ts - * import { assert, fail, assertEquals } from "jsr:@std/assert"; - * - * Deno.test("My test description", { permissions: { read: true } }, (): void => { - * assertEquals("hello", "hello"); - * }); - * - * Deno.test("My async test description", { permissions: { read: false } }, async (): Promise => { - * const decoder = new TextDecoder("utf-8"); - * const data = await Deno.readFile("hello_world.txt"); - * assertEquals(decoder.decode(data), "Hello world"); - * }); - * ``` - * - * @category Testing - */ - ( - name: string, - options: Omit, - fn: (t: TestContext) => void | Promise, - ): void; - - /** Register a test which will be run when `deno test` is used on the command - * line and the containing module looks like a test module. - * - * `fn` can be async if required. - * - * ```ts - * import { assertEquals } from "jsr:@std/assert"; - * - * Deno.test( - * { - * name: "My test description", - * permissions: { read: true }, - * }, - * () => { - * assertEquals("hello", "hello"); - * }, - * ); - * - * Deno.test( - * { - * name: "My async test description", - * permissions: { read: false }, - * }, - * async () => { - * const decoder = new TextDecoder("utf-8"); - * const data = await Deno.readFile("hello_world.txt"); - * assertEquals(decoder.decode(data), "Hello world"); - * }, - * ); - * ``` - * - * @category Testing - */ - ( - options: Omit, - fn: (t: TestContext) => void | Promise, - ): void; - - /** Register a test which will be run when `deno test` is used on the command - * line and the containing module looks like a test module. - * - * `fn` can be async if required. Declared function must have a name. - * - * ```ts - * import { assertEquals } from "jsr:@std/assert"; - * - * Deno.test( - * { permissions: { read: true } }, - * function myTestName() { - * assertEquals("hello", "hello"); - * }, - * ); - * - * Deno.test( - * { permissions: { read: false } }, - * async function myOtherTestName() { - * const decoder = new TextDecoder("utf-8"); - * const data = await Deno.readFile("hello_world.txt"); - * assertEquals(decoder.decode(data), "Hello world"); - * }, - * ); - * ``` - * - * @category Testing - */ - ( - options: Omit, - fn: (t: TestContext) => void | Promise, - ): void; - - /** Shorthand property for ignoring a particular test case. - * - * @category Testing - */ - ignore(t: Omit): void; - - /** Shorthand property for ignoring a particular test case. - * - * @category Testing - */ - ignore( - name: string, - fn: (t: TestContext) => void | Promise, - ): void; - - /** Shorthand property for ignoring a particular test case. - * - * @category Testing - */ - ignore(fn: (t: TestContext) => void | Promise): void; - - /** Shorthand property for ignoring a particular test case. - * - * @category Testing - */ - ignore( - name: string, - options: Omit, - fn: (t: TestContext) => void | Promise, - ): void; - - /** Shorthand property for ignoring a particular test case. - * - * @category Testing - */ - ignore( - options: Omit, - fn: (t: TestContext) => void | Promise, - ): void; - - /** Shorthand property for ignoring a particular test case. - * - * @category Testing - */ - ignore( - options: Omit, - fn: (t: TestContext) => void | Promise, - ): void; - - /** Shorthand property for focusing a particular test case. - * - * @category Testing - */ - only(t: Omit): void; - - /** Shorthand property for focusing a particular test case. - * - * @category Testing - */ - only( - name: string, - fn: (t: TestContext) => void | Promise, - ): void; - - /** Shorthand property for focusing a particular test case. - * - * @category Testing - */ - only(fn: (t: TestContext) => void | Promise): void; - - /** Shorthand property for focusing a particular test case. - * - * @category Testing - */ - only( - name: string, - options: Omit, - fn: (t: TestContext) => void | Promise, - ): void; - - /** Shorthand property for focusing a particular test case. - * - * @category Testing - */ - only( - options: Omit, - fn: (t: TestContext) => void | Promise, - ): void; - - /** Shorthand property for focusing a particular test case. - * - * @category Testing - */ - only( - options: Omit, - fn: (t: TestContext) => void | Promise, - ): void; - } - - /** - * Context that is passed to a benchmarked function. The instance is shared - * between iterations of the benchmark. Its methods can be used for example - * to override of the measured portion of the function. - * - * @category Testing - */ - export interface BenchContext { - /** The current benchmark name. */ - name: string; - /** The string URL of the current benchmark. */ - origin: string; - - /** Restarts the timer for the bench measurement. This should be called - * after doing setup work which should not be measured. - * - * Warning: This method should not be used for benchmarks averaging less - * than 10μs per iteration. In such cases it will be disabled but the call - * will still have noticeable overhead, resulting in a warning. - * - * ```ts - * Deno.bench("foo", async (t) => { - * const data = await Deno.readFile("data.txt"); - * t.start(); - * // some operation on `data`... - * }); - * ``` - */ - start(): void; - - /** End the timer early for the bench measurement. This should be called - * before doing teardown work which should not be measured. - * - * Warning: This method should not be used for benchmarks averaging less - * than 10μs per iteration. In such cases it will be disabled but the call - * will still have noticeable overhead, resulting in a warning. - * - * ```ts - * Deno.bench("foo", async (t) => { - * using file = await Deno.open("data.txt"); - * t.start(); - * // some operation on `file`... - * t.end(); - * }); - * ``` - */ - end(): void; - } - - /** - * The interface for defining a benchmark test using {@linkcode Deno.bench}. - * - * @category Testing - */ - export interface BenchDefinition { - /** The test function which will be benchmarked. */ - fn: (b: BenchContext) => void | Promise; - /** The name of the test, which will be used in displaying the results. */ - name: string; - /** If truthy, the benchmark test will be ignored/skipped. */ - ignore?: boolean; - /** Group name for the benchmark. - * - * Grouped benchmarks produce a group time summary, where the difference - * in performance between each test of the group is compared. */ - group?: string; - /** Benchmark should be used as the baseline for other benchmarks. - * - * If there are multiple baselines in a group, the first one is used as the - * baseline. */ - baseline?: boolean; - /** If at least one bench has `only` set to true, only run benches that have - * `only` set to `true` and fail the bench suite. */ - only?: boolean; - /** Ensure the bench case does not prematurely cause the process to exit, - * for example via a call to {@linkcode Deno.exit}. - * - * @default {true} */ - sanitizeExit?: boolean; - /** Specifies the permissions that should be used to run the bench. - * - * Set this to `"inherit"` to keep the calling thread's permissions. - * - * Set this to `"none"` to revoke all permissions. - * - * @default {"inherit"} - */ - permissions?: PermissionOptions; - } - - /** - * Register a benchmark test which will be run when `deno bench` is used on - * the command line and the containing module looks like a bench module. - * - * If the test function (`fn`) returns a promise or is async, the test runner - * will await resolution to consider the test complete. - * - * ```ts - * import { assertEquals } from "jsr:@std/assert"; - * - * Deno.bench({ - * name: "example test", - * fn() { - * assertEquals("world", "world"); - * }, - * }); - * - * Deno.bench({ - * name: "example ignored test", - * ignore: Deno.build.os === "windows", - * fn() { - * // This test is ignored only on Windows machines - * }, - * }); - * - * Deno.bench({ - * name: "example async test", - * async fn() { - * const decoder = new TextDecoder("utf-8"); - * const data = await Deno.readFile("hello_world.txt"); - * assertEquals(decoder.decode(data), "Hello world"); - * } - * }); - * ``` - * - * @category Testing - */ - export function bench(b: BenchDefinition): void; - - /** - * Register a benchmark test which will be run when `deno bench` is used on - * the command line and the containing module looks like a bench module. - * - * If the test function (`fn`) returns a promise or is async, the test runner - * will await resolution to consider the test complete. - * - * ```ts - * import { assertEquals } from "jsr:@std/assert"; - * - * Deno.bench("My test description", () => { - * assertEquals("hello", "hello"); - * }); - * - * Deno.bench("My async test description", async () => { - * const decoder = new TextDecoder("utf-8"); - * const data = await Deno.readFile("hello_world.txt"); - * assertEquals(decoder.decode(data), "Hello world"); - * }); - * ``` - * - * @category Testing - */ - export function bench( - name: string, - fn: (b: BenchContext) => void | Promise, - ): void; - - /** - * Register a benchmark test which will be run when `deno bench` is used on - * the command line and the containing module looks like a bench module. - * - * If the test function (`fn`) returns a promise or is async, the test runner - * will await resolution to consider the test complete. - * - * ```ts - * import { assertEquals } from "jsr:@std/assert"; - * - * Deno.bench(function myTestName() { - * assertEquals("hello", "hello"); - * }); - * - * Deno.bench(async function myOtherTestName() { - * const decoder = new TextDecoder("utf-8"); - * const data = await Deno.readFile("hello_world.txt"); - * assertEquals(decoder.decode(data), "Hello world"); - * }); - * ``` - * - * @category Testing - */ - export function bench(fn: (b: BenchContext) => void | Promise): void; - - /** - * Register a benchmark test which will be run when `deno bench` is used on - * the command line and the containing module looks like a bench module. - * - * If the test function (`fn`) returns a promise or is async, the test runner - * will await resolution to consider the test complete. - * - * ```ts - * import { assertEquals } from "jsr:@std/assert"; - * - * Deno.bench( - * "My test description", - * { permissions: { read: true } }, - * () => { - * assertEquals("hello", "hello"); - * } - * ); - * - * Deno.bench( - * "My async test description", - * { permissions: { read: false } }, - * async () => { - * const decoder = new TextDecoder("utf-8"); - * const data = await Deno.readFile("hello_world.txt"); - * assertEquals(decoder.decode(data), "Hello world"); - * } - * ); - * ``` - * - * @category Testing - */ - export function bench( - name: string, - options: Omit, - fn: (b: BenchContext) => void | Promise, - ): void; - - /** - * Register a benchmark test which will be run when `deno bench` is used on - * the command line and the containing module looks like a bench module. - * - * If the test function (`fn`) returns a promise or is async, the test runner - * will await resolution to consider the test complete. - * - * ```ts - * import { assertEquals } from "jsr:@std/assert"; - * - * Deno.bench( - * { name: "My test description", permissions: { read: true } }, - * () => { - * assertEquals("hello", "hello"); - * } - * ); - * - * Deno.bench( - * { name: "My async test description", permissions: { read: false } }, - * async () => { - * const decoder = new TextDecoder("utf-8"); - * const data = await Deno.readFile("hello_world.txt"); - * assertEquals(decoder.decode(data), "Hello world"); - * } - * ); - * ``` - * - * @category Testing - */ - export function bench( - options: Omit, - fn: (b: BenchContext) => void | Promise, - ): void; - - /** - * Register a benchmark test which will be run when `deno bench` is used on - * the command line and the containing module looks like a bench module. - * - * If the test function (`fn`) returns a promise or is async, the test runner - * will await resolution to consider the test complete. - * - * ```ts - * import { assertEquals } from "jsr:@std/assert"; - * - * Deno.bench( - * { permissions: { read: true } }, - * function myTestName() { - * assertEquals("hello", "hello"); - * } - * ); - * - * Deno.bench( - * { permissions: { read: false } }, - * async function myOtherTestName() { - * const decoder = new TextDecoder("utf-8"); - * const data = await Deno.readFile("hello_world.txt"); - * assertEquals(decoder.decode(data), "Hello world"); - * } - * ); - * ``` - * - * @category Testing - */ - export function bench( - options: Omit, - fn: (b: BenchContext) => void | Promise, - ): void; - - /** Exit the Deno process with optional exit code. - * - * If no exit code is supplied then Deno will exit with return code of `0`. - * - * In worker contexts this is an alias to `self.close();`. - * - * ```ts - * Deno.exit(5); - * ``` - * - * @category Runtime Environment - */ - export function exit(code?: number): never; - - /** An interface containing methods to interact with the process environment - * variables. - * - * @tags allow-env - * @category Runtime Environment - */ - export interface Env { - /** Retrieve the value of an environment variable. - * - * Returns `undefined` if the supplied environment variable is not defined. - * - * ```ts - * console.log(Deno.env.get("HOME")); // e.g. outputs "/home/alice" - * console.log(Deno.env.get("MADE_UP_VAR")); // outputs "undefined" - * ``` - * - * Requires `allow-env` permission. - * - * @tags allow-env - */ - get(key: string): string | undefined; - - /** Set the value of an environment variable. - * - * ```ts - * Deno.env.set("SOME_VAR", "Value"); - * Deno.env.get("SOME_VAR"); // outputs "Value" - * ``` - * - * Requires `allow-env` permission. - * - * @tags allow-env - */ - set(key: string, value: string): void; - - /** Delete the value of an environment variable. - * - * ```ts - * Deno.env.set("SOME_VAR", "Value"); - * Deno.env.delete("SOME_VAR"); // outputs "undefined" - * ``` - * - * Requires `allow-env` permission. - * - * @tags allow-env - */ - delete(key: string): void; - - /** Check whether an environment variable is present or not. - * - * ```ts - * Deno.env.set("SOME_VAR", "Value"); - * Deno.env.has("SOME_VAR"); // outputs true - * ``` - * - * Requires `allow-env` permission. - * - * @tags allow-env - */ - has(key: string): boolean; - - /** Returns a snapshot of the environment variables at invocation as a - * simple object of keys and values. - * - * ```ts - * Deno.env.set("TEST_VAR", "A"); - * const myEnv = Deno.env.toObject(); - * console.log(myEnv.SHELL); - * Deno.env.set("TEST_VAR", "B"); - * console.log(myEnv.TEST_VAR); // outputs "A" - * ``` - * - * Requires `allow-env` permission. - * - * @tags allow-env - */ - toObject(): { [index: string]: string }; - } - - /** An interface containing methods to interact with the process environment - * variables. - * - * @tags allow-env - * @category Runtime Environment - */ - export const env: Env; - - /** - * Returns the path to the current deno executable. - * - * ```ts - * console.log(Deno.execPath()); // e.g. "/home/alice/.local/bin/deno" - * ``` - * - * Requires `allow-read` permission. - * - * @tags allow-read - * @category Runtime Environment - */ - export function execPath(): string; - - /** - * Change the current working directory to the specified path. - * - * ```ts - * Deno.chdir("/home/userA"); - * Deno.chdir("../userB"); - * Deno.chdir("C:\\Program Files (x86)\\Java"); - * ``` - * - * Throws {@linkcode Deno.errors.NotFound} if directory not found. - * - * Throws {@linkcode Deno.errors.PermissionDenied} if the user does not have - * operating system file access rights. - * - * Requires `allow-read` permission. - * - * @tags allow-read - * @category Runtime Environment - */ - export function chdir(directory: string | URL): void; - - /** - * Return a string representing the current working directory. - * - * If the current directory can be reached via multiple paths (due to symbolic - * links), `cwd()` may return any one of them. - * - * ```ts - * const currentWorkingDirectory = Deno.cwd(); - * ``` - * - * Throws {@linkcode Deno.errors.NotFound} if directory not available. - * - * Requires `allow-read` permission. - * - * @tags allow-read - * @category Runtime Environment - */ - export function cwd(): string; - - /** - * Creates `newpath` as a hard link to `oldpath`. - * - * ```ts - * await Deno.link("old/name", "new/name"); - * ``` - * - * Requires `allow-read` and `allow-write` permissions. - * - * @tags allow-read, allow-write - * @category File System - */ - export function link(oldpath: string, newpath: string): Promise; - - /** - * Synchronously creates `newpath` as a hard link to `oldpath`. - * - * ```ts - * Deno.linkSync("old/name", "new/name"); - * ``` - * - * Requires `allow-read` and `allow-write` permissions. - * - * @tags allow-read, allow-write - * @category File System - */ - export function linkSync(oldpath: string, newpath: string): void; - - /** - * A enum which defines the seek mode for IO related APIs that support - * seeking. - * - * @category I/O */ - export enum SeekMode { - /* Seek from the start of the file/resource. */ - Start = 0, - /* Seek from the current position within the file/resource. */ - Current = 1, - /* Seek from the end of the current file/resource. */ - End = 2, - } - - /** - * An abstract interface which when implemented provides an interface to read - * bytes into an array buffer asynchronously. - * - * @deprecated This will be removed in Deno 2.0. See the - * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide} - * for migration instructions. - * - * @category I/O */ - export interface Reader { - /** Reads up to `p.byteLength` bytes into `p`. It resolves to the number of - * bytes read (`0` < `n` <= `p.byteLength`) and rejects if any error - * encountered. Even if `read()` resolves to `n` < `p.byteLength`, it may - * use all of `p` as scratch space during the call. If some data is - * available but not `p.byteLength` bytes, `read()` conventionally resolves - * to what is available instead of waiting for more. - * - * When `read()` encounters end-of-file condition, it resolves to EOF - * (`null`). - * - * When `read()` encounters an error, it rejects with an error. - * - * Callers should always process the `n` > `0` bytes returned before - * considering the EOF (`null`). Doing so correctly handles I/O errors that - * happen after reading some bytes and also both of the allowed EOF - * behaviors. - * - * Implementations should not retain a reference to `p`. - * - * Use - * {@linkcode https://jsr.io/@std/io/doc/iterate-reader/~/iterateReader | iterateReader} - * to turn {@linkcode Reader} into an {@linkcode AsyncIterator}. - */ - read(p: Uint8Array): Promise; - } - - /** - * An abstract interface which when implemented provides an interface to read - * bytes into an array buffer synchronously. - * - * @deprecated This will be removed in Deno 2.0. See the - * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide} - * for migration instructions. - * - * @category I/O */ - export interface ReaderSync { - /** Reads up to `p.byteLength` bytes into `p`. It resolves to the number - * of bytes read (`0` < `n` <= `p.byteLength`) and rejects if any error - * encountered. Even if `readSync()` returns `n` < `p.byteLength`, it may use - * all of `p` as scratch space during the call. If some data is available - * but not `p.byteLength` bytes, `readSync()` conventionally returns what is - * available instead of waiting for more. - * - * When `readSync()` encounters end-of-file condition, it returns EOF - * (`null`). - * - * When `readSync()` encounters an error, it throws with an error. - * - * Callers should always process the `n` > `0` bytes returned before - * considering the EOF (`null`). Doing so correctly handles I/O errors that - * happen after reading some bytes and also both of the allowed EOF - * behaviors. - * - * Implementations should not retain a reference to `p`. - * - * Use - * {@linkcode https://jsr.io/@std/io/doc/iterate-reader/~/iterateReaderSync | iterateReaderSync} - * to turn {@linkcode ReaderSync} into an {@linkcode Iterator}. - */ - readSync(p: Uint8Array): number | null; - } - - /** - * An abstract interface which when implemented provides an interface to write - * bytes from an array buffer to a file/resource asynchronously. - * - * @deprecated This will be removed in Deno 2.0. See the - * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide} - * for migration instructions. - * - * @category I/O */ - export interface Writer { - /** Writes `p.byteLength` bytes from `p` to the underlying data stream. It - * resolves to the number of bytes written from `p` (`0` <= `n` <= - * `p.byteLength`) or reject with the error encountered that caused the - * write to stop early. `write()` must reject with a non-null error if - * would resolve to `n` < `p.byteLength`. `write()` must not modify the - * slice data, even temporarily. - * - * This function is one of the lowest - * level APIs and most users should not work with this directly, but rather - * use {@linkcode https://jsr.io/@std/io/doc/write-all/~/writeAll | writeAll} - * instead. - * - * Implementations should not retain a reference to `p`. - */ - write(p: Uint8Array): Promise; - } - - /** - * An abstract interface which when implemented provides an interface to write - * bytes from an array buffer to a file/resource synchronously. - * - * @deprecated This will be removed in Deno 2.0. See the - * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide} - * for migration instructions. - * - * @category I/O */ - export interface WriterSync { - /** Writes `p.byteLength` bytes from `p` to the underlying data - * stream. It returns the number of bytes written from `p` (`0` <= `n` - * <= `p.byteLength`) and any error encountered that caused the write to - * stop early. `writeSync()` must throw a non-null error if it returns `n` < - * `p.byteLength`. `writeSync()` must not modify the slice data, even - * temporarily. - * - * Implementations should not retain a reference to `p`. - */ - writeSync(p: Uint8Array): number; - } - - /** - * An abstract interface which when implemented provides an interface to close - * files/resources that were previously opened. - * - * @deprecated This will be removed in Deno 2.0. See the - * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide} - * for migration instructions. - * - * @category I/O */ - export interface Closer { - /** Closes the resource, "freeing" the backing file/resource. */ - close(): void; - } - - /** - * An abstract interface which when implemented provides an interface to seek - * within an open file/resource asynchronously. - * - * @category I/O */ - export interface Seeker { - /** Seek sets the offset for the next `read()` or `write()` to offset, - * interpreted according to `whence`: `Start` means relative to the - * start of the file, `Current` means relative to the current offset, - * and `End` means relative to the end. Seek resolves to the new offset - * relative to the start of the file. - * - * Seeking to an offset before the start of the file is an error. Seeking to - * any positive offset is legal, but the behavior of subsequent I/O - * operations on the underlying object is implementation-dependent. - * - * It resolves with the updated offset. - */ - seek(offset: number | bigint, whence: SeekMode): Promise; - } - - /** - * An abstract interface which when implemented provides an interface to seek - * within an open file/resource synchronously. - * - * @category I/O */ - export interface SeekerSync { - /** Seek sets the offset for the next `readSync()` or `writeSync()` to - * offset, interpreted according to `whence`: `Start` means relative - * to the start of the file, `Current` means relative to the current - * offset, and `End` means relative to the end. - * - * Seeking to an offset before the start of the file is an error. Seeking to - * any positive offset is legal, but the behavior of subsequent I/O - * operations on the underlying object is implementation-dependent. - * - * It returns the updated offset. - */ - seekSync(offset: number | bigint, whence: SeekMode): number; - } - - /** - * Copies from `src` to `dst` until either EOF (`null`) is read from `src` or - * an error occurs. It resolves to the number of bytes copied or rejects with - * the first error encountered while copying. - * - * @deprecated This will be removed in Deno 2.0. See the - * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide} - * for migration instructions. - * - * @category I/O - * - * @param src The source to copy from - * @param dst The destination to copy to - * @param options Can be used to tune size of the buffer. Default size is 32kB - */ - export function copy( - src: Reader, - dst: Writer, - options?: { bufSize?: number }, - ): Promise; - - /** - * Turns a Reader, `r`, into an async iterator. - * - * @deprecated This will be removed in Deno 2.0. See the - * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide} - * for migration instructions. - * - * @category I/O - */ - export function iter( - r: Reader, - options?: { bufSize?: number }, - ): AsyncIterableIterator; - - /** - * Turns a ReaderSync, `r`, into an iterator. - * - * @deprecated This will be removed in Deno 2.0. See the - * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide} - * for migration instructions. - * - * @category I/O - */ - export function iterSync( - r: ReaderSync, - options?: { - bufSize?: number; - }, - ): IterableIterator; - - /** Open a file and resolve to an instance of {@linkcode Deno.FsFile}. The - * file does not need to previously exist if using the `create` or `createNew` - * open options. The caller may have the resulting file automatically closed - * by the runtime once it's out of scope by declaring the file variable with - * the `using` keyword. - * - * ```ts - * using file = await Deno.open("/foo/bar.txt", { read: true, write: true }); - * // Do work with file - * ``` - * - * Alternatively, the caller may manually close the resource when finished with - * it. - * - * ```ts - * const file = await Deno.open("/foo/bar.txt", { read: true, write: true }); - * // Do work with file - * file.close(); - * ``` - * - * Requires `allow-read` and/or `allow-write` permissions depending on - * options. - * - * @tags allow-read, allow-write - * @category File System - */ - export function open( - path: string | URL, - options?: OpenOptions, - ): Promise; - - /** Synchronously open a file and return an instance of - * {@linkcode Deno.FsFile}. The file does not need to previously exist if - * using the `create` or `createNew` open options. The caller may have the - * resulting file automatically closed by the runtime once it's out of scope - * by declaring the file variable with the `using` keyword. - * - * ```ts - * using file = Deno.openSync("/foo/bar.txt", { read: true, write: true }); - * // Do work with file - * ``` - * - * Alternatively, the caller may manually close the resource when finished with - * it. - * - * ```ts - * const file = Deno.openSync("/foo/bar.txt", { read: true, write: true }); - * // Do work with file - * file.close(); - * ``` - * - * Requires `allow-read` and/or `allow-write` permissions depending on - * options. - * - * @tags allow-read, allow-write - * @category File System - */ - export function openSync(path: string | URL, options?: OpenOptions): FsFile; - - /** Creates a file if none exists or truncates an existing file and resolves to - * an instance of {@linkcode Deno.FsFile}. - * - * ```ts - * const file = await Deno.create("/foo/bar.txt"); - * ``` - * - * Requires `allow-read` and `allow-write` permissions. - * - * @tags allow-read, allow-write - * @category File System - */ - export function create(path: string | URL): Promise; - - /** Creates a file if none exists or truncates an existing file and returns - * an instance of {@linkcode Deno.FsFile}. - * - * ```ts - * const file = Deno.createSync("/foo/bar.txt"); - * ``` - * - * Requires `allow-read` and `allow-write` permissions. - * - * @tags allow-read, allow-write - * @category File System - */ - export function createSync(path: string | URL): FsFile; - - /** Read from a resource ID (`rid`) into an array buffer (`buffer`). - * - * Resolves to either the number of bytes read during the operation or EOF - * (`null`) if there was nothing more to read. - * - * It is possible for a read to successfully return with `0` bytes. This does - * not indicate EOF. - * - * This function is one of the lowest level APIs and most users should not - * work with this directly, but rather use {@linkcode ReadableStream} and - * {@linkcode https://jsr.io/@std/streams/doc/to-array-buffer/~/toArrayBuffer | toArrayBuffer} - * instead. - * - * **It is not guaranteed that the full buffer will be read in a single call.** - * - * ```ts - * // if "/foo/bar.txt" contains the text "hello world": - * using file = await Deno.open("/foo/bar.txt"); - * const buf = new Uint8Array(100); - * const numberOfBytesRead = await Deno.read(file.rid, buf); // 11 bytes - * const text = new TextDecoder().decode(buf); // "hello world" - * ``` - * - * @deprecated This will be removed in Deno 2.0. See the - * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide} - * for migration instructions. - * - * @category I/O - */ - export function read(rid: number, buffer: Uint8Array): Promise; - - /** Synchronously read from a resource ID (`rid`) into an array buffer - * (`buffer`). - * - * Returns either the number of bytes read during the operation or EOF - * (`null`) if there was nothing more to read. - * - * It is possible for a read to successfully return with `0` bytes. This does - * not indicate EOF. - * - * This function is one of the lowest level APIs and most users should not - * work with this directly, but rather use {@linkcode ReadableStream} and - * {@linkcode https://jsr.io/@std/streams/doc/to-array-buffer/~/toArrayBuffer | toArrayBuffer} - * instead. - * - * **It is not guaranteed that the full buffer will be read in a single - * call.** - * - * ```ts - * // if "/foo/bar.txt" contains the text "hello world": - * using file = Deno.openSync("/foo/bar.txt"); - * const buf = new Uint8Array(100); - * const numberOfBytesRead = Deno.readSync(file.rid, buf); // 11 bytes - * const text = new TextDecoder().decode(buf); // "hello world" - * ``` - * - * @deprecated This will be removed in Deno 2.0. See the - * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide} - * for migration instructions. - * - * @category I/O - */ - export function readSync(rid: number, buffer: Uint8Array): number | null; - - /** Write to the resource ID (`rid`) the contents of the array buffer (`data`). - * - * Resolves to the number of bytes written. This function is one of the lowest - * level APIs and most users should not work with this directly, but rather - * use {@linkcode WritableStream}, {@linkcode ReadableStream.from} and - * {@linkcode ReadableStream.pipeTo}. - * - * **It is not guaranteed that the full buffer will be written in a single - * call.** - * - * ```ts - * const encoder = new TextEncoder(); - * const data = encoder.encode("Hello world"); - * using file = await Deno.open("/foo/bar.txt", { write: true }); - * const bytesWritten = await Deno.write(file.rid, data); // 11 - * ``` - * - * @deprecated This will be removed in Deno 2.0. See the - * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide} - * for migration instructions. - * - * @category I/O - */ - export function write(rid: number, data: Uint8Array): Promise; - - /** Synchronously write to the resource ID (`rid`) the contents of the array - * buffer (`data`). - * - * Returns the number of bytes written. This function is one of the lowest - * level APIs and most users should not work with this directly, but rather - * use {@linkcode WritableStream}, {@linkcode ReadableStream.from} and - * {@linkcode ReadableStream.pipeTo}. - * - * **It is not guaranteed that the full buffer will be written in a single - * call.** - * - * ```ts - * const encoder = new TextEncoder(); - * const data = encoder.encode("Hello world"); - * using file = Deno.openSync("/foo/bar.txt", { write: true }); - * const bytesWritten = Deno.writeSync(file.rid, data); // 11 - * ``` - * - * @deprecated This will be removed in Deno 2.0. See the - * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide} - * for migration instructions. - * - * @category I/O - */ - export function writeSync(rid: number, data: Uint8Array): number; - - /** Seek a resource ID (`rid`) to the given `offset` under mode given by `whence`. - * The call resolves to the new position within the resource (bytes from the start). - * - * ```ts - * // Given file.rid pointing to file with "Hello world", which is 11 bytes long: - * using file = await Deno.open( - * "hello.txt", - * { read: true, write: true, truncate: true, create: true }, - * ); - * await file.write(new TextEncoder().encode("Hello world")); - * - * // advance cursor 6 bytes - * const cursorPosition = await Deno.seek(file.rid, 6, Deno.SeekMode.Start); - * console.log(cursorPosition); // 6 - * const buf = new Uint8Array(100); - * await file.read(buf); - * console.log(new TextDecoder().decode(buf)); // "world" - * ``` - * - * The seek modes work as follows: - * - * ```ts - * // Given file.rid pointing to file with "Hello world", which is 11 bytes long: - * using file = await Deno.open( - * "hello.txt", - * { read: true, write: true, truncate: true, create: true }, - * ); - * await file.write(new TextEncoder().encode("Hello world")); - * - * // Seek 6 bytes from the start of the file - * console.log(await Deno.seek(file.rid, 6, Deno.SeekMode.Start)); // "6" - * // Seek 2 more bytes from the current position - * console.log(await Deno.seek(file.rid, 2, Deno.SeekMode.Current)); // "8" - * // Seek backwards 2 bytes from the end of the file - * console.log(await Deno.seek(file.rid, -2, Deno.SeekMode.End)); // "9" (i.e. 11-2) - * ``` - * - * @deprecated This will be removed in Deno 2.0. See the - * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide} - * for migration instructions. - * - * @category I/O - */ - export function seek( - rid: number, - offset: number | bigint, - whence: SeekMode, - ): Promise; - - /** Synchronously seek a resource ID (`rid`) to the given `offset` under mode - * given by `whence`. The new position within the resource (bytes from the - * start) is returned. - * - * ```ts - * using file = Deno.openSync( - * "hello.txt", - * { read: true, write: true, truncate: true, create: true }, - * ); - * file.writeSync(new TextEncoder().encode("Hello world")); - * - * // advance cursor 6 bytes - * const cursorPosition = Deno.seekSync(file.rid, 6, Deno.SeekMode.Start); - * console.log(cursorPosition); // 6 - * const buf = new Uint8Array(100); - * file.readSync(buf); - * console.log(new TextDecoder().decode(buf)); // "world" - * ``` - * - * The seek modes work as follows: - * - * ```ts - * // Given file.rid pointing to file with "Hello world", which is 11 bytes long: - * using file = Deno.openSync( - * "hello.txt", - * { read: true, write: true, truncate: true, create: true }, - * ); - * file.writeSync(new TextEncoder().encode("Hello world")); - * - * // Seek 6 bytes from the start of the file - * console.log(Deno.seekSync(file.rid, 6, Deno.SeekMode.Start)); // "6" - * // Seek 2 more bytes from the current position - * console.log(Deno.seekSync(file.rid, 2, Deno.SeekMode.Current)); // "8" - * // Seek backwards 2 bytes from the end of the file - * console.log(Deno.seekSync(file.rid, -2, Deno.SeekMode.End)); // "9" (i.e. 11-2) - * ``` - * - * @deprecated This will be removed in Deno 2.0. See the - * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide} - * for migration instructions. - * - * @category I/O - */ - export function seekSync( - rid: number, - offset: number | bigint, - whence: SeekMode, - ): number; - - /** - * Flushes any pending data and metadata operations of the given file stream - * to disk. - * - * ```ts - * const file = await Deno.open( - * "my_file.txt", - * { read: true, write: true, create: true }, - * ); - * await file.write(new TextEncoder().encode("Hello World")); - * await file.truncate(1); - * await Deno.fsync(file.rid); - * console.log(await Deno.readTextFile("my_file.txt")); // H - * ``` - * - * @category File System - */ - export function fsync(rid: number): Promise; - - /** - * Synchronously flushes any pending data and metadata operations of the given - * file stream to disk. - * - * ```ts - * const file = Deno.openSync( - * "my_file.txt", - * { read: true, write: true, create: true }, - * ); - * file.writeSync(new TextEncoder().encode("Hello World")); - * file.truncateSync(1); - * Deno.fsyncSync(file.rid); - * console.log(Deno.readTextFileSync("my_file.txt")); // H - * ``` - * - * @category File System - */ - export function fsyncSync(rid: number): void; - - /** - * Flushes any pending data operations of the given file stream to disk. - * ```ts - * const file = await Deno.open( - * "my_file.txt", - * { read: true, write: true, create: true }, - * ); - * await file.write(new TextEncoder().encode("Hello World")); - * await Deno.fdatasync(file.rid); - * console.log(await Deno.readTextFile("my_file.txt")); // Hello World - * ``` - * - * @category File System - */ - export function fdatasync(rid: number): Promise; - - /** - * Synchronously flushes any pending data operations of the given file stream - * to disk. - * - * ```ts - * const file = Deno.openSync( - * "my_file.txt", - * { read: true, write: true, create: true }, - * ); - * file.writeSync(new TextEncoder().encode("Hello World")); - * Deno.fdatasyncSync(file.rid); - * console.log(Deno.readTextFileSync("my_file.txt")); // Hello World - * ``` - * - * @category File System - */ - export function fdatasyncSync(rid: number): void; - - /** Close the given resource ID (`rid`) which has been previously opened, such - * as via opening or creating a file. Closing a file when you are finished - * with it is important to avoid leaking resources. - * - * ```ts - * const file = await Deno.open("my_file.txt"); - * // do work with "file" object - * Deno.close(file.rid); - * ``` - * - * It is recommended to define the variable with the `using` keyword so the - * runtime will automatically close the resource when it goes out of scope. - * Doing so negates the need to manually close the resource. - * - * ```ts - * using file = await Deno.open("my_file.txt"); - * // do work with "file" object - * ``` - * - * @deprecated This will be removed in Deno 2.0. See the - * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide} - * for migration instructions. - * - * @category I/O - */ - export function close(rid: number): void; - - /** The Deno abstraction for reading and writing files. - * - * This is the most straight forward way of handling files within Deno and is - * recommended over using the discrete functions within the `Deno` namespace. - * - * ```ts - * using file = await Deno.open("/foo/bar.txt", { read: true }); - * const fileInfo = await file.stat(); - * if (fileInfo.isFile) { - * const buf = new Uint8Array(100); - * const numberOfBytesRead = await file.read(buf); // 11 bytes - * const text = new TextDecoder().decode(buf); // "hello world" - * } - * ``` - * - * @category File System - */ - export class FsFile implements Reader, ReaderSync, Writer, WriterSync, Seeker, SeekerSync, Closer, Disposable { - /** - * The resource ID associated with the file instance. The resource ID - * should be considered an opaque reference to resource. - * - * @deprecated This will be removed in Deno 2.0. See the - * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide} - * for migration instructions. - */ - readonly rid: number; - /** A {@linkcode ReadableStream} instance representing to the byte contents - * of the file. This makes it easy to interoperate with other web streams - * based APIs. - * - * ```ts - * using file = await Deno.open("my_file.txt", { read: true }); - * const decoder = new TextDecoder(); - * for await (const chunk of file.readable) { - * console.log(decoder.decode(chunk)); - * } - * ``` - */ - readonly readable: ReadableStream; - /** A {@linkcode WritableStream} instance to write the contents of the - * file. This makes it easy to interoperate with other web streams based - * APIs. - * - * ```ts - * const items = ["hello", "world"]; - * using file = await Deno.open("my_file.txt", { write: true }); - * const encoder = new TextEncoder(); - * const writer = file.writable.getWriter(); - * for (const item of items) { - * await writer.write(encoder.encode(item)); - * } - * ``` - */ - readonly writable: WritableStream; - /** - * The constructor which takes a resource ID. Generally `FsFile` should - * not be constructed directly. Instead use {@linkcode Deno.open} or - * {@linkcode Deno.openSync} to create a new instance of `FsFile`. - * - * @deprecated This will be removed in Deno 2.0. See the - * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide} - * for migration instructions. - */ - constructor(rid: number); - /** Write the contents of the array buffer (`p`) to the file. - * - * Resolves to the number of bytes written. - * - * **It is not guaranteed that the full buffer will be written in a single - * call.** - * - * ```ts - * const encoder = new TextEncoder(); - * const data = encoder.encode("Hello world"); - * using file = await Deno.open("/foo/bar.txt", { write: true }); - * const bytesWritten = await file.write(data); // 11 - * ``` - * - * @category I/O - */ - write(p: Uint8Array): Promise; - /** Synchronously write the contents of the array buffer (`p`) to the file. - * - * Returns the number of bytes written. - * - * **It is not guaranteed that the full buffer will be written in a single - * call.** - * - * ```ts - * const encoder = new TextEncoder(); - * const data = encoder.encode("Hello world"); - * using file = Deno.openSync("/foo/bar.txt", { write: true }); - * const bytesWritten = file.writeSync(data); // 11 - * ``` - */ - writeSync(p: Uint8Array): number; - /** Truncates (or extends) the file to reach the specified `len`. If `len` - * is not specified, then the entire file contents are truncated. - * - * ### Truncate the entire file - * - * ```ts - * using file = await Deno.open("my_file.txt", { write: true }); - * await file.truncate(); - * ``` - * - * ### Truncate part of the file - * - * ```ts - * // if "my_file.txt" contains the text "hello world": - * using file = await Deno.open("my_file.txt", { write: true }); - * await file.truncate(7); - * const buf = new Uint8Array(100); - * await file.read(buf); - * const text = new TextDecoder().decode(buf); // "hello w" - * ``` - */ - truncate(len?: number): Promise; - /** Synchronously truncates (or extends) the file to reach the specified - * `len`. If `len` is not specified, then the entire file contents are - * truncated. - * - * ### Truncate the entire file - * - * ```ts - * using file = Deno.openSync("my_file.txt", { write: true }); - * file.truncateSync(); - * ``` - * - * ### Truncate part of the file - * - * ```ts - * // if "my_file.txt" contains the text "hello world": - * using file = Deno.openSync("my_file.txt", { write: true }); - * file.truncateSync(7); - * const buf = new Uint8Array(100); - * file.readSync(buf); - * const text = new TextDecoder().decode(buf); // "hello w" - * ``` - */ - truncateSync(len?: number): void; - /** Read the file into an array buffer (`p`). - * - * Resolves to either the number of bytes read during the operation or EOF - * (`null`) if there was nothing more to read. - * - * It is possible for a read to successfully return with `0` bytes. This - * does not indicate EOF. - * - * **It is not guaranteed that the full buffer will be read in a single - * call.** - * - * ```ts - * // if "/foo/bar.txt" contains the text "hello world": - * using file = await Deno.open("/foo/bar.txt"); - * const buf = new Uint8Array(100); - * const numberOfBytesRead = await file.read(buf); // 11 bytes - * const text = new TextDecoder().decode(buf); // "hello world" - * ``` - */ - read(p: Uint8Array): Promise; - /** Synchronously read from the file into an array buffer (`p`). - * - * Returns either the number of bytes read during the operation or EOF - * (`null`) if there was nothing more to read. - * - * It is possible for a read to successfully return with `0` bytes. This - * does not indicate EOF. - * - * **It is not guaranteed that the full buffer will be read in a single - * call.** - * - * ```ts - * // if "/foo/bar.txt" contains the text "hello world": - * using file = Deno.openSync("/foo/bar.txt"); - * const buf = new Uint8Array(100); - * const numberOfBytesRead = file.readSync(buf); // 11 bytes - * const text = new TextDecoder().decode(buf); // "hello world" - * ``` - */ - readSync(p: Uint8Array): number | null; - /** Seek to the given `offset` under mode given by `whence`. The call - * resolves to the new position within the resource (bytes from the start). - * - * ```ts - * // Given file pointing to file with "Hello world", which is 11 bytes long: - * using file = await Deno.open( - * "hello.txt", - * { read: true, write: true, truncate: true, create: true }, - * ); - * await file.write(new TextEncoder().encode("Hello world")); - * - * // advance cursor 6 bytes - * const cursorPosition = await file.seek(6, Deno.SeekMode.Start); - * console.log(cursorPosition); // 6 - * const buf = new Uint8Array(100); - * await file.read(buf); - * console.log(new TextDecoder().decode(buf)); // "world" - * ``` - * - * The seek modes work as follows: - * - * ```ts - * // Given file.rid pointing to file with "Hello world", which is 11 bytes long: - * const file = await Deno.open( - * "hello.txt", - * { read: true, write: true, truncate: true, create: true }, - * ); - * await file.write(new TextEncoder().encode("Hello world")); - * - * // Seek 6 bytes from the start of the file - * console.log(await file.seek(6, Deno.SeekMode.Start)); // "6" - * // Seek 2 more bytes from the current position - * console.log(await file.seek(2, Deno.SeekMode.Current)); // "8" - * // Seek backwards 2 bytes from the end of the file - * console.log(await file.seek(-2, Deno.SeekMode.End)); // "9" (i.e. 11-2) - * ``` - */ - seek(offset: number | bigint, whence: SeekMode): Promise; - /** Synchronously seek to the given `offset` under mode given by `whence`. - * The new position within the resource (bytes from the start) is returned. - * - * ```ts - * using file = Deno.openSync( - * "hello.txt", - * { read: true, write: true, truncate: true, create: true }, - * ); - * file.writeSync(new TextEncoder().encode("Hello world")); - * - * // advance cursor 6 bytes - * const cursorPosition = file.seekSync(6, Deno.SeekMode.Start); - * console.log(cursorPosition); // 6 - * const buf = new Uint8Array(100); - * file.readSync(buf); - * console.log(new TextDecoder().decode(buf)); // "world" - * ``` - * - * The seek modes work as follows: - * - * ```ts - * // Given file.rid pointing to file with "Hello world", which is 11 bytes long: - * using file = Deno.openSync( - * "hello.txt", - * { read: true, write: true, truncate: true, create: true }, - * ); - * file.writeSync(new TextEncoder().encode("Hello world")); - * - * // Seek 6 bytes from the start of the file - * console.log(file.seekSync(6, Deno.SeekMode.Start)); // "6" - * // Seek 2 more bytes from the current position - * console.log(file.seekSync(2, Deno.SeekMode.Current)); // "8" - * // Seek backwards 2 bytes from the end of the file - * console.log(file.seekSync(-2, Deno.SeekMode.End)); // "9" (i.e. 11-2) - * ``` - */ - seekSync(offset: number | bigint, whence: SeekMode): number; - /** Resolves to a {@linkcode Deno.FileInfo} for the file. - * - * ```ts - * import { assert } from "jsr:@std/assert"; - * - * using file = await Deno.open("hello.txt"); - * const fileInfo = await file.stat(); - * assert(fileInfo.isFile); - * ``` - */ - stat(): Promise; - /** Synchronously returns a {@linkcode Deno.FileInfo} for the file. - * - * ```ts - * import { assert } from "jsr:@std/assert"; - * - * using file = Deno.openSync("hello.txt") - * const fileInfo = file.statSync(); - * assert(fileInfo.isFile); - * ``` - */ - statSync(): FileInfo; - /** **UNSTABLE**: New API, yet to be vetted. - * - * Flushes any pending data and metadata operations of the given file - * stream to disk. - * - * ```ts - * const file = await Deno.open( - * "my_file.txt", - * { read: true, write: true, create: true }, - * ); - * await file.write(new TextEncoder().encode("Hello World")); - * await file.truncate(1); - * await file.sync(); - * console.log(await Deno.readTextFile("my_file.txt")); // H - * ``` - * - * @category I/O - */ - sync(): Promise; - /** **UNSTABLE**: New API, yet to be vetted. - * - * Synchronously flushes any pending data and metadata operations of the given - * file stream to disk. - * - * ```ts - * const file = Deno.openSync( - * "my_file.txt", - * { read: true, write: true, create: true }, - * ); - * file.writeSync(new TextEncoder().encode("Hello World")); - * file.truncateSync(1); - * file.syncSync(); - * console.log(Deno.readTextFileSync("my_file.txt")); // H - * ``` - * - * @category I/O - */ - syncSync(): void; - /** **UNSTABLE**: New API, yet to be vetted. - * - * Flushes any pending data operations of the given file stream to disk. - * ```ts - * using file = await Deno.open( - * "my_file.txt", - * { read: true, write: true, create: true }, - * ); - * await file.write(new TextEncoder().encode("Hello World")); - * await file.syncData(); - * console.log(await Deno.readTextFile("my_file.txt")); // Hello World - * ``` - * - * @category I/O - */ - syncData(): Promise; - /** **UNSTABLE**: New API, yet to be vetted. - * - * Synchronously flushes any pending data operations of the given file stream - * to disk. - * - * ```ts - * using file = Deno.openSync( - * "my_file.txt", - * { read: true, write: true, create: true }, - * ); - * file.writeSync(new TextEncoder().encode("Hello World")); - * file.syncDataSync(); - * console.log(Deno.readTextFileSync("my_file.txt")); // Hello World - * ``` - * - * @category I/O - */ - syncDataSync(): void; - /** - * Changes the access (`atime`) and modification (`mtime`) times of the - * file stream resource. Given times are either in seconds (UNIX epoch - * time) or as `Date` objects. - * - * ```ts - * using file = await Deno.open("file.txt", { create: true, write: true }); - * await file.utime(1556495550, new Date()); - * ``` - * - * @category File System - */ - utime(atime: number | Date, mtime: number | Date): Promise; - /** - * Synchronously changes the access (`atime`) and modification (`mtime`) - * times of the file stream resource. Given times are either in seconds - * (UNIX epoch time) or as `Date` objects. - * - * ```ts - * using file = Deno.openSync("file.txt", { create: true, write: true }); - * file.utime(1556495550, new Date()); - * ``` - * - * @category File System - */ - utimeSync(atime: number | Date, mtime: number | Date): void; - /** **UNSTABLE**: New API, yet to be vetted. - * - * Checks if the file resource is a TTY (terminal). - * - * ```ts - * // This example is system and context specific - * using file = await Deno.open("/dev/tty6"); - * file.isTerminal(); // true - * ``` - */ - isTerminal(): boolean; - /** **UNSTABLE**: New API, yet to be vetted. - * - * Set TTY to be under raw mode or not. In raw mode, characters are read and - * returned as is, without being processed. All special processing of - * characters by the terminal is disabled, including echoing input - * characters. Reading from a TTY device in raw mode is faster than reading - * from a TTY device in canonical mode. - * - * ```ts - * using file = await Deno.open("/dev/tty6"); - * file.setRaw(true, { cbreak: true }); - * ``` - */ - setRaw(mode: boolean, options?: SetRawOptions): void; - /** **UNSTABLE**: New API, yet to be vetted. - * - * Acquire an advisory file-system lock for the file. - * - * @param [exclusive=false] - */ - lock(exclusive?: boolean): Promise; - /** **UNSTABLE**: New API, yet to be vetted. - * - * Synchronously acquire an advisory file-system lock synchronously for the file. - * - * @param [exclusive=false] - */ - lockSync(exclusive?: boolean): void; - /** **UNSTABLE**: New API, yet to be vetted. - * - * Release an advisory file-system lock for the file. - */ - unlock(): Promise; - /** **UNSTABLE**: New API, yet to be vetted. - * - * Synchronously release an advisory file-system lock for the file. - */ - unlockSync(): void; - /** Close the file. Closing a file when you are finished with it is - * important to avoid leaking resources. - * - * ```ts - * using file = await Deno.open("my_file.txt"); - * // do work with "file" object - * ``` - */ - close(): void; - - [Symbol.dispose](): void; - } - - /** - * The Deno abstraction for reading and writing files. - * - * @deprecated This will be removed in Deno 2.0. See the - * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide} - * for migration instructions. - * - * @category File System - */ - export const File: typeof FsFile; - - /** Gets the size of the console as columns/rows. - * - * ```ts - * const { columns, rows } = Deno.consoleSize(); - * ``` - * - * This returns the size of the console window as reported by the operating - * system. It's not a reflection of how many characters will fit within the - * console window, but can be used as part of that calculation. - * - * @category I/O - */ - export function consoleSize(): { - columns: number; - rows: number; - }; - - /** @category I/O */ - export interface SetRawOptions { - /** - * The `cbreak` option can be used to indicate that characters that - * correspond to a signal should still be generated. When disabling raw - * mode, this option is ignored. This functionality currently only works on - * Linux and Mac OS. - */ - cbreak: boolean; - } - - /** A reference to `stdin` which can be used to read directly from `stdin`. - * It implements the Deno specific {@linkcode Reader}, {@linkcode ReaderSync}, - * and {@linkcode Closer} interfaces as well as provides a - * {@linkcode ReadableStream} interface. - * - * ### Reading chunks from the readable stream - * - * ```ts - * const decoder = new TextDecoder(); - * for await (const chunk of Deno.stdin.readable) { - * const text = decoder.decode(chunk); - * // do something with the text - * } - * ``` - * - * @category I/O - */ - export const stdin: Reader & ReaderSync & Closer & { - /** - * The resource ID assigned to `stdin`. This can be used with the discrete - * I/O functions in the `Deno` namespace. - * - * @deprecated This will be soft-removed in Deno 2.0. See the - * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide} - * for migration instructions. - */ - readonly rid: number; - /** A readable stream interface to `stdin`. */ - readonly readable: ReadableStream; - /** - * Set TTY to be under raw mode or not. In raw mode, characters are read and - * returned as is, without being processed. All special processing of - * characters by the terminal is disabled, including echoing input - * characters. Reading from a TTY device in raw mode is faster than reading - * from a TTY device in canonical mode. - * - * ```ts - * Deno.stdin.setRaw(true, { cbreak: true }); - * ``` - * - * @category I/O - */ - setRaw(mode: boolean, options?: SetRawOptions): void; - /** - * Checks if `stdin` is a TTY (terminal). - * - * ```ts - * // This example is system and context specific - * Deno.stdin.isTerminal(); // true - * ``` - * - * @category I/O - */ - isTerminal(): boolean; - }; - /** A reference to `stdout` which can be used to write directly to `stdout`. - * It implements the Deno specific {@linkcode Writer}, {@linkcode WriterSync}, - * and {@linkcode Closer} interfaces as well as provides a - * {@linkcode WritableStream} interface. - * - * These are low level constructs, and the {@linkcode console} interface is a - * more straight forward way to interact with `stdout` and `stderr`. - * - * @category I/O - */ - export const stdout: Writer & WriterSync & Closer & { - /** - * The resource ID assigned to `stdout`. This can be used with the discrete - * I/O functions in the `Deno` namespace. - * - * @deprecated This will be soft-removed in Deno 2.0. See the - * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide} - * for migration instructions. - */ - readonly rid: number; - /** A writable stream interface to `stdout`. */ - readonly writable: WritableStream; - /** - * Checks if `stdout` is a TTY (terminal). - * - * ```ts - * // This example is system and context specific - * Deno.stdout.isTerminal(); // true - * ``` - * - * @category I/O - */ - isTerminal(): boolean; - }; - /** A reference to `stderr` which can be used to write directly to `stderr`. - * It implements the Deno specific {@linkcode Writer}, {@linkcode WriterSync}, - * and {@linkcode Closer} interfaces as well as provides a - * {@linkcode WritableStream} interface. - * - * These are low level constructs, and the {@linkcode console} interface is a - * more straight forward way to interact with `stdout` and `stderr`. - * - * @category I/O - */ - export const stderr: Writer & WriterSync & Closer & { - /** - * The resource ID assigned to `stderr`. This can be used with the discrete - * I/O functions in the `Deno` namespace. - * - * @deprecated This will be soft-removed in Deno 2.0. See the - * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide} - * for migration instructions. - */ - readonly rid: number; - /** A writable stream interface to `stderr`. */ - readonly writable: WritableStream; - /** - * Checks if `stderr` is a TTY (terminal). - * - * ```ts - * // This example is system and context specific - * Deno.stderr.isTerminal(); // true - * ``` - * - * @category I/O - */ - isTerminal(): boolean; - }; - - /** - * Options which can be set when doing {@linkcode Deno.open} and - * {@linkcode Deno.openSync}. - * - * @category File System */ - export interface OpenOptions { - /** Sets the option for read access. This option, when `true`, means that - * the file should be read-able if opened. - * - * @default {true} */ - read?: boolean; - /** Sets the option for write access. This option, when `true`, means that - * the file should be write-able if opened. If the file already exists, - * any write calls on it will overwrite its contents, by default without - * truncating it. - * - * @default {false} */ - write?: boolean; - /** Sets the option for the append mode. This option, when `true`, means - * that writes will append to a file instead of overwriting previous - * contents. - * - * Note that setting `{ write: true, append: true }` has the same effect as - * setting only `{ append: true }`. - * - * @default {false} */ - append?: boolean; - /** Sets the option for truncating a previous file. If a file is - * successfully opened with this option set it will truncate the file to `0` - * size if it already exists. The file must be opened with write access - * for truncate to work. - * - * @default {false} */ - truncate?: boolean; - /** Sets the option to allow creating a new file, if one doesn't already - * exist at the specified path. Requires write or append access to be - * used. - * - * @default {false} */ - create?: boolean; - /** If set to `true`, no file, directory, or symlink is allowed to exist at - * the target location. Requires write or append access to be used. When - * createNew is set to `true`, create and truncate are ignored. - * - * @default {false} */ - createNew?: boolean; - /** Permissions to use if creating the file (defaults to `0o666`, before - * the process's umask). - * - * Ignored on Windows. */ - mode?: number; - } - - /** - * Options which can be set when using {@linkcode Deno.readFile} or - * {@linkcode Deno.readFileSync}. - * - * @category File System */ - export interface ReadFileOptions { - /** - * An abort signal to allow cancellation of the file read operation. - * If the signal becomes aborted the readFile operation will be stopped - * and the promise returned will be rejected with an AbortError. - */ - signal?: AbortSignal; - } - - /** - * Check if a given resource id (`rid`) is a TTY (a terminal). - * - * ```ts - * // This example is system and context specific - * const nonTTYRid = Deno.openSync("my_file.txt").rid; - * const ttyRid = Deno.openSync("/dev/tty6").rid; - * console.log(Deno.isatty(nonTTYRid)); // false - * console.log(Deno.isatty(ttyRid)); // true - * ``` - * - * @deprecated This will be soft-removed in Deno 2.0. See the - * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide} - * for migration instructions. - * - * @category I/O - */ - export function isatty(rid: number): boolean; - - /** - * A variable-sized buffer of bytes with `read()` and `write()` methods. - * - * @deprecated This will be removed in Deno 2.0. See the - * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide} - * for migration instructions. - * - * @category I/O - */ - export class Buffer implements Reader, ReaderSync, Writer, WriterSync { - constructor(ab?: ArrayBuffer); - /** Returns a slice holding the unread portion of the buffer. - * - * The slice is valid for use only until the next buffer modification (that - * is, only until the next call to a method like `read()`, `write()`, - * `reset()`, or `truncate()`). If `options.copy` is false the slice aliases the buffer content at - * least until the next buffer modification, so immediate changes to the - * slice will affect the result of future reads. - * @param options Defaults to `{ copy: true }` - */ - bytes(options?: { copy?: boolean }): Uint8Array; - /** Returns whether the unread portion of the buffer is empty. */ - empty(): boolean; - /** A read only number of bytes of the unread portion of the buffer. */ - readonly length: number; - /** The read only capacity of the buffer's underlying byte slice, that is, - * the total space allocated for the buffer's data. */ - readonly capacity: number; - /** Discards all but the first `n` unread bytes from the buffer but - * continues to use the same allocated storage. It throws if `n` is - * negative or greater than the length of the buffer. */ - truncate(n: number): void; - /** Resets the buffer to be empty, but it retains the underlying storage for - * use by future writes. `.reset()` is the same as `.truncate(0)`. */ - reset(): void; - /** Reads the next `p.length` bytes from the buffer or until the buffer is - * drained. Returns the number of bytes read. If the buffer has no data to - * return, the return is EOF (`null`). */ - readSync(p: Uint8Array): number | null; - /** Reads the next `p.length` bytes from the buffer or until the buffer is - * drained. Resolves to the number of bytes read. If the buffer has no - * data to return, resolves to EOF (`null`). - * - * NOTE: This methods reads bytes synchronously; it's provided for - * compatibility with `Reader` interfaces. - */ - read(p: Uint8Array): Promise; - writeSync(p: Uint8Array): number; - /** NOTE: This methods writes bytes synchronously; it's provided for - * compatibility with `Writer` interface. */ - write(p: Uint8Array): Promise; - /** Grows the buffer's capacity, if necessary, to guarantee space for - * another `n` bytes. After `.grow(n)`, at least `n` bytes can be written to - * the buffer without another allocation. If `n` is negative, `.grow()` will - * throw. If the buffer can't grow it will throw an error. - * - * Based on Go Lang's - * [Buffer.Grow](https://golang.org/pkg/bytes/#Buffer.Grow). */ - grow(n: number): void; - /** Reads data from `r` until EOF (`null`) and appends it to the buffer, - * growing the buffer as needed. It resolves to the number of bytes read. - * If the buffer becomes too large, `.readFrom()` will reject with an error. - * - * Based on Go Lang's - * [Buffer.ReadFrom](https://golang.org/pkg/bytes/#Buffer.ReadFrom). */ - readFrom(r: Reader): Promise; - /** Reads data from `r` until EOF (`null`) and appends it to the buffer, - * growing the buffer as needed. It returns the number of bytes read. If the - * buffer becomes too large, `.readFromSync()` will throw an error. - * - * Based on Go Lang's - * [Buffer.ReadFrom](https://golang.org/pkg/bytes/#Buffer.ReadFrom). */ - readFromSync(r: ReaderSync): number; - } - - /** - * Read Reader `r` until EOF (`null`) and resolve to the content as - * Uint8Array`. - * - * @deprecated This will be removed in Deno 2.0. See the - * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide} - * for migration instructions. - * - * @category I/O - */ - export function readAll(r: Reader): Promise; - - /** - * Synchronously reads Reader `r` until EOF (`null`) and returns the content - * as `Uint8Array`. - * - * @deprecated This will be removed in Deno 2.0. See the - * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide} - * for migration instructions. - * - * @category I/O - */ - export function readAllSync(r: ReaderSync): Uint8Array; - - /** - * Write all the content of the array buffer (`arr`) to the writer (`w`). - * - * @deprecated This will be removed in Deno 2.0. See the - * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide} - * for migration instructions. - * - * @category I/O - */ - export function writeAll(w: Writer, arr: Uint8Array): Promise; - - /** - * Synchronously write all the content of the array buffer (`arr`) to the - * writer (`w`). - * - * @deprecated This will be removed in Deno 2.0. See the - * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide} - * for migration instructions. - * - * @category I/O - */ - export function writeAllSync(w: WriterSync, arr: Uint8Array): void; - - /** - * Options which can be set when using {@linkcode Deno.mkdir} and - * {@linkcode Deno.mkdirSync}. - * - * @category File System */ - export interface MkdirOptions { - /** If set to `true`, means that any intermediate directories will also be - * created (as with the shell command `mkdir -p`). - * - * Intermediate directories are created with the same permissions. - * - * When recursive is set to `true`, succeeds silently (without changing any - * permissions) if a directory already exists at the path, or if the path - * is a symlink to an existing directory. - * - * @default {false} */ - recursive?: boolean; - /** Permissions to use when creating the directory (defaults to `0o777`, - * before the process's umask). - * - * Ignored on Windows. */ - mode?: number; - } - - /** Creates a new directory with the specified path. - * - * ```ts - * await Deno.mkdir("new_dir"); - * await Deno.mkdir("nested/directories", { recursive: true }); - * await Deno.mkdir("restricted_access_dir", { mode: 0o700 }); - * ``` - * - * Defaults to throwing error if the directory already exists. - * - * Requires `allow-write` permission. - * - * @tags allow-write - * @category File System - */ - export function mkdir( - path: string | URL, - options?: MkdirOptions, - ): Promise; - - /** Synchronously creates a new directory with the specified path. - * - * ```ts - * Deno.mkdirSync("new_dir"); - * Deno.mkdirSync("nested/directories", { recursive: true }); - * Deno.mkdirSync("restricted_access_dir", { mode: 0o700 }); - * ``` - * - * Defaults to throwing error if the directory already exists. - * - * Requires `allow-write` permission. - * - * @tags allow-write - * @category File System - */ - export function mkdirSync(path: string | URL, options?: MkdirOptions): void; - - /** - * Options which can be set when using {@linkcode Deno.makeTempDir}, - * {@linkcode Deno.makeTempDirSync}, {@linkcode Deno.makeTempFile}, and - * {@linkcode Deno.makeTempFileSync}. - * - * @category File System */ - export interface MakeTempOptions { - /** Directory where the temporary directory should be created (defaults to - * the env variable `TMPDIR`, or the system's default, usually `/tmp`). - * - * Note that if the passed `dir` is relative, the path returned by - * `makeTempFile()` and `makeTempDir()` will also be relative. Be mindful of - * this when changing working directory. */ - dir?: string; - /** String that should precede the random portion of the temporary - * directory's name. */ - prefix?: string; - /** String that should follow the random portion of the temporary - * directory's name. */ - suffix?: string; - } - - /** Creates a new temporary directory in the default directory for temporary - * files, unless `dir` is specified. Other optional options include - * prefixing and suffixing the directory name with `prefix` and `suffix` - * respectively. - * - * This call resolves to the full path to the newly created directory. - * - * Multiple programs calling this function simultaneously will create different - * directories. It is the caller's responsibility to remove the directory when - * no longer needed. - * - * ```ts - * const tempDirName0 = await Deno.makeTempDir(); // e.g. /tmp/2894ea76 - * const tempDirName1 = await Deno.makeTempDir({ prefix: 'my_temp' }); // e.g. /tmp/my_temp339c944d - * ``` - * - * Requires `allow-write` permission. - * - * @tags allow-write - * @category File System - */ - // TODO(ry) Doesn't check permissions. - export function makeTempDir(options?: MakeTempOptions): Promise; - - /** Synchronously creates a new temporary directory in the default directory - * for temporary files, unless `dir` is specified. Other optional options - * include prefixing and suffixing the directory name with `prefix` and - * `suffix` respectively. - * - * The full path to the newly created directory is returned. - * - * Multiple programs calling this function simultaneously will create different - * directories. It is the caller's responsibility to remove the directory when - * no longer needed. - * - * ```ts - * const tempDirName0 = Deno.makeTempDirSync(); // e.g. /tmp/2894ea76 - * const tempDirName1 = Deno.makeTempDirSync({ prefix: 'my_temp' }); // e.g. /tmp/my_temp339c944d - * ``` - * - * Requires `allow-write` permission. - * - * @tags allow-write - * @category File System - */ - // TODO(ry) Doesn't check permissions. - export function makeTempDirSync(options?: MakeTempOptions): string; - - /** Creates a new temporary file in the default directory for temporary - * files, unless `dir` is specified. - * - * Other options include prefixing and suffixing the directory name with - * `prefix` and `suffix` respectively. - * - * This call resolves to the full path to the newly created file. - * - * Multiple programs calling this function simultaneously will create - * different files. It is the caller's responsibility to remove the file when - * no longer needed. - * - * ```ts - * const tmpFileName0 = await Deno.makeTempFile(); // e.g. /tmp/419e0bf2 - * const tmpFileName1 = await Deno.makeTempFile({ prefix: 'my_temp' }); // e.g. /tmp/my_temp754d3098 - * ``` - * - * Requires `allow-write` permission. - * - * @tags allow-write - * @category File System - */ - export function makeTempFile(options?: MakeTempOptions): Promise; - - /** Synchronously creates a new temporary file in the default directory for - * temporary files, unless `dir` is specified. - * - * Other options include prefixing and suffixing the directory name with - * `prefix` and `suffix` respectively. - * - * The full path to the newly created file is returned. - * - * Multiple programs calling this function simultaneously will create - * different files. It is the caller's responsibility to remove the file when - * no longer needed. - * - * ```ts - * const tempFileName0 = Deno.makeTempFileSync(); // e.g. /tmp/419e0bf2 - * const tempFileName1 = Deno.makeTempFileSync({ prefix: 'my_temp' }); // e.g. /tmp/my_temp754d3098 - * ``` - * - * Requires `allow-write` permission. - * - * @tags allow-write - * @category File System - */ - export function makeTempFileSync(options?: MakeTempOptions): string; - - /** Changes the permission of a specific file/directory of specified path. - * Ignores the process's umask. - * - * ```ts - * await Deno.chmod("/path/to/file", 0o666); - * ``` - * - * The mode is a sequence of 3 octal numbers. The first/left-most number - * specifies the permissions for the owner. The second number specifies the - * permissions for the group. The last/right-most number specifies the - * permissions for others. For example, with a mode of 0o764, the owner (7) - * can read/write/execute, the group (6) can read/write and everyone else (4) - * can read only. - * - * | Number | Description | - * | ------ | ----------- | - * | 7 | read, write, and execute | - * | 6 | read and write | - * | 5 | read and execute | - * | 4 | read only | - * | 3 | write and execute | - * | 2 | write only | - * | 1 | execute only | - * | 0 | no permission | - * - * NOTE: This API currently throws on Windows - * - * Requires `allow-write` permission. - * - * @tags allow-write - * @category File System - */ - export function chmod(path: string | URL, mode: number): Promise; - - /** Synchronously changes the permission of a specific file/directory of - * specified path. Ignores the process's umask. - * - * ```ts - * Deno.chmodSync("/path/to/file", 0o666); - * ``` - * - * For a full description, see {@linkcode Deno.chmod}. - * - * NOTE: This API currently throws on Windows - * - * Requires `allow-write` permission. - * - * @tags allow-write - * @category File System - */ - export function chmodSync(path: string | URL, mode: number): void; - - /** Change owner of a regular file or directory. - * - * This functionality is not available on Windows. - * - * ```ts - * await Deno.chown("myFile.txt", 1000, 1002); - * ``` - * - * Requires `allow-write` permission. - * - * Throws Error (not implemented) if executed on Windows. - * - * @tags allow-write - * @category File System - * - * @param path path to the file - * @param uid user id (UID) of the new owner, or `null` for no change - * @param gid group id (GID) of the new owner, or `null` for no change - */ - export function chown( - path: string | URL, - uid: number | null, - gid: number | null, - ): Promise; - - /** Synchronously change owner of a regular file or directory. - * - * This functionality is not available on Windows. - * - * ```ts - * Deno.chownSync("myFile.txt", 1000, 1002); - * ``` - * - * Requires `allow-write` permission. - * - * Throws Error (not implemented) if executed on Windows. - * - * @tags allow-write - * @category File System - * - * @param path path to the file - * @param uid user id (UID) of the new owner, or `null` for no change - * @param gid group id (GID) of the new owner, or `null` for no change - */ - export function chownSync( - path: string | URL, - uid: number | null, - gid: number | null, - ): void; - - /** - * Options which can be set when using {@linkcode Deno.remove} and - * {@linkcode Deno.removeSync}. - * - * @category File System */ - export interface RemoveOptions { - /** If set to `true`, path will be removed even if it's a non-empty directory. - * - * @default {false} */ - recursive?: boolean; - } - - /** Removes the named file or directory. - * - * ```ts - * await Deno.remove("/path/to/empty_dir/or/file"); - * await Deno.remove("/path/to/populated_dir/or/file", { recursive: true }); - * ``` - * - * Throws error if permission denied, path not found, or path is a non-empty - * directory and the `recursive` option isn't set to `true`. - * - * Requires `allow-write` permission. - * - * @tags allow-write - * @category File System - */ - export function remove( - path: string | URL, - options?: RemoveOptions, - ): Promise; - - /** Synchronously removes the named file or directory. - * - * ```ts - * Deno.removeSync("/path/to/empty_dir/or/file"); - * Deno.removeSync("/path/to/populated_dir/or/file", { recursive: true }); - * ``` - * - * Throws error if permission denied, path not found, or path is a non-empty - * directory and the `recursive` option isn't set to `true`. - * - * Requires `allow-write` permission. - * - * @tags allow-write - * @category File System - */ - export function removeSync(path: string | URL, options?: RemoveOptions): void; - - /** Synchronously renames (moves) `oldpath` to `newpath`. Paths may be files or - * directories. If `newpath` already exists and is not a directory, - * `renameSync()` replaces it. OS-specific restrictions may apply when - * `oldpath` and `newpath` are in different directories. - * - * ```ts - * Deno.renameSync("old/path", "new/path"); - * ``` - * - * On Unix-like OSes, this operation does not follow symlinks at either path. - * - * It varies between platforms when the operation throws errors, and if so what - * they are. It's always an error to rename anything to a non-empty directory. - * - * Requires `allow-read` and `allow-write` permissions. - * - * @tags allow-read, allow-write - * @category File System - */ - export function renameSync( - oldpath: string | URL, - newpath: string | URL, - ): void; - - /** Renames (moves) `oldpath` to `newpath`. Paths may be files or directories. - * If `newpath` already exists and is not a directory, `rename()` replaces it. - * OS-specific restrictions may apply when `oldpath` and `newpath` are in - * different directories. - * - * ```ts - * await Deno.rename("old/path", "new/path"); - * ``` - * - * On Unix-like OSes, this operation does not follow symlinks at either path. - * - * It varies between platforms when the operation throws errors, and if so - * what they are. It's always an error to rename anything to a non-empty - * directory. - * - * Requires `allow-read` and `allow-write` permissions. - * - * @tags allow-read, allow-write - * @category File System - */ - export function rename( - oldpath: string | URL, - newpath: string | URL, - ): Promise; - - /** Asynchronously reads and returns the entire contents of a file as an UTF-8 - * decoded string. Reading a directory throws an error. - * - * ```ts - * const data = await Deno.readTextFile("hello.txt"); - * console.log(data); - * ``` - * - * Requires `allow-read` permission. - * - * @tags allow-read - * @category File System - */ - export function readTextFile( - path: string | URL, - options?: ReadFileOptions, - ): Promise; - - /** Synchronously reads and returns the entire contents of a file as an UTF-8 - * decoded string. Reading a directory throws an error. - * - * ```ts - * const data = Deno.readTextFileSync("hello.txt"); - * console.log(data); - * ``` - * - * Requires `allow-read` permission. - * - * @tags allow-read - * @category File System - */ - export function readTextFileSync(path: string | URL): string; - - /** Reads and resolves to the entire contents of a file as an array of bytes. - * `TextDecoder` can be used to transform the bytes to string if required. - * Reading a directory returns an empty data array. - * - * ```ts - * const decoder = new TextDecoder("utf-8"); - * const data = await Deno.readFile("hello.txt"); - * console.log(decoder.decode(data)); - * ``` - * - * Requires `allow-read` permission. - * - * @tags allow-read - * @category File System - */ - export function readFile( - path: string | URL, - options?: ReadFileOptions, - ): Promise; - - /** Synchronously reads and returns the entire contents of a file as an array - * of bytes. `TextDecoder` can be used to transform the bytes to string if - * required. Reading a directory returns an empty data array. - * - * ```ts - * const decoder = new TextDecoder("utf-8"); - * const data = Deno.readFileSync("hello.txt"); - * console.log(decoder.decode(data)); - * ``` - * - * Requires `allow-read` permission. - * - * @tags allow-read - * @category File System - */ - export function readFileSync(path: string | URL): Uint8Array; - - /** Provides information about a file and is returned by - * {@linkcode Deno.stat}, {@linkcode Deno.lstat}, {@linkcode Deno.statSync}, - * and {@linkcode Deno.lstatSync} or from calling `stat()` and `statSync()` - * on an {@linkcode Deno.FsFile} instance. - * - * @category File System - */ - export interface FileInfo { - /** True if this is info for a regular file. Mutually exclusive to - * `FileInfo.isDirectory` and `FileInfo.isSymlink`. */ - isFile: boolean; - /** True if this is info for a regular directory. Mutually exclusive to - * `FileInfo.isFile` and `FileInfo.isSymlink`. */ - isDirectory: boolean; - /** True if this is info for a symlink. Mutually exclusive to - * `FileInfo.isFile` and `FileInfo.isDirectory`. */ - isSymlink: boolean; - /** The size of the file, in bytes. */ - size: number; - /** The last modification time of the file. This corresponds to the `mtime` - * field from `stat` on Linux/Mac OS and `ftLastWriteTime` on Windows. This - * may not be available on all platforms. */ - mtime: Date | null; - /** The last access time of the file. This corresponds to the `atime` - * field from `stat` on Unix and `ftLastAccessTime` on Windows. This may not - * be available on all platforms. */ - atime: Date | null; - /** The creation time of the file. This corresponds to the `birthtime` - * field from `stat` on Mac/BSD and `ftCreationTime` on Windows. This may - * not be available on all platforms. */ - birthtime: Date | null; - /** ID of the device containing the file. */ - dev: number; - /** Inode number. - * - * _Linux/Mac OS only._ */ - ino: number | null; - /** The underlying raw `st_mode` bits that contain the standard Unix - * permissions for this file/directory. - * - * _Linux/Mac OS only._ */ - mode: number | null; - /** Number of hard links pointing to this file. - * - * _Linux/Mac OS only._ */ - nlink: number | null; - /** User ID of the owner of this file. - * - * _Linux/Mac OS only._ */ - uid: number | null; - /** Group ID of the owner of this file. - * - * _Linux/Mac OS only._ */ - gid: number | null; - /** Device ID of this file. - * - * _Linux/Mac OS only._ */ - rdev: number | null; - /** Blocksize for filesystem I/O. - * - * _Linux/Mac OS only._ */ - blksize: number | null; - /** Number of blocks allocated to the file, in 512-byte units. - * - * _Linux/Mac OS only._ */ - blocks: number | null; - /** True if this is info for a block device. - * - * _Linux/Mac OS only._ */ - isBlockDevice: boolean | null; - /** True if this is info for a char device. - * - * _Linux/Mac OS only._ */ - isCharDevice: boolean | null; - /** True if this is info for a fifo. - * - * _Linux/Mac OS only._ */ - isFifo: boolean | null; - /** True if this is info for a socket. - * - * _Linux/Mac OS only._ */ - isSocket: boolean | null; - } - - /** Resolves to the absolute normalized path, with symbolic links resolved. - * - * ```ts - * // e.g. given /home/alice/file.txt and current directory /home/alice - * await Deno.symlink("file.txt", "symlink_file.txt"); - * const realPath = await Deno.realPath("./file.txt"); - * const realSymLinkPath = await Deno.realPath("./symlink_file.txt"); - * console.log(realPath); // outputs "/home/alice/file.txt" - * console.log(realSymLinkPath); // outputs "/home/alice/file.txt" - * ``` - * - * Requires `allow-read` permission for the target path. - * - * Also requires `allow-read` permission for the `CWD` if the target path is - * relative. - * - * @tags allow-read - * @category File System - */ - export function realPath(path: string | URL): Promise; - - /** Synchronously returns absolute normalized path, with symbolic links - * resolved. - * - * ```ts - * // e.g. given /home/alice/file.txt and current directory /home/alice - * Deno.symlinkSync("file.txt", "symlink_file.txt"); - * const realPath = Deno.realPathSync("./file.txt"); - * const realSymLinkPath = Deno.realPathSync("./symlink_file.txt"); - * console.log(realPath); // outputs "/home/alice/file.txt" - * console.log(realSymLinkPath); // outputs "/home/alice/file.txt" - * ``` - * - * Requires `allow-read` permission for the target path. - * - * Also requires `allow-read` permission for the `CWD` if the target path is - * relative. - * - * @tags allow-read - * @category File System - */ - export function realPathSync(path: string | URL): string; - - /** - * Information about a directory entry returned from {@linkcode Deno.readDir} - * and {@linkcode Deno.readDirSync}. - * - * @category File System */ - export interface DirEntry { - /** The file name of the entry. It is just the entity name and does not - * include the full path. */ - name: string; - /** True if this is info for a regular file. Mutually exclusive to - * `DirEntry.isDirectory` and `DirEntry.isSymlink`. */ - isFile: boolean; - /** True if this is info for a regular directory. Mutually exclusive to - * `DirEntry.isFile` and `DirEntry.isSymlink`. */ - isDirectory: boolean; - /** True if this is info for a symlink. Mutually exclusive to - * `DirEntry.isFile` and `DirEntry.isDirectory`. */ - isSymlink: boolean; - } - - /** Reads the directory given by `path` and returns an async iterable of - * {@linkcode Deno.DirEntry}. The order of entries is not guaranteed. - * - * ```ts - * for await (const dirEntry of Deno.readDir("/")) { - * console.log(dirEntry.name); - * } - * ``` - * - * Throws error if `path` is not a directory. - * - * Requires `allow-read` permission. - * - * @tags allow-read - * @category File System - */ - export function readDir(path: string | URL): AsyncIterable; - - /** Synchronously reads the directory given by `path` and returns an iterable - * of {@linkcode Deno.DirEntry}. The order of entries is not guaranteed. - * - * ```ts - * for (const dirEntry of Deno.readDirSync("/")) { - * console.log(dirEntry.name); - * } - * ``` - * - * Throws error if `path` is not a directory. - * - * Requires `allow-read` permission. - * - * @tags allow-read - * @category File System - */ - export function readDirSync(path: string | URL): Iterable; - - /** Copies the contents and permissions of one file to another specified path, - * by default creating a new file if needed, else overwriting. Fails if target - * path is a directory or is unwritable. - * - * ```ts - * await Deno.copyFile("from.txt", "to.txt"); - * ``` - * - * Requires `allow-read` permission on `fromPath`. - * - * Requires `allow-write` permission on `toPath`. - * - * @tags allow-read, allow-write - * @category File System - */ - export function copyFile( - fromPath: string | URL, - toPath: string | URL, - ): Promise; - - /** Synchronously copies the contents and permissions of one file to another - * specified path, by default creating a new file if needed, else overwriting. - * Fails if target path is a directory or is unwritable. - * - * ```ts - * Deno.copyFileSync("from.txt", "to.txt"); - * ``` - * - * Requires `allow-read` permission on `fromPath`. - * - * Requires `allow-write` permission on `toPath`. - * - * @tags allow-read, allow-write - * @category File System - */ - export function copyFileSync( - fromPath: string | URL, - toPath: string | URL, - ): void; - - /** Resolves to the full path destination of the named symbolic link. - * - * ```ts - * await Deno.symlink("./test.txt", "./test_link.txt"); - * const target = await Deno.readLink("./test_link.txt"); // full path of ./test.txt - * ``` - * - * Throws TypeError if called with a hard link. - * - * Requires `allow-read` permission. - * - * @tags allow-read - * @category File System - */ - export function readLink(path: string | URL): Promise; - - /** Synchronously returns the full path destination of the named symbolic - * link. - * - * ```ts - * Deno.symlinkSync("./test.txt", "./test_link.txt"); - * const target = Deno.readLinkSync("./test_link.txt"); // full path of ./test.txt - * ``` - * - * Throws TypeError if called with a hard link. - * - * Requires `allow-read` permission. - * - * @tags allow-read - * @category File System - */ - export function readLinkSync(path: string | URL): string; - - /** Resolves to a {@linkcode Deno.FileInfo} for the specified `path`. If - * `path` is a symlink, information for the symlink will be returned instead - * of what it points to. - * - * ```ts - * import { assert } from "jsr:@std/assert"; - * const fileInfo = await Deno.lstat("hello.txt"); - * assert(fileInfo.isFile); - * ``` - * - * Requires `allow-read` permission. - * - * @tags allow-read - * @category File System - */ - export function lstat(path: string | URL): Promise; - - /** Synchronously returns a {@linkcode Deno.FileInfo} for the specified - * `path`. If `path` is a symlink, information for the symlink will be - * returned instead of what it points to. - * - * ```ts - * import { assert } from "jsr:@std/assert"; - * const fileInfo = Deno.lstatSync("hello.txt"); - * assert(fileInfo.isFile); - * ``` - * - * Requires `allow-read` permission. - * - * @tags allow-read - * @category File System - */ - export function lstatSync(path: string | URL): FileInfo; - - /** Resolves to a {@linkcode Deno.FileInfo} for the specified `path`. Will - * always follow symlinks. - * - * ```ts - * import { assert } from "jsr:@std/assert"; - * const fileInfo = await Deno.stat("hello.txt"); - * assert(fileInfo.isFile); - * ``` - * - * Requires `allow-read` permission. - * - * @tags allow-read - * @category File System - */ - export function stat(path: string | URL): Promise; - - /** Synchronously returns a {@linkcode Deno.FileInfo} for the specified - * `path`. Will always follow symlinks. - * - * ```ts - * import { assert } from "jsr:@std/assert"; - * const fileInfo = Deno.statSync("hello.txt"); - * assert(fileInfo.isFile); - * ``` - * - * Requires `allow-read` permission. - * - * @tags allow-read - * @category File System - */ - export function statSync(path: string | URL): FileInfo; - - /** Options for writing to a file. - * - * @category File System - */ - export interface WriteFileOptions { - /** If set to `true`, will append to a file instead of overwriting previous - * contents. - * - * @default {false} */ - append?: boolean; - /** Sets the option to allow creating a new file, if one doesn't already - * exist at the specified path. - * - * @default {true} */ - create?: boolean; - /** If set to `true`, no file, directory, or symlink is allowed to exist at - * the target location. When createNew is set to `true`, `create` is ignored. - * - * @default {false} */ - createNew?: boolean; - /** Permissions always applied to file. */ - mode?: number; - /** An abort signal to allow cancellation of the file write operation. - * - * If the signal becomes aborted the write file operation will be stopped - * and the promise returned will be rejected with an {@linkcode AbortError}. - */ - signal?: AbortSignal; - } - - /** Write `data` to the given `path`, by default creating a new file if - * needed, else overwriting. - * - * ```ts - * const encoder = new TextEncoder(); - * const data = encoder.encode("Hello world\n"); - * await Deno.writeFile("hello1.txt", data); // overwrite "hello1.txt" or create it - * await Deno.writeFile("hello2.txt", data, { create: false }); // only works if "hello2.txt" exists - * await Deno.writeFile("hello3.txt", data, { mode: 0o777 }); // set permissions on new file - * await Deno.writeFile("hello4.txt", data, { append: true }); // add data to the end of the file - * ``` - * - * Requires `allow-write` permission, and `allow-read` if `options.create` is - * `false`. - * - * @tags allow-read, allow-write - * @category File System - */ - export function writeFile( - path: string | URL, - data: Uint8Array | ReadableStream, - options?: WriteFileOptions, - ): Promise; - - /** Synchronously write `data` to the given `path`, by default creating a new - * file if needed, else overwriting. - * - * ```ts - * const encoder = new TextEncoder(); - * const data = encoder.encode("Hello world\n"); - * Deno.writeFileSync("hello1.txt", data); // overwrite "hello1.txt" or create it - * Deno.writeFileSync("hello2.txt", data, { create: false }); // only works if "hello2.txt" exists - * Deno.writeFileSync("hello3.txt", data, { mode: 0o777 }); // set permissions on new file - * Deno.writeFileSync("hello4.txt", data, { append: true }); // add data to the end of the file - * ``` - * - * Requires `allow-write` permission, and `allow-read` if `options.create` is - * `false`. - * - * @tags allow-read, allow-write - * @category File System - */ - export function writeFileSync( - path: string | URL, - data: Uint8Array, - options?: WriteFileOptions, - ): void; - - /** Write string `data` to the given `path`, by default creating a new file if - * needed, else overwriting. - * - * ```ts - * await Deno.writeTextFile("hello1.txt", "Hello world\n"); // overwrite "hello1.txt" or create it - * ``` - * - * Requires `allow-write` permission, and `allow-read` if `options.create` is - * `false`. - * - * @tags allow-read, allow-write - * @category File System - */ - export function writeTextFile( - path: string | URL, - data: string | ReadableStream, - options?: WriteFileOptions, - ): Promise; - - /** Synchronously write string `data` to the given `path`, by default creating - * a new file if needed, else overwriting. - * - * ```ts - * Deno.writeTextFileSync("hello1.txt", "Hello world\n"); // overwrite "hello1.txt" or create it - * ``` - * - * Requires `allow-write` permission, and `allow-read` if `options.create` is - * `false`. - * - * @tags allow-read, allow-write - * @category File System - */ - export function writeTextFileSync( - path: string | URL, - data: string, - options?: WriteFileOptions, - ): void; - - /** Truncates (or extends) the specified file, to reach the specified `len`. - * If `len` is not specified then the entire file contents are truncated. - * - * ### Truncate the entire file - * ```ts - * await Deno.truncate("my_file.txt"); - * ``` - * - * ### Truncate part of the file - * - * ```ts - * const file = await Deno.makeTempFile(); - * await Deno.writeTextFile(file, "Hello World"); - * await Deno.truncate(file, 7); - * const data = await Deno.readFile(file); - * console.log(new TextDecoder().decode(data)); // "Hello W" - * ``` - * - * Requires `allow-write` permission. - * - * @tags allow-write - * @category File System - */ - export function truncate(name: string, len?: number): Promise; - - /** Synchronously truncates (or extends) the specified file, to reach the - * specified `len`. If `len` is not specified then the entire file contents - * are truncated. - * - * ### Truncate the entire file - * - * ```ts - * Deno.truncateSync("my_file.txt"); - * ``` - * - * ### Truncate part of the file - * - * ```ts - * const file = Deno.makeTempFileSync(); - * Deno.writeFileSync(file, new TextEncoder().encode("Hello World")); - * Deno.truncateSync(file, 7); - * const data = Deno.readFileSync(file); - * console.log(new TextDecoder().decode(data)); - * ``` - * - * Requires `allow-write` permission. - * - * @tags allow-write - * @category File System - */ - export function truncateSync(name: string, len?: number): void; - - /** @category Observability - * - * @deprecated This will be removed in Deno 2.0. - */ - export interface OpMetrics { - opsDispatched: number; - opsDispatchedSync: number; - opsDispatchedAsync: number; - opsDispatchedAsyncUnref: number; - opsCompleted: number; - opsCompletedSync: number; - opsCompletedAsync: number; - opsCompletedAsyncUnref: number; - bytesSentControl: number; - bytesSentData: number; - bytesReceived: number; - } - - /** @category Observability - * - * @deprecated This will be removed in Deno 2.0. - */ - export interface Metrics extends OpMetrics { - ops: Record; - } - - /** Receive metrics from the privileged side of Deno. This is primarily used - * in the development of Deno. _Ops_, also called _bindings_, are the - * go-between between Deno JavaScript sandbox and the rest of Deno. - * - * ```shell - * > console.table(Deno.metrics()) - * ┌─────────────────────────┬────────┐ - * │ (index) │ Values │ - * ├─────────────────────────┼────────┤ - * │ opsDispatched │ 3 │ - * │ opsDispatchedSync │ 2 │ - * │ opsDispatchedAsync │ 1 │ - * │ opsDispatchedAsyncUnref │ 0 │ - * │ opsCompleted │ 3 │ - * │ opsCompletedSync │ 2 │ - * │ opsCompletedAsync │ 1 │ - * │ opsCompletedAsyncUnref │ 0 │ - * │ bytesSentControl │ 73 │ - * │ bytesSentData │ 0 │ - * │ bytesReceived │ 375 │ - * └─────────────────────────┴────────┘ - * ``` - * - * @category Observability - * - * @deprecated This will be removed in Deno 2.0. - */ - export function metrics(): Metrics; - - /** - * A map of open resources that Deno is tracking. The key is the resource ID - * (_rid_) and the value is its representation. - * - * @deprecated This will be removed in Deno 2.0. - * - * @category Observability */ - interface ResourceMap { - [rid: number]: unknown; - } - - /** Returns a map of open resource IDs (_rid_) along with their string - * representations. This is an internal API and as such resource - * representation has `unknown` type; that means it can change any time and - * should not be depended upon. - * - * ```ts - * console.log(Deno.resources()); - * // { 0: "stdin", 1: "stdout", 2: "stderr" } - * Deno.openSync('../test.file'); - * console.log(Deno.resources()); - * // { 0: "stdin", 1: "stdout", 2: "stderr", 3: "fsFile" } - * ``` - * - * @deprecated This will be removed in Deno 2.0. - * - * @category Observability - */ - export function resources(): ResourceMap; - - /** - * Additional information for FsEvent objects with the "other" kind. - * - * - `"rescan"`: rescan notices indicate either a lapse in the events or a - * change in the filesystem such that events received so far can no longer - * be relied on to represent the state of the filesystem now. An - * application that simply reacts to file changes may not care about this. - * An application that keeps an in-memory representation of the filesystem - * will need to care, and will need to refresh that representation directly - * from the filesystem. - * - * @category File System - */ - export type FsEventFlag = "rescan"; - - /** - * Represents a unique file system event yielded by a - * {@linkcode Deno.FsWatcher}. - * - * @category File System */ - export interface FsEvent { - /** The kind/type of the file system event. */ - kind: "any" | "access" | "create" | "modify" | "remove" | "other"; - /** An array of paths that are associated with the file system event. */ - paths: string[]; - /** Any additional flags associated with the event. */ - flag?: FsEventFlag; - } - - /** - * Returned by {@linkcode Deno.watchFs}. It is an async iterator yielding up - * system events. To stop watching the file system by calling `.close()` - * method. - * - * @category File System - */ - export interface FsWatcher extends AsyncIterable, Disposable { - /** - * The resource id. - * - * @deprecated This will be removed in Deno 2.0. See the - * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide} - * for migration instructions. - */ - readonly rid: number; - /** Stops watching the file system and closes the watcher resource. */ - close(): void; - /** - * Stops watching the file system and closes the watcher resource. - * - * @deprecated This will be removed in Deno 2.0. See the - * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide} - * for migration instructions. - */ - return?(value?: any): Promise>; - [Symbol.asyncIterator](): AsyncIterableIterator; - } - - /** Watch for file system events against one or more `paths`, which can be - * files or directories. These paths must exist already. One user action (e.g. - * `touch test.file`) can generate multiple file system events. Likewise, - * one user action can result in multiple file paths in one event (e.g. `mv - * old_name.txt new_name.txt`). - * - * The recursive option is `true` by default and, for directories, will watch - * the specified directory and all sub directories. - * - * Note that the exact ordering of the events can vary between operating - * systems. - * - * ```ts - * const watcher = Deno.watchFs("/"); - * for await (const event of watcher) { - * console.log(">>>> event", event); - * // { kind: "create", paths: [ "/foo.txt" ] } - * } - * ``` - * - * Call `watcher.close()` to stop watching. - * - * ```ts - * const watcher = Deno.watchFs("/"); - * - * setTimeout(() => { - * watcher.close(); - * }, 5000); - * - * for await (const event of watcher) { - * console.log(">>>> event", event); - * } - * ``` - * - * Requires `allow-read` permission. - * - * @tags allow-read - * @category File System - */ - export function watchFs( - paths: string | string[], - options?: { recursive: boolean }, - ): FsWatcher; - - /** - * Options which can be used with {@linkcode Deno.run}. - * - * @deprecated This will be removed in Deno 2.0. See the - * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide} - * for migration instructions. - * - * @category Sub Process */ - export interface RunOptions { - /** Arguments to pass. - * - * _Note_: the first element needs to be a path to the executable that is - * being run. */ - cmd: readonly string[] | [string | URL, ...string[]]; - /** The current working directory that should be used when running the - * sub-process. */ - cwd?: string; - /** Any environment variables to be set when running the sub-process. */ - env?: Record; - /** By default subprocess inherits `stdout` of parent process. To change - * this this option can be set to a resource ID (_rid_) of an open file, - * `"inherit"`, `"piped"`, or `"null"`: - * - * - _number_: the resource ID of an open file/resource. This allows you to - * write to a file. - * - `"inherit"`: The default if unspecified. The subprocess inherits from the - * parent. - * - `"piped"`: A new pipe should be arranged to connect the parent and child - * sub-process. - * - `"null"`: This stream will be ignored. This is the equivalent of attaching - * the stream to `/dev/null`. - */ - stdout?: "inherit" | "piped" | "null" | number; - /** By default subprocess inherits `stderr` of parent process. To change - * this this option can be set to a resource ID (_rid_) of an open file, - * `"inherit"`, `"piped"`, or `"null"`: - * - * - _number_: the resource ID of an open file/resource. This allows you to - * write to a file. - * - `"inherit"`: The default if unspecified. The subprocess inherits from the - * parent. - * - `"piped"`: A new pipe should be arranged to connect the parent and child - * sub-process. - * - `"null"`: This stream will be ignored. This is the equivalent of attaching - * the stream to `/dev/null`. - */ - stderr?: "inherit" | "piped" | "null" | number; - /** By default subprocess inherits `stdin` of parent process. To change - * this this option can be set to a resource ID (_rid_) of an open file, - * `"inherit"`, `"piped"`, or `"null"`: - * - * - _number_: the resource ID of an open file/resource. This allows you to - * read from a file. - * - `"inherit"`: The default if unspecified. The subprocess inherits from the - * parent. - * - `"piped"`: A new pipe should be arranged to connect the parent and child - * sub-process. - * - `"null"`: This stream will be ignored. This is the equivalent of attaching - * the stream to `/dev/null`. - */ - stdin?: "inherit" | "piped" | "null" | number; - } - - /** - * The status resolved from the `.status()` method of a - * {@linkcode Deno.Process} instance. - * - * If `success` is `true`, then `code` will be `0`, but if `success` is - * `false`, the sub-process exit code will be set in `code`. - * - * @deprecated This will be removed in Deno 2.0. See the - * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide} - * for migration instructions. - * - * @category Sub Process */ - export type ProcessStatus = - | { - success: true; - code: 0; - signal?: undefined; - } - | { - success: false; - code: number; - signal?: number; - }; - - /** - * Represents an instance of a sub process that is returned from - * {@linkcode Deno.run} which can be used to manage the sub-process. - * - * @deprecated This will be removed in Deno 2.0. See the - * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide} - * for migration instructions. - * - * @category Sub Process */ - export class Process { - /** The resource ID of the sub-process. */ - readonly rid: number; - /** The operating system's process ID for the sub-process. */ - readonly pid: number; - /** A reference to the sub-processes `stdin`, which allows interacting with - * the sub-process at a low level. */ - readonly stdin: T["stdin"] extends "piped" ? Writer & Closer & { - writable: WritableStream; - } - : (Writer & Closer & { writable: WritableStream }) | null; - /** A reference to the sub-processes `stdout`, which allows interacting with - * the sub-process at a low level. */ - readonly stdout: T["stdout"] extends "piped" ? Reader & Closer & { - readable: ReadableStream; - } - : (Reader & Closer & { readable: ReadableStream }) | null; - /** A reference to the sub-processes `stderr`, which allows interacting with - * the sub-process at a low level. */ - readonly stderr: T["stderr"] extends "piped" ? Reader & Closer & { - readable: ReadableStream; - } - : (Reader & Closer & { readable: ReadableStream }) | null; - /** Wait for the process to exit and return its exit status. - * - * Calling this function multiple times will return the same status. - * - * The `stdin` reference to the process will be closed before waiting to - * avoid a deadlock. - * - * If `stdout` and/or `stderr` were set to `"piped"`, they must be closed - * manually before the process can exit. - * - * To run process to completion and collect output from both `stdout` and - * `stderr` use: - * - * ```ts - * const p = Deno.run({ cmd: [ "echo", "hello world" ], stderr: 'piped', stdout: 'piped' }); - * const [status, stdout, stderr] = await Promise.all([ - * p.status(), - * p.output(), - * p.stderrOutput() - * ]); - * p.close(); - * ``` - */ - status(): Promise; - /** Buffer the stdout until EOF and return it as `Uint8Array`. - * - * You must set `stdout` to `"piped"` when creating the process. - * - * This calls `close()` on stdout after its done. */ - output(): Promise; - /** Buffer the stderr until EOF and return it as `Uint8Array`. - * - * You must set `stderr` to `"piped"` when creating the process. - * - * This calls `close()` on stderr after its done. */ - stderrOutput(): Promise; - /** Clean up resources associated with the sub-process instance. */ - close(): void; - /** Send a signal to process. - * Default signal is `"SIGTERM"`. - * - * ```ts - * const p = Deno.run({ cmd: [ "sleep", "20" ]}); - * p.kill("SIGTERM"); - * p.close(); - * ``` - */ - kill(signo?: Signal): void; - } - - /** Operating signals which can be listened for or sent to sub-processes. What - * signals and what their standard behaviors are OS dependent. - * - * @category Runtime Environment */ - export type Signal = - | "SIGABRT" - | "SIGALRM" - | "SIGBREAK" - | "SIGBUS" - | "SIGCHLD" - | "SIGCONT" - | "SIGEMT" - | "SIGFPE" - | "SIGHUP" - | "SIGILL" - | "SIGINFO" - | "SIGINT" - | "SIGIO" - | "SIGKILL" - | "SIGPIPE" - | "SIGPROF" - | "SIGPWR" - | "SIGQUIT" - | "SIGSEGV" - | "SIGSTKFLT" - | "SIGSTOP" - | "SIGSYS" - | "SIGTERM" - | "SIGTRAP" - | "SIGTSTP" - | "SIGTTIN" - | "SIGTTOU" - | "SIGURG" - | "SIGUSR1" - | "SIGUSR2" - | "SIGVTALRM" - | "SIGWINCH" - | "SIGXCPU" - | "SIGXFSZ"; - - /** Registers the given function as a listener of the given signal event. - * - * ```ts - * Deno.addSignalListener( - * "SIGTERM", - * () => { - * console.log("SIGTERM!") - * } - * ); - * ``` - * - * _Note_: On Windows only `"SIGINT"` (CTRL+C) and `"SIGBREAK"` (CTRL+Break) - * are supported. - * - * @category Runtime Environment - */ - export function addSignalListener(signal: Signal, handler: () => void): void; - - /** Removes the given signal listener that has been registered with - * {@linkcode Deno.addSignalListener}. - * - * ```ts - * const listener = () => { - * console.log("SIGTERM!") - * }; - * Deno.addSignalListener("SIGTERM", listener); - * Deno.removeSignalListener("SIGTERM", listener); - * ``` - * - * _Note_: On Windows only `"SIGINT"` (CTRL+C) and `"SIGBREAK"` (CTRL+Break) - * are supported. - * - * @category Runtime Environment - */ - export function removeSignalListener( - signal: Signal, - handler: () => void, - ): void; - - /** - * Spawns new subprocess. RunOptions must contain at a minimum the `opt.cmd`, - * an array of program arguments, the first of which is the binary. - * - * ```ts - * const p = Deno.run({ - * cmd: ["curl", "https://example.com"], - * }); - * const status = await p.status(); - * ``` - * - * Subprocess uses same working directory as parent process unless `opt.cwd` - * is specified. - * - * Environmental variables from parent process can be cleared using `opt.clearEnv`. - * Doesn't guarantee that only `opt.env` variables are present, - * as the OS may set environmental variables for processes. - * - * Environmental variables for subprocess can be specified using `opt.env` - * mapping. - * - * `opt.uid` sets the child process’s user ID. This translates to a setuid call - * in the child process. Failure in the setuid call will cause the spawn to fail. - * - * `opt.gid` is similar to `opt.uid`, but sets the group ID of the child process. - * This has the same semantics as the uid field. - * - * By default subprocess inherits stdio of parent process. To change - * this this, `opt.stdin`, `opt.stdout`, and `opt.stderr` can be set - * independently to a resource ID (_rid_) of an open file, `"inherit"`, - * `"piped"`, or `"null"`: - * - * - _number_: the resource ID of an open file/resource. This allows you to - * read or write to a file. - * - `"inherit"`: The default if unspecified. The subprocess inherits from the - * parent. - * - `"piped"`: A new pipe should be arranged to connect the parent and child - * sub-process. - * - `"null"`: This stream will be ignored. This is the equivalent of attaching - * the stream to `/dev/null`. - * - * Details of the spawned process are returned as an instance of - * {@linkcode Deno.Process}. - * - * Requires `allow-run` permission. - * - * @deprecated This will be soft-removed in Deno 2.0. See the - * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide} - * for migration instructions. - * - * @tags allow-run - * @category Sub Process - */ - export function run(opt: T): Process; - - /** Create a child process. - * - * If any stdio options are not set to `"piped"`, accessing the corresponding - * field on the `Command` or its `CommandOutput` will throw a `TypeError`. - * - * If `stdin` is set to `"piped"`, the `stdin` {@linkcode WritableStream} - * needs to be closed manually. - * - * @example Spawn a subprocess and pipe the output to a file - * - * ```ts - * const command = new Deno.Command(Deno.execPath(), { - * args: [ - * "eval", - * "console.log('Hello World')", - * ], - * stdin: "piped", - * stdout: "piped", - * }); - * const child = command.spawn(); - * - * // open a file and pipe the subprocess output to it. - * child.stdout.pipeTo( - * Deno.openSync("output", { write: true, create: true }).writable, - * ); - * - * // manually close stdin - * child.stdin.close(); - * const status = await child.status; - * ``` - * - * @example Spawn a subprocess and collect its output - * - * ```ts - * const command = new Deno.Command(Deno.execPath(), { - * args: [ - * "eval", - * "console.log('hello'); console.error('world')", - * ], - * }); - * const { code, stdout, stderr } = await command.output(); - * console.assert(code === 0); - * console.assert("hello\n" === new TextDecoder().decode(stdout)); - * console.assert("world\n" === new TextDecoder().decode(stderr)); - * ``` - * - * @example Spawn a subprocess and collect its output synchronously - * - * ```ts - * const command = new Deno.Command(Deno.execPath(), { - * args: [ - * "eval", - * "console.log('hello'); console.error('world')", - * ], - * }); - * const { code, stdout, stderr } = command.outputSync(); - * console.assert(code === 0); - * console.assert("hello\n" === new TextDecoder().decode(stdout)); - * console.assert("world\n" === new TextDecoder().decode(stderr)); - * ``` - * - * @tags allow-run - * @category Sub Process - */ - export class Command { - constructor(command: string | URL, options?: CommandOptions); - /** - * Executes the {@linkcode Deno.Command}, waiting for it to finish and - * collecting all of its output. - * If `spawn()` was called, calling this function will collect the remaining - * output. - * - * Will throw an error if `stdin: "piped"` is set. - * - * If options `stdout` or `stderr` are not set to `"piped"`, accessing the - * corresponding field on {@linkcode Deno.CommandOutput} will throw a `TypeError`. - */ - output(): Promise; - /** - * Synchronously executes the {@linkcode Deno.Command}, waiting for it to - * finish and collecting all of its output. - * - * Will throw an error if `stdin: "piped"` is set. - * - * If options `stdout` or `stderr` are not set to `"piped"`, accessing the - * corresponding field on {@linkcode Deno.CommandOutput} will throw a `TypeError`. - */ - outputSync(): CommandOutput; - /** - * Spawns a streamable subprocess, allowing to use the other methods. - */ - spawn(): ChildProcess; - } - - /** - * The interface for handling a child process returned from - * {@linkcode Deno.Command.spawn}. - * - * @category Sub Process - */ - export class ChildProcess implements AsyncDisposable { - get stdin(): WritableStream; - get stdout(): ReadableStream; - get stderr(): ReadableStream; - readonly pid: number; - /** Get the status of the child. */ - readonly status: Promise; - - /** Waits for the child to exit completely, returning all its output and - * status. */ - output(): Promise; - /** Kills the process with given {@linkcode Deno.Signal}. - * - * Defaults to `SIGTERM` if no signal is provided. - * - * @param [signo="SIGTERM"] - */ - kill(signo?: Signal): void; - - /** Ensure that the status of the child process prevents the Deno process - * from exiting. */ - ref(): void; - /** Ensure that the status of the child process does not block the Deno - * process from exiting. */ - unref(): void; - - [Symbol.asyncDispose](): Promise; - } - - /** - * Options which can be set when calling {@linkcode Deno.Command}. - * - * @category Sub Process - */ - export interface CommandOptions { - /** Arguments to pass to the process. */ - args?: string[]; - /** - * The working directory of the process. - * - * If not specified, the `cwd` of the parent process is used. - */ - cwd?: string | URL; - /** - * Clear environmental variables from parent process. - * - * Doesn't guarantee that only `env` variables are present, as the OS may - * set environmental variables for processes. - * - * @default {false} - */ - clearEnv?: boolean; - /** Environmental variables to pass to the subprocess. */ - env?: Record; - /** - * Sets the child process’s user ID. This translates to a setuid call in the - * child process. Failure in the set uid call will cause the spawn to fail. - */ - uid?: number; - /** Similar to `uid`, but sets the group ID of the child process. */ - gid?: number; - /** - * An {@linkcode AbortSignal} that allows closing the process using the - * corresponding {@linkcode AbortController} by sending the process a - * SIGTERM signal. - * - * Not supported in {@linkcode Deno.Command.outputSync}. - */ - signal?: AbortSignal; - - /** How `stdin` of the spawned process should be handled. - * - * Defaults to `"inherit"` for `output` & `outputSync`, - * and `"inherit"` for `spawn`. */ - stdin?: "piped" | "inherit" | "null"; - /** How `stdout` of the spawned process should be handled. - * - * Defaults to `"piped"` for `output` & `outputSync`, - * and `"inherit"` for `spawn`. */ - stdout?: "piped" | "inherit" | "null"; - /** How `stderr` of the spawned process should be handled. - * - * Defaults to `"piped"` for `output` & `outputSync`, - * and `"inherit"` for `spawn`. */ - stderr?: "piped" | "inherit" | "null"; - - /** Skips quoting and escaping of the arguments on windows. This option - * is ignored on non-windows platforms. - * - * @default {false} */ - windowsRawArguments?: boolean; - } - - /** - * @category Sub Process - */ - export interface CommandStatus { - /** If the child process exits with a 0 status code, `success` will be set - * to `true`, otherwise `false`. */ - success: boolean; - /** The exit code of the child process. */ - code: number; - /** The signal associated with the child process. */ - signal: Signal | null; - } - - /** - * The interface returned from calling {@linkcode Deno.Command.output} or - * {@linkcode Deno.Command.outputSync} which represents the result of spawning the - * child process. - * - * @category Sub Process - */ - export interface CommandOutput extends CommandStatus { - /** The buffered output from the child process' `stdout`. */ - readonly stdout: Uint8Array; - /** The buffered output from the child process' `stderr`. */ - readonly stderr: Uint8Array; - } - - /** Option which can be specified when performing {@linkcode Deno.inspect}. - * - * @category Console and Debugging */ - export interface InspectOptions { - /** Stylize output with ANSI colors. - * - * @default {false} */ - colors?: boolean; - /** Try to fit more than one entry of a collection on the same line. - * - * @default {true} */ - compact?: boolean; - /** Traversal depth for nested objects. - * - * @default {4} */ - depth?: number; - /** The maximum length for an inspection to take up a single line. - * - * @default {80} */ - breakLength?: number; - /** Whether or not to escape sequences. - * - * @default {true} */ - escapeSequences?: boolean; - /** The maximum number of iterable entries to print. - * - * @default {100} */ - iterableLimit?: number; - /** Show a Proxy's target and handler. - * - * @default {false} */ - showProxy?: boolean; - /** Sort Object, Set and Map entries by key. - * - * @default {false} */ - sorted?: boolean; - /** Add a trailing comma for multiline collections. - * - * @default {false} */ - trailingComma?: boolean; - /** Evaluate the result of calling getters. - * - * @default {false} */ - getters?: boolean; - /** Show an object's non-enumerable properties. - * - * @default {false} */ - showHidden?: boolean; - /** The maximum length of a string before it is truncated with an - * ellipsis. */ - strAbbreviateSize?: number; - } - - /** Converts the input into a string that has the same format as printed by - * `console.log()`. - * - * ```ts - * const obj = { - * a: 10, - * b: "hello", - * }; - * const objAsString = Deno.inspect(obj); // { a: 10, b: "hello" } - * console.log(obj); // prints same value as objAsString, e.g. { a: 10, b: "hello" } - * ``` - * - * A custom inspect functions can be registered on objects, via the symbol - * `Symbol.for("Deno.customInspect")`, to control and customize the output - * of `inspect()` or when using `console` logging: - * - * ```ts - * class A { - * x = 10; - * y = "hello"; - * [Symbol.for("Deno.customInspect")]() { - * return `x=${this.x}, y=${this.y}`; - * } - * } - * - * const inStringFormat = Deno.inspect(new A()); // "x=10, y=hello" - * console.log(inStringFormat); // prints "x=10, y=hello" - * ``` - * - * A depth can be specified by using the `depth` option: - * - * ```ts - * Deno.inspect({a: {b: {c: {d: 'hello'}}}}, {depth: 2}); // { a: { b: [Object] } } - * ``` - * - * @category Console and Debugging - */ - export function inspect(value: unknown, options?: InspectOptions): string; - - /** The name of a privileged feature which needs permission. - * - * @category Permissions - */ - export type PermissionName = - | "run" - | "read" - | "write" - | "net" - | "env" - | "sys" - | "ffi" - | "hrtime"; - - /** The current status of the permission: - * - * - `"granted"` - the permission has been granted. - * - `"denied"` - the permission has been explicitly denied. - * - `"prompt"` - the permission has not explicitly granted nor denied. - * - * @category Permissions - */ - export type PermissionState = - | "granted" - | "denied" - | "prompt"; - - /** The permission descriptor for the `allow-run` and `deny-run` permissions, which controls - * access to what sub-processes can be executed by Deno. The option `command` - * allows scoping the permission to a specific executable. - * - * **Warning, in practice, `allow-run` is effectively the same as `allow-all` - * in the sense that malicious code could execute any arbitrary code on the - * host.** - * - * @category Permissions */ - export interface RunPermissionDescriptor { - name: "run"; - /** An `allow-run` or `deny-run` permission can be scoped to a specific executable, - * which would be relative to the start-up CWD of the Deno CLI. */ - command?: string | URL; - } - - /** The permission descriptor for the `allow-read` and `deny-read` permissions, which controls - * access to reading resources from the local host. The option `path` allows - * scoping the permission to a specific path (and if the path is a directory - * any sub paths). - * - * Permission granted under `allow-read` only allows runtime code to attempt - * to read, the underlying operating system may apply additional permissions. - * - * @category Permissions */ - export interface ReadPermissionDescriptor { - name: "read"; - /** An `allow-read` or `deny-read` permission can be scoped to a specific path (and if - * the path is a directory, any sub paths). */ - path?: string | URL; - } - - /** The permission descriptor for the `allow-write` and `deny-write` permissions, which - * controls access to writing to resources from the local host. The option - * `path` allow scoping the permission to a specific path (and if the path is - * a directory any sub paths). - * - * Permission granted under `allow-write` only allows runtime code to attempt - * to write, the underlying operating system may apply additional permissions. - * - * @category Permissions */ - export interface WritePermissionDescriptor { - name: "write"; - /** An `allow-write` or `deny-write` permission can be scoped to a specific path (and if - * the path is a directory, any sub paths). */ - path?: string | URL; - } - - /** The permission descriptor for the `allow-net` and `deny-net` permissions, which controls - * access to opening network ports and connecting to remote hosts via the - * network. The option `host` allows scoping the permission for outbound - * connection to a specific host and port. - * - * @category Permissions */ - export interface NetPermissionDescriptor { - name: "net"; - /** Optional host string of the form `"[:]"`. Examples: - * - * "github.com" - * "deno.land:8080" - */ - host?: string; - } - - /** The permission descriptor for the `allow-env` and `deny-env` permissions, which controls - * access to being able to read and write to the process environment variables - * as well as access other information about the environment. The option - * `variable` allows scoping the permission to a specific environment - * variable. - * - * @category Permissions */ - export interface EnvPermissionDescriptor { - name: "env"; - /** Optional environment variable name (e.g. `PATH`). */ - variable?: string; - } - - /** The permission descriptor for the `allow-sys` and `deny-sys` permissions, which controls - * access to sensitive host system information, which malicious code might - * attempt to exploit. The option `kind` allows scoping the permission to a - * specific piece of information. - * - * @category Permissions */ - export interface SysPermissionDescriptor { - name: "sys"; - /** The specific information to scope the permission to. */ - kind?: - | "loadavg" - | "hostname" - | "systemMemoryInfo" - | "networkInterfaces" - | "osRelease" - | "osUptime" - | "uid" - | "gid" - | "cpus"; - } - - /** The permission descriptor for the `allow-ffi` and `deny-ffi` permissions, which controls - * access to loading _foreign_ code and interfacing with it via the - * [Foreign Function Interface API](https://deno.land/manual/runtime/ffi_api) - * available in Deno. The option `path` allows scoping the permission to a - * specific path on the host. - * - * @category Permissions */ - export interface FfiPermissionDescriptor { - name: "ffi"; - /** Optional path on the local host to scope the permission to. */ - path?: string | URL; - } - - /** The permission descriptor for the `allow-hrtime` and `deny-hrtime` permissions, which - * controls if the runtime code has access to high resolution time. High - * resolution time is considered sensitive information, because it can be used - * by malicious code to gain information about the host that it might not - * otherwise have access to. - * - * @category Permissions */ - export interface HrtimePermissionDescriptor { - name: "hrtime"; - } - - /** Permission descriptors which define a permission and can be queried, - * requested, or revoked. - * - * View the specifics of the individual descriptors for more information about - * each permission kind. - * - * @category Permissions - */ - export type PermissionDescriptor = - | RunPermissionDescriptor - | ReadPermissionDescriptor - | WritePermissionDescriptor - | NetPermissionDescriptor - | EnvPermissionDescriptor - | SysPermissionDescriptor - | FfiPermissionDescriptor - | HrtimePermissionDescriptor; - - /** The interface which defines what event types are supported by - * {@linkcode PermissionStatus} instances. - * - * @category Permissions */ - export interface PermissionStatusEventMap { - "change": Event; - } - - /** An {@linkcode EventTarget} returned from the {@linkcode Deno.permissions} - * API which can provide updates to any state changes of the permission. - * - * @category Permissions */ - export class PermissionStatus extends EventTarget { - // deno-lint-ignore no-explicit-any - onchange: ((this: PermissionStatus, ev: Event) => any) | null; - readonly state: PermissionState; - /** - * Describes if permission is only granted partially, eg. an access - * might be granted to "/foo" directory, but denied for "/foo/bar". - * In such case this field will be set to `true` when querying for - * read permissions of "/foo" directory. - */ - readonly partial: boolean; - addEventListener( - type: K, - listener: ( - this: PermissionStatus, - ev: PermissionStatusEventMap[K], - ) => any, - options?: boolean | AddEventListenerOptions, - ): void; - addEventListener( - type: string, - listener: EventListenerOrEventListenerObject, - options?: boolean | AddEventListenerOptions, - ): void; - removeEventListener( - type: K, - listener: ( - this: PermissionStatus, - ev: PermissionStatusEventMap[K], - ) => any, - options?: boolean | EventListenerOptions, - ): void; - removeEventListener( - type: string, - listener: EventListenerOrEventListenerObject, - options?: boolean | EventListenerOptions, - ): void; - } - - /** - * Deno's permission management API. - * - * The class which provides the interface for the {@linkcode Deno.permissions} - * global instance and is based on the web platform - * [Permissions API](https://developer.mozilla.org/en-US/docs/Web/API/Permissions_API), - * though some proposed parts of the API which are useful in a server side - * runtime context were removed or abandoned in the web platform specification - * which is why it was chosen to locate it in the {@linkcode Deno} namespace - * instead. - * - * By default, if the `stdin`/`stdout` is TTY for the Deno CLI (meaning it can - * send and receive text), then the CLI will prompt the user to grant - * permission when an un-granted permission is requested. This behavior can - * be changed by using the `--no-prompt` command at startup. When prompting - * the CLI will request the narrowest permission possible, potentially making - * it annoying to the user. The permissions APIs allow the code author to - * request a wider set of permissions at one time in order to provide a better - * user experience. - * - * @category Permissions */ - export class Permissions { - /** Resolves to the current status of a permission. - * - * Note, if the permission is already granted, `request()` will not prompt - * the user again, therefore `query()` is only necessary if you are going - * to react differently existing permissions without wanting to modify them - * or prompt the user to modify them. - * - * ```ts - * const status = await Deno.permissions.query({ name: "read", path: "/etc" }); - * console.log(status.state); - * ``` - */ - query(desc: PermissionDescriptor): Promise; - - /** Returns the current status of a permission. - * - * Note, if the permission is already granted, `request()` will not prompt - * the user again, therefore `querySync()` is only necessary if you are going - * to react differently existing permissions without wanting to modify them - * or prompt the user to modify them. - * - * ```ts - * const status = Deno.permissions.querySync({ name: "read", path: "/etc" }); - * console.log(status.state); - * ``` - */ - querySync(desc: PermissionDescriptor): PermissionStatus; - - /** Revokes a permission, and resolves to the state of the permission. - * - * ```ts - * import { assert } from "jsr:@std/assert"; - * - * const status = await Deno.permissions.revoke({ name: "run" }); - * assert(status.state !== "granted") - * ``` - */ - revoke(desc: PermissionDescriptor): Promise; - - /** Revokes a permission, and returns the state of the permission. - * - * ```ts - * import { assert } from "jsr:@std/assert"; - * - * const status = Deno.permissions.revokeSync({ name: "run" }); - * assert(status.state !== "granted") - * ``` - */ - revokeSync(desc: PermissionDescriptor): PermissionStatus; - - /** Requests the permission, and resolves to the state of the permission. - * - * If the permission is already granted, the user will not be prompted to - * grant the permission again. - * - * ```ts - * const status = await Deno.permissions.request({ name: "env" }); - * if (status.state === "granted") { - * console.log("'env' permission is granted."); - * } else { - * console.log("'env' permission is denied."); - * } - * ``` - */ - request(desc: PermissionDescriptor): Promise; - - /** Requests the permission, and returns the state of the permission. - * - * If the permission is already granted, the user will not be prompted to - * grant the permission again. - * - * ```ts - * const status = Deno.permissions.requestSync({ name: "env" }); - * if (status.state === "granted") { - * console.log("'env' permission is granted."); - * } else { - * console.log("'env' permission is denied."); - * } - * ``` - */ - requestSync(desc: PermissionDescriptor): PermissionStatus; - } - - /** Deno's permission management API. - * - * It is a singleton instance of the {@linkcode Permissions} object and is - * based on the web platform - * [Permissions API](https://developer.mozilla.org/en-US/docs/Web/API/Permissions_API), - * though some proposed parts of the API which are useful in a server side - * runtime context were removed or abandoned in the web platform specification - * which is why it was chosen to locate it in the {@linkcode Deno} namespace - * instead. - * - * By default, if the `stdin`/`stdout` is TTY for the Deno CLI (meaning it can - * send and receive text), then the CLI will prompt the user to grant - * permission when an un-granted permission is requested. This behavior can - * be changed by using the `--no-prompt` command at startup. When prompting - * the CLI will request the narrowest permission possible, potentially making - * it annoying to the user. The permissions APIs allow the code author to - * request a wider set of permissions at one time in order to provide a better - * user experience. - * - * Requesting already granted permissions will not prompt the user and will - * return that the permission was granted. - * - * ### Querying - * - * ```ts - * const status = await Deno.permissions.query({ name: "read", path: "/etc" }); - * console.log(status.state); - * ``` - * - * ```ts - * const status = Deno.permissions.querySync({ name: "read", path: "/etc" }); - * console.log(status.state); - * ``` - * - * ### Revoking - * - * ```ts - * import { assert } from "jsr:@std/assert"; - * - * const status = await Deno.permissions.revoke({ name: "run" }); - * assert(status.state !== "granted") - * ``` - * - * ```ts - * import { assert } from "jsr:@std/assert"; - * - * const status = Deno.permissions.revokeSync({ name: "run" }); - * assert(status.state !== "granted") - * ``` - * - * ### Requesting - * - * ```ts - * const status = await Deno.permissions.request({ name: "env" }); - * if (status.state === "granted") { - * console.log("'env' permission is granted."); - * } else { - * console.log("'env' permission is denied."); - * } - * ``` - * - * ```ts - * const status = Deno.permissions.requestSync({ name: "env" }); - * if (status.state === "granted") { - * console.log("'env' permission is granted."); - * } else { - * console.log("'env' permission is denied."); - * } - * ``` - * - * @category Permissions - */ - export const permissions: Permissions; - - /** Information related to the build of the current Deno runtime. - * - * Users are discouraged from code branching based on this information, as - * assumptions about what is available in what build environment might change - * over time. Developers should specifically sniff out the features they - * intend to use. - * - * The intended use for the information is for logging and debugging purposes. - * - * @category Runtime Environment - */ - export const build: { - /** The [LLVM](https://llvm.org/) target triple, which is the combination - * of `${arch}-${vendor}-${os}` and represent the specific build target that - * the current runtime was built for. */ - target: string; - /** Instruction set architecture that the Deno CLI was built for. */ - arch: "x86_64" | "aarch64"; - /** The operating system that the Deno CLI was built for. `"darwin"` is - * also known as OSX or MacOS. */ - os: - | "darwin" - | "linux" - | "android" - | "windows" - | "freebsd" - | "netbsd" - | "aix" - | "solaris" - | "illumos"; - /** The computer vendor that the Deno CLI was built for. */ - vendor: string; - /** Optional environment flags that were set for this build of Deno CLI. */ - env?: string; - }; - - /** Version information related to the current Deno CLI runtime environment. - * - * Users are discouraged from code branching based on this information, as - * assumptions about what is available in what build environment might change - * over time. Developers should specifically sniff out the features they - * intend to use. - * - * The intended use for the information is for logging and debugging purposes. - * - * @category Runtime Environment - */ - export const version: { - /** Deno CLI's version. For example: `"1.26.0"`. */ - deno: string; - /** The V8 version used by Deno. For example: `"10.7.100.0"`. - * - * V8 is the underlying JavaScript runtime platform that Deno is built on - * top of. */ - v8: string; - /** The TypeScript version used by Deno. For example: `"4.8.3"`. - * - * A version of the TypeScript type checker and language server is built-in - * to the Deno CLI. */ - typescript: string; - }; - - /** Returns the script arguments to the program. - * - * Give the following command line invocation of Deno: - * - * ```sh - * deno run --allow-read https://examples.deno.land/command-line-arguments.ts Sushi - * ``` - * - * Then `Deno.args` will contain: - * - * ```ts - * [ "Sushi" ] - * ``` - * - * If you are looking for a structured way to parse arguments, there is - * [`parseArgs()`](https://jsr.io/@std/cli/doc/parse-args/~/parseArgs) from - * the Deno Standard Library. - * - * @category Runtime Environment - */ - export const args: string[]; - - /** - * A symbol which can be used as a key for a custom method which will be - * called when `Deno.inspect()` is called, or when the object is logged to - * the console. - * - * @deprecated This will be removed in Deno 2.0. See the - * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide} - * for migration instructions. - * - * @category Console and Debugging - */ - export const customInspect: unique symbol; - - /** The URL of the entrypoint module entered from the command-line. It - * requires read permission to the CWD. - * - * Also see {@linkcode ImportMeta} for other related information. - * - * @tags allow-read - * @category Runtime Environment - */ - export const mainModule: string; - - /** Options that can be used with {@linkcode symlink} and - * {@linkcode symlinkSync}. - * - * @category File System */ - export interface SymlinkOptions { - /** If the symbolic link should be either a file or directory. This option - * only applies to Windows and is ignored on other operating systems. */ - type: "file" | "dir"; - } - - /** - * Creates `newpath` as a symbolic link to `oldpath`. - * - * The `options.type` parameter can be set to `"file"` or `"dir"`. This - * argument is only available on Windows and ignored on other platforms. - * - * ```ts - * await Deno.symlink("old/name", "new/name"); - * ``` - * - * Requires full `allow-read` and `allow-write` permissions. - * - * @tags allow-read, allow-write - * @category File System - */ - export function symlink( - oldpath: string | URL, - newpath: string | URL, - options?: SymlinkOptions, - ): Promise; - - /** - * Creates `newpath` as a symbolic link to `oldpath`. - * - * The `options.type` parameter can be set to `"file"` or `"dir"`. This - * argument is only available on Windows and ignored on other platforms. - * - * ```ts - * Deno.symlinkSync("old/name", "new/name"); - * ``` - * - * Requires full `allow-read` and `allow-write` permissions. - * - * @tags allow-read, allow-write - * @category File System - */ - export function symlinkSync( - oldpath: string | URL, - newpath: string | URL, - options?: SymlinkOptions, - ): void; - - /** - * Truncates or extends the specified file stream, to reach the specified - * `len`. - * - * If `len` is not specified then the entire file contents are truncated as if - * `len` was set to `0`. - * - * If the file previously was larger than this new length, the extra data is - * lost. - * - * If the file previously was shorter, it is extended, and the extended part - * reads as null bytes ('\0'). - * - * ### Truncate the entire file - * - * ```ts - * const file = await Deno.open( - * "my_file.txt", - * { read: true, write: true, create: true } - * ); - * await Deno.ftruncate(file.rid); - * ``` - * - * ### Truncate part of the file - * - * ```ts - * const file = await Deno.open( - * "my_file.txt", - * { read: true, write: true, create: true } - * ); - * await file.write(new TextEncoder().encode("Hello World")); - * await Deno.ftruncate(file.rid, 7); - * const data = new Uint8Array(32); - * await Deno.read(file.rid, data); - * console.log(new TextDecoder().decode(data)); // Hello W - * ``` - * - * @deprecated This will be removed in Deno 2.0. See the - * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide} - * for migration instructions. - * - * @category File System - */ - export function ftruncate(rid: number, len?: number): Promise; - - /** - * Synchronously truncates or extends the specified file stream, to reach the - * specified `len`. - * - * If `len` is not specified then the entire file contents are truncated as if - * `len` was set to `0`. - * - * If the file previously was larger than this new length, the extra data is - * lost. - * - * If the file previously was shorter, it is extended, and the extended part - * reads as null bytes ('\0'). - * - * ### Truncate the entire file - * - * ```ts - * const file = Deno.openSync( - * "my_file.txt", - * { read: true, write: true, truncate: true, create: true } - * ); - * Deno.ftruncateSync(file.rid); - * ``` - * - * ### Truncate part of the file - * - * ```ts - * const file = Deno.openSync( - * "my_file.txt", - * { read: true, write: true, create: true } - * ); - * file.writeSync(new TextEncoder().encode("Hello World")); - * Deno.ftruncateSync(file.rid, 7); - * Deno.seekSync(file.rid, 0, Deno.SeekMode.Start); - * const data = new Uint8Array(32); - * Deno.readSync(file.rid, data); - * console.log(new TextDecoder().decode(data)); // Hello W - * ``` - * - * @deprecated This will be removed in Deno 2.0. See the - * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide} - * for migration instructions. - * - * @category File System - */ - export function ftruncateSync(rid: number, len?: number): void; - - /** - * Synchronously changes the access (`atime`) and modification (`mtime`) times - * of a file stream resource referenced by `rid`. Given times are either in - * seconds (UNIX epoch time) or as `Date` objects. - * - * ```ts - * const file = Deno.openSync("file.txt", { create: true, write: true }); - * Deno.futimeSync(file.rid, 1556495550, new Date()); - * ``` - * - * @deprecated This will be removed in Deno 2.0. See the - * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide} - * for migration instructions. - * - * @category File System - */ - export function futimeSync( - rid: number, - atime: number | Date, - mtime: number | Date, - ): void; - - /** - * Changes the access (`atime`) and modification (`mtime`) times of a file - * stream resource referenced by `rid`. Given times are either in seconds - * (UNIX epoch time) or as `Date` objects. - * - * ```ts - * const file = await Deno.open("file.txt", { create: true, write: true }); - * await Deno.futime(file.rid, 1556495550, new Date()); - * ``` - * - * @deprecated This will be removed in Deno 2.0. See the - * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide} - * for migration instructions. - * - * @category File System - */ - export function futime( - rid: number, - atime: number | Date, - mtime: number | Date, - ): Promise; - - /** - * Returns a `Deno.FileInfo` for the given file stream. - * - * ```ts - * import { assert } from "jsr:@std/assert"; - * - * const file = await Deno.open("file.txt", { read: true }); - * const fileInfo = await Deno.fstat(file.rid); - * assert(fileInfo.isFile); - * ``` - * - * @deprecated This will be removed in Deno 2.0. See the - * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide} - * for migration instructions. - * - * @category File System - */ - export function fstat(rid: number): Promise; - - /** - * Synchronously returns a {@linkcode Deno.FileInfo} for the given file - * stream. - * - * ```ts - * import { assert } from "jsr:@std/assert"; - * - * const file = Deno.openSync("file.txt", { read: true }); - * const fileInfo = Deno.fstatSync(file.rid); - * assert(fileInfo.isFile); - * ``` - * - * @deprecated This will be removed in Deno 2.0. See the - * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide} - * for migration instructions. - * - * @category File System - */ - export function fstatSync(rid: number): FileInfo; - - /** - * Synchronously changes the access (`atime`) and modification (`mtime`) times - * of a file system object referenced by `path`. Given times are either in - * seconds (UNIX epoch time) or as `Date` objects. - * - * ```ts - * Deno.utimeSync("myfile.txt", 1556495550, new Date()); - * ``` - * - * Requires `allow-write` permission. - * - * @tags allow-write - * @category File System - */ - export function utimeSync( - path: string | URL, - atime: number | Date, - mtime: number | Date, - ): void; - - /** - * Changes the access (`atime`) and modification (`mtime`) times of a file - * system object referenced by `path`. Given times are either in seconds - * (UNIX epoch time) or as `Date` objects. - * - * ```ts - * await Deno.utime("myfile.txt", 1556495550, new Date()); - * ``` - * - * Requires `allow-write` permission. - * - * @tags allow-write - * @category File System - */ - export function utime( - path: string | URL, - atime: number | Date, - mtime: number | Date, - ): Promise; - - /** The event yielded from an {@linkcode HttpConn} which represents an HTTP - * request from a remote client. - * - * @category HTTP Server - * - * @deprecated This will be removed in Deno 2.0. See the - * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide} - * for migration instructions. - */ - export interface RequestEvent { - /** The request from the client in the form of the web platform - * {@linkcode Request}. */ - readonly request: Request; - /** The method to be used to respond to the event. The response needs to - * either be an instance of {@linkcode Response} or a promise that resolves - * with an instance of `Response`. - * - * When the response is successfully processed then the promise returned - * will be resolved. If there are any issues with sending the response, - * the promise will be rejected. */ - respondWith(r: Response | PromiseLike): Promise; - } - - /** - * The async iterable that is returned from {@linkcode serveHttp} which - * yields up {@linkcode RequestEvent} events, representing individual - * requests on the HTTP server connection. - * - * @category HTTP Server - * - * @deprecated This will be removed in Deno 2.0. See the - * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide} - * for migration instructions. - */ - export interface HttpConn extends AsyncIterable, Disposable { - /** The resource ID associated with this connection. Generally users do not - * need to be aware of this identifier. */ - readonly rid: number; - - /** An alternative to the async iterable interface which provides promises - * which resolve with either a {@linkcode RequestEvent} when there is - * another request or `null` when the client has closed the connection. */ - nextRequest(): Promise; - /** Initiate a server side closure of the connection, indicating to the - * client that you refuse to accept any more requests on this connection. - * - * Typically the client closes the connection, which will result in the - * async iterable terminating or the `nextRequest()` method returning - * `null`. */ - close(): void; - } - - /** - * Provides an interface to handle HTTP request and responses over TCP or TLS - * connections. The method returns an {@linkcode HttpConn} which yields up - * {@linkcode RequestEvent} events, which utilize the web platform standard - * {@linkcode Request} and {@linkcode Response} objects to handle the request. - * - * ```ts - * const conn = Deno.listen({ port: 80 }); - * const httpConn = Deno.serveHttp(await conn.accept()); - * const e = await httpConn.nextRequest(); - * if (e) { - * e.respondWith(new Response("Hello World")); - * } - * ``` - * - * Alternatively, you can also use the async iterator approach: - * - * ```ts - * async function handleHttp(conn: Deno.Conn) { - * for await (const e of Deno.serveHttp(conn)) { - * e.respondWith(new Response("Hello World")); - * } - * } - * - * for await (const conn of Deno.listen({ port: 80 })) { - * handleHttp(conn); - * } - * ``` - * - * If `httpConn.nextRequest()` encounters an error or returns `null` then the - * underlying {@linkcode HttpConn} resource is closed automatically. - * - * Also see the experimental Flash HTTP server {@linkcode Deno.serve} which - * provides a ground up rewrite of handling of HTTP requests and responses - * within the Deno CLI. - * - * Note that this function *consumes* the given connection passed to it, thus - * the original connection will be unusable after calling this. Additionally, - * you need to ensure that the connection is not being used elsewhere when - * calling this function in order for the connection to be consumed properly. - * - * For instance, if there is a `Promise` that is waiting for read operation on - * the connection to complete, it is considered that the connection is being - * used elsewhere. In such a case, this function will fail. - * - * @category HTTP Server - * @deprecated This will be soft-removed in Deno 2.0. See the - * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide} - * for migration instructions. - */ - export function serveHttp(conn: Conn): HttpConn; - - /** The object that is returned from a {@linkcode Deno.upgradeWebSocket} - * request. - * - * @category Web Sockets */ - export interface WebSocketUpgrade { - /** The response object that represents the HTTP response to the client, - * which should be used to the {@linkcode RequestEvent} `.respondWith()` for - * the upgrade to be successful. */ - response: Response; - /** The {@linkcode WebSocket} interface to communicate to the client via a - * web socket. */ - socket: WebSocket; - } - - /** Options which can be set when performing a - * {@linkcode Deno.upgradeWebSocket} upgrade of a {@linkcode Request} - * - * @category Web Sockets */ - export interface UpgradeWebSocketOptions { - /** Sets the `.protocol` property on the client side web socket to the - * value provided here, which should be one of the strings specified in the - * `protocols` parameter when requesting the web socket. This is intended - * for clients and servers to specify sub-protocols to use to communicate to - * each other. */ - protocol?: string; - /** If the client does not respond to this frame with a - * `pong` within the timeout specified, the connection is deemed - * unhealthy and is closed. The `close` and `error` event will be emitted. - * - * The unit is seconds, with a default of 120. - * Set to `0` to disable timeouts. */ - idleTimeout?: number; - } - - /** - * Upgrade an incoming HTTP request to a WebSocket. - * - * Given a {@linkcode Request}, returns a pair of {@linkcode WebSocket} and - * {@linkcode Response} instances. The original request must be responded to - * with the returned response for the websocket upgrade to be successful. - * - * ```ts - * const conn = Deno.listen({ port: 80 }); - * const httpConn = Deno.serveHttp(await conn.accept()); - * const e = await httpConn.nextRequest(); - * if (e) { - * const { socket, response } = Deno.upgradeWebSocket(e.request); - * socket.onopen = () => { - * socket.send("Hello World!"); - * }; - * socket.onmessage = (e) => { - * console.log(e.data); - * socket.close(); - * }; - * socket.onclose = () => console.log("WebSocket has been closed."); - * socket.onerror = (e) => console.error("WebSocket error:", e); - * e.respondWith(response); - * } - * ``` - * - * If the request body is disturbed (read from) before the upgrade is - * completed, upgrading fails. - * - * This operation does not yet consume the request or open the websocket. This - * only happens once the returned response has been passed to `respondWith()`. - * - * @category Web Sockets - */ - export function upgradeWebSocket( - request: Request, - options?: UpgradeWebSocketOptions, - ): WebSocketUpgrade; - - /** Send a signal to process under given `pid`. The value and meaning of the - * `signal` to the process is operating system and process dependant. - * {@linkcode Signal} provides the most common signals. Default signal - * is `"SIGTERM"`. - * - * The term `kill` is adopted from the UNIX-like command line command `kill` - * which also signals processes. - * - * If `pid` is negative, the signal will be sent to the process group - * identified by `pid`. An error will be thrown if a negative `pid` is used on - * Windows. - * - * ```ts - * const p = Deno.run({ - * cmd: ["sleep", "10000"] - * }); - * - * Deno.kill(p.pid, "SIGINT"); - * ``` - * - * Requires `allow-run` permission. - * - * @tags allow-run - * @category Sub Process - */ - export function kill(pid: number, signo?: Signal): void; - - /** The type of the resource record to resolve via DNS using - * {@linkcode Deno.resolveDns}. - * - * Only the listed types are supported currently. - * - * @category Network - */ - export type RecordType = - | "A" - | "AAAA" - | "ANAME" - | "CAA" - | "CNAME" - | "MX" - | "NAPTR" - | "NS" - | "PTR" - | "SOA" - | "SRV" - | "TXT"; - - /** - * Options which can be set when using {@linkcode Deno.resolveDns}. - * - * @category Network */ - export interface ResolveDnsOptions { - /** The name server to be used for lookups. - * - * If not specified, defaults to the system configuration. For example - * `/etc/resolv.conf` on Unix-like systems. */ - nameServer?: { - /** The IP address of the name server. */ - ipAddr: string; - /** The port number the query will be sent to. - * - * @default {53} */ - port?: number; - }; - /** - * An abort signal to allow cancellation of the DNS resolution operation. - * If the signal becomes aborted the resolveDns operation will be stopped - * and the promise returned will be rejected with an AbortError. - */ - signal?: AbortSignal; - } - - /** If {@linkcode Deno.resolveDns} is called with `"CAA"` record type - * specified, it will resolve with an array of objects with this interface. - * - * @category Network - */ - export interface CAARecord { - /** If `true`, indicates that the corresponding property tag **must** be - * understood if the semantics of the CAA record are to be correctly - * interpreted by an issuer. - * - * Issuers **must not** issue certificates for a domain if the relevant CAA - * Resource Record set contains unknown property tags that have `critical` - * set. */ - critical: boolean; - /** An string that represents the identifier of the property represented by - * the record. */ - tag: string; - /** The value associated with the tag. */ - value: string; - } - - /** If {@linkcode Deno.resolveDns} is called with `"MX"` record type - * specified, it will return an array of objects with this interface. - * - * @category Network */ - export interface MXRecord { - /** A priority value, which is a relative value compared to the other - * preferences of MX records for the domain. */ - preference: number; - /** The server that mail should be delivered to. */ - exchange: string; - } - - /** If {@linkcode Deno.resolveDns} is called with `"NAPTR"` record type - * specified, it will return an array of objects with this interface. - * - * @category Network */ - export interface NAPTRRecord { - order: number; - preference: number; - flags: string; - services: string; - regexp: string; - replacement: string; - } - - /** If {@linkcode Deno.resolveDns} is called with `"SOA"` record type - * specified, it will return an array of objects with this interface. - * - * @category Network */ - export interface SOARecord { - mname: string; - rname: string; - serial: number; - refresh: number; - retry: number; - expire: number; - minimum: number; - } - - /** If {@linkcode Deno.resolveDns} is called with `"SRV"` record type - * specified, it will return an array of objects with this interface. - * - * @category Network - */ - export interface SRVRecord { - priority: number; - weight: number; - port: number; - target: string; - } - - /** - * Performs DNS resolution against the given query, returning resolved - * records. - * - * Fails in the cases such as: - * - * - the query is in invalid format. - * - the options have an invalid parameter. For example `nameServer.port` is - * beyond the range of 16-bit unsigned integer. - * - the request timed out. - * - * ```ts - * const a = await Deno.resolveDns("example.com", "A"); - * - * const aaaa = await Deno.resolveDns("example.com", "AAAA", { - * nameServer: { ipAddr: "8.8.8.8", port: 53 }, - * }); - * ``` - * - * Requires `allow-net` permission. - * - * @tags allow-net - * @category Network - */ - export function resolveDns( - query: string, - recordType: "A" | "AAAA" | "ANAME" | "CNAME" | "NS" | "PTR", - options?: ResolveDnsOptions, - ): Promise; - - /** - * Performs DNS resolution against the given query, returning resolved - * records. - * - * Fails in the cases such as: - * - * - the query is in invalid format. - * - the options have an invalid parameter. For example `nameServer.port` is - * beyond the range of 16-bit unsigned integer. - * - the request timed out. - * - * ```ts - * const a = await Deno.resolveDns("example.com", "A"); - * - * const aaaa = await Deno.resolveDns("example.com", "AAAA", { - * nameServer: { ipAddr: "8.8.8.8", port: 53 }, - * }); - * ``` - * - * Requires `allow-net` permission. - * - * @tags allow-net - * @category Network - */ - export function resolveDns( - query: string, - recordType: "CAA", - options?: ResolveDnsOptions, - ): Promise; - - /** - * Performs DNS resolution against the given query, returning resolved - * records. - * - * Fails in the cases such as: - * - * - the query is in invalid format. - * - the options have an invalid parameter. For example `nameServer.port` is - * beyond the range of 16-bit unsigned integer. - * - the request timed out. - * - * ```ts - * const a = await Deno.resolveDns("example.com", "A"); - * - * const aaaa = await Deno.resolveDns("example.com", "AAAA", { - * nameServer: { ipAddr: "8.8.8.8", port: 53 }, - * }); - * ``` - * - * Requires `allow-net` permission. - * - * @tags allow-net - * @category Network - */ - export function resolveDns( - query: string, - recordType: "MX", - options?: ResolveDnsOptions, - ): Promise; - - /** - * Performs DNS resolution against the given query, returning resolved - * records. - * - * Fails in the cases such as: - * - * - the query is in invalid format. - * - the options have an invalid parameter. For example `nameServer.port` is - * beyond the range of 16-bit unsigned integer. - * - the request timed out. - * - * ```ts - * const a = await Deno.resolveDns("example.com", "A"); - * - * const aaaa = await Deno.resolveDns("example.com", "AAAA", { - * nameServer: { ipAddr: "8.8.8.8", port: 53 }, - * }); - * ``` - * - * Requires `allow-net` permission. - * - * @tags allow-net - * @category Network - */ - export function resolveDns( - query: string, - recordType: "NAPTR", - options?: ResolveDnsOptions, - ): Promise; - - /** - * Performs DNS resolution against the given query, returning resolved - * records. - * - * Fails in the cases such as: - * - * - the query is in invalid format. - * - the options have an invalid parameter. For example `nameServer.port` is - * beyond the range of 16-bit unsigned integer. - * - the request timed out. - * - * ```ts - * const a = await Deno.resolveDns("example.com", "A"); - * - * const aaaa = await Deno.resolveDns("example.com", "AAAA", { - * nameServer: { ipAddr: "8.8.8.8", port: 53 }, - * }); - * ``` - * - * Requires `allow-net` permission. - * - * @tags allow-net - * @category Network - */ - export function resolveDns( - query: string, - recordType: "SOA", - options?: ResolveDnsOptions, - ): Promise; - - /** - * Performs DNS resolution against the given query, returning resolved - * records. - * - * Fails in the cases such as: - * - * - the query is in invalid format. - * - the options have an invalid parameter. For example `nameServer.port` is - * beyond the range of 16-bit unsigned integer. - * - the request timed out. - * - * ```ts - * const a = await Deno.resolveDns("example.com", "A"); - * - * const aaaa = await Deno.resolveDns("example.com", "AAAA", { - * nameServer: { ipAddr: "8.8.8.8", port: 53 }, - * }); - * ``` - * - * Requires `allow-net` permission. - * - * @tags allow-net - * @category Network - */ - export function resolveDns( - query: string, - recordType: "SRV", - options?: ResolveDnsOptions, - ): Promise; - - /** - * Performs DNS resolution against the given query, returning resolved - * records. - * - * Fails in the cases such as: - * - * - the query is in invalid format. - * - the options have an invalid parameter. For example `nameServer.port` is - * beyond the range of 16-bit unsigned integer. - * - the request timed out. - * - * ```ts - * const a = await Deno.resolveDns("example.com", "A"); - * - * const aaaa = await Deno.resolveDns("example.com", "AAAA", { - * nameServer: { ipAddr: "8.8.8.8", port: 53 }, - * }); - * ``` - * - * Requires `allow-net` permission. - * - * @tags allow-net - * @category Network - */ - export function resolveDns( - query: string, - recordType: "TXT", - options?: ResolveDnsOptions, - ): Promise; - - /** - * Performs DNS resolution against the given query, returning resolved - * records. - * - * Fails in the cases such as: - * - * - the query is in invalid format. - * - the options have an invalid parameter. For example `nameServer.port` is - * beyond the range of 16-bit unsigned integer. - * - the request timed out. - * - * ```ts - * const a = await Deno.resolveDns("example.com", "A"); - * - * const aaaa = await Deno.resolveDns("example.com", "AAAA", { - * nameServer: { ipAddr: "8.8.8.8", port: 53 }, - * }); - * ``` - * - * Requires `allow-net` permission. - * - * @tags allow-net - * @category Network - */ - export function resolveDns( - query: string, - recordType: RecordType, - options?: ResolveDnsOptions, - ): Promise< - | string[] - | CAARecord[] - | MXRecord[] - | NAPTRRecord[] - | SOARecord[] - | SRVRecord[] - | string[][] - >; - - /** - * Make the timer of the given `id` block the event loop from finishing. - * - * @category Timers - */ - export function refTimer(id: number): void; - - /** - * Make the timer of the given `id` not block the event loop from finishing. - * - * @category Timers - */ - export function unrefTimer(id: number): void; - - /** - * Returns the user id of the process on POSIX platforms. Returns null on Windows. - * - * ```ts - * console.log(Deno.uid()); - * ``` - * - * Requires `allow-sys` permission. - * - * @tags allow-sys - * @category Runtime Environment - */ - export function uid(): number | null; - - /** - * Returns the group id of the process on POSIX platforms. Returns null on windows. - * - * ```ts - * console.log(Deno.gid()); - * ``` - * - * Requires `allow-sys` permission. - * - * @tags allow-sys - * @category Runtime Environment - */ - export function gid(): number | null; - - /** Information for a HTTP request. - * - * @category HTTP Server - */ - export interface ServeHandlerInfo { - /** The remote address of the connection. */ - remoteAddr: Deno.NetAddr; - } - - /** A handler for HTTP requests. Consumes a request and returns a response. - * - * If a handler throws, the server calling the handler will assume the impact - * of the error is isolated to the individual request. It will catch the error - * and if necessary will close the underlying connection. - * - * @category HTTP Server - */ - export type ServeHandler = ( - request: Request, - info: ServeHandlerInfo, - ) => Response | Promise; - - /** Options which can be set when calling {@linkcode Deno.serve}. - * - * @category HTTP Server - */ - export interface ServeOptions { - /** The port to listen on. - * - * @default {8000} */ - port?: number; - - /** A literal IP address or host name that can be resolved to an IP address. - * - * __Note about `0.0.0.0`__ While listening `0.0.0.0` works on all platforms, - * the browsers on Windows don't work with the address `0.0.0.0`. - * You should show the message like `server running on localhost:8080` instead of - * `server running on 0.0.0.0:8080` if your program supports Windows. - * - * @default {"0.0.0.0"} */ - hostname?: string; - - /** An {@linkcode AbortSignal} to close the server and all connections. */ - signal?: AbortSignal; - - /** Sets `SO_REUSEPORT` on POSIX systems. */ - reusePort?: boolean; - - /** The handler to invoke when route handlers throw an error. */ - onError?: (error: unknown) => Response | Promise; - - /** The callback which is called when the server starts listening. */ - onListen?: (params: { hostname: string; port: number }) => void; - } - - /** Additional options which are used when opening a TLS (HTTPS) server. - * - * @category HTTP Server - */ - export interface ServeTlsOptions extends ServeOptions { - /** Server private key in PEM format */ - cert: string; - - /** Cert chain in PEM format */ - key: string; - } - - /** - * @category HTTP Server - */ - export interface ServeInit { - /** The handler to invoke to process each incoming request. */ - handler: ServeHandler; - } - - /** @category HTTP Server */ - export interface ServeUnixOptions { - /** The unix domain socket path to listen on. */ - path: string; - - /** An {@linkcode AbortSignal} to close the server and all connections. */ - signal?: AbortSignal; - - /** The handler to invoke when route handlers throw an error. */ - onError?: (error: unknown) => Response | Promise; - - /** The callback which is called when the server starts listening. */ - onListen?: (params: { path: string }) => void; - } - - /** Information for a unix domain socket HTTP request. - * - * @category HTTP Server - */ - export interface ServeUnixHandlerInfo { - /** The remote address of the connection. */ - remoteAddr: Deno.UnixAddr; - } - - /** A handler for unix domain socket HTTP requests. Consumes a request and returns a response. - * - * If a handler throws, the server calling the handler will assume the impact - * of the error is isolated to the individual request. It will catch the error - * and if necessary will close the underlying connection. - * - * @category HTTP Server - */ - export type ServeUnixHandler = ( - request: Request, - info: ServeUnixHandlerInfo, - ) => Response | Promise; - - /** - * @category HTTP Server - */ - export interface ServeUnixInit { - /** The handler to invoke to process each incoming request. */ - handler: ServeUnixHandler; - } - - /** An instance of the server created using `Deno.serve()` API. - * - * @category HTTP Server - */ - export interface HttpServer extends AsyncDisposable { - /** A promise that resolves once server finishes - eg. when aborted using - * the signal passed to {@linkcode ServeOptions.signal}. - */ - finished: Promise; - - /** - * Make the server block the event loop from finishing. - * - * Note: the server blocks the event loop from finishing by default. - * This method is only meaningful after `.unref()` is called. - */ - ref(): void; - - /** Make the server not block the event loop from finishing. */ - unref(): void; - - /** Gracefully close the server. No more new connections will be accepted, - * while pending requests will be allowed to finish. - */ - shutdown(): Promise; - } - - /** - * @category HTTP Server - * - * @deprecated This will be removed in Deno 2.0. See the - * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide} - * for migration instructions. - */ - export type Server = HttpServer; - - /** Serves HTTP requests with the given handler. - * - * The below example serves with the port `8000` on hostname `"127.0.0.1"`. - * - * ```ts - * Deno.serve((_req) => new Response("Hello, world")); - * ``` - * - * @category HTTP Server - */ - export function serve(handler: ServeHandler): HttpServer; - /** Serves HTTP requests with the given option bag and handler. - * - * You can specify the socket path with `path` option. - * - * ```ts - * Deno.serve( - * { path: "path/to/socket" }, - * (_req) => new Response("Hello, world") - * ); - * ``` - * - * You can stop the server with an {@linkcode AbortSignal}. The abort signal - * needs to be passed as the `signal` option in the options bag. The server - * aborts when the abort signal is aborted. To wait for the server to close, - * await the promise returned from the `Deno.serve` API. - * - * ```ts - * const ac = new AbortController(); - * - * const server = Deno.serve( - * { signal: ac.signal, path: "path/to/socket" }, - * (_req) => new Response("Hello, world") - * ); - * server.finished.then(() => console.log("Server closed")); - * - * console.log("Closing server..."); - * ac.abort(); - * ``` - * - * By default `Deno.serve` prints the message - * `Listening on path/to/socket` on listening. If you like to - * change this behavior, you can specify a custom `onListen` callback. - * - * ```ts - * Deno.serve({ - * onListen({ path }) { - * console.log(`Server started at ${path}`); - * // ... more info specific to your server .. - * }, - * path: "path/to/socket", - * }, (_req) => new Response("Hello, world")); - * ``` - * - * @category HTTP Server - */ - export function serve( - options: ServeUnixOptions, - handler: ServeUnixHandler, - ): HttpServer; - /** Serves HTTP requests with the given option bag and handler. - * - * You can specify an object with a port and hostname option, which is the - * address to listen on. The default is port `8000` on hostname `"127.0.0.1"`. - * - * You can change the address to listen on using the `hostname` and `port` - * options. The below example serves on port `3000` and hostname `"0.0.0.0"`. - * - * ```ts - * Deno.serve( - * { port: 3000, hostname: "0.0.0.0" }, - * (_req) => new Response("Hello, world") - * ); - * ``` - * - * You can stop the server with an {@linkcode AbortSignal}. The abort signal - * needs to be passed as the `signal` option in the options bag. The server - * aborts when the abort signal is aborted. To wait for the server to close, - * await the promise returned from the `Deno.serve` API. - * - * ```ts - * const ac = new AbortController(); - * - * const server = Deno.serve( - * { signal: ac.signal }, - * (_req) => new Response("Hello, world") - * ); - * server.finished.then(() => console.log("Server closed")); - * - * console.log("Closing server..."); - * ac.abort(); - * ``` - * - * By default `Deno.serve` prints the message - * `Listening on http://:/` on listening. If you like to - * change this behavior, you can specify a custom `onListen` callback. - * - * ```ts - * Deno.serve({ - * onListen({ port, hostname }) { - * console.log(`Server started at http://${hostname}:${port}`); - * // ... more info specific to your server .. - * }, - * }, (_req) => new Response("Hello, world")); - * ``` - * - * To enable TLS you must specify the `key` and `cert` options. - * - * ```ts - * const cert = "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n"; - * const key = "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n"; - * Deno.serve({ cert, key }, (_req) => new Response("Hello, world")); - * ``` - * - * @category HTTP Server - */ - export function serve( - options: ServeOptions | ServeTlsOptions, - handler: ServeHandler, - ): HttpServer; - /** Serves HTTP requests with the given option bag. - * - * You can specify an object with the path option, which is the - * unix domain socket to listen on. - * - * ```ts - * const ac = new AbortController(); - * - * const server = Deno.serve({ - * path: "path/to/socket", - * handler: (_req) => new Response("Hello, world"), - * signal: ac.signal, - * onListen({ path }) { - * console.log(`Server started at ${path}`); - * }, - * }); - * server.finished.then(() => console.log("Server closed")); - * - * console.log("Closing server..."); - * ac.abort(); - * ``` - * - * @category HTTP Server - */ - export function serve( - options: ServeUnixInit & ServeUnixOptions, - ): HttpServer; - /** Serves HTTP requests with the given option bag. - * - * You can specify an object with a port and hostname option, which is the - * address to listen on. The default is port `8000` on hostname `"127.0.0.1"`. - * - * ```ts - * const ac = new AbortController(); - * - * const server = Deno.serve({ - * port: 3000, - * hostname: "0.0.0.0", - * handler: (_req) => new Response("Hello, world"), - * signal: ac.signal, - * onListen({ port, hostname }) { - * console.log(`Server started at http://${hostname}:${port}`); - * }, - * }); - * server.finished.then(() => console.log("Server closed")); - * - * console.log("Closing server..."); - * ac.abort(); - * ``` - * - * @category HTTP Server - */ - export function serve( - options: ServeInit & (ServeOptions | ServeTlsOptions), - ): HttpServer; - - /** **UNSTABLE**: New API, yet to be vetted. - * - * Retrieve the process umask. If `mask` is provided, sets the process umask. - * This call always returns what the umask was before the call. - * - * ```ts - * console.log(Deno.umask()); // e.g. 18 (0o022) - * const prevUmaskValue = Deno.umask(0o077); // e.g. 18 (0o022) - * console.log(Deno.umask()); // e.g. 63 (0o077) - * ``` - * - * This API is under consideration to determine if permissions are required to - * call it. - * - * *Note*: This API is not implemented on Windows - * - * @category File System - */ - export function umask(mask?: number): number; - - /** **UNSTABLE**: New API, yet to be vetted. - * - * All plain number types for interfacing with foreign functions. - * - * @category FFI - */ - type NativeNumberType = - | "u8" - | "i8" - | "u16" - | "i16" - | "u32" - | "i32" - | "f32" - | "f64"; - - /** **UNSTABLE**: New API, yet to be vetted. - * - * All BigInt number types for interfacing with foreign functions. - * - * @category FFI - */ - type NativeBigIntType = - | "u64" - | "i64" - | "usize" - | "isize"; - - /** **UNSTABLE**: New API, yet to be vetted. - * - * The native boolean type for interfacing to foreign functions. - * - * @category FFI - */ - type NativeBooleanType = "bool"; - - /** **UNSTABLE**: New API, yet to be vetted. - * - * The native pointer type for interfacing to foreign functions. - * - * @category FFI - */ - type NativePointerType = "pointer"; - - /** **UNSTABLE**: New API, yet to be vetted. - * - * The native buffer type for interfacing to foreign functions. - * - * @category FFI - */ - type NativeBufferType = "buffer"; - - /** **UNSTABLE**: New API, yet to be vetted. - * - * The native function type for interfacing with foreign functions. - * - * @category FFI - */ - type NativeFunctionType = "function"; - - /** **UNSTABLE**: New API, yet to be vetted. - * - * The native void type for interfacing with foreign functions. - * - * @category FFI - */ - type NativeVoidType = "void"; - - /** **UNSTABLE**: New API, yet to be vetted. - * - * The native struct type for interfacing with foreign functions. - * - * @category FFI - */ - type NativeStructType = { readonly struct: readonly NativeType[] }; - - /** @category FFI */ - const brand: unique symbol; - - /** @category FFI */ - export type NativeU8Enum = "u8" & { [brand]: T }; - /** @category FFI */ - export type NativeI8Enum = "i8" & { [brand]: T }; - /** @category FFI */ - export type NativeU16Enum = "u16" & { [brand]: T }; - /** @category FFI */ - export type NativeI16Enum = "i16" & { [brand]: T }; - /** @category FFI */ - export type NativeU32Enum = "u32" & { [brand]: T }; - /** @category FFI */ - export type NativeI32Enum = "i32" & { [brand]: T }; - /** @category FFI */ - export type NativeTypedPointer = "pointer" & { - [brand]: T; - }; - /** @category FFI */ - export type NativeTypedFunction = - & "function" - & { - [brand]: T; - }; - - /** **UNSTABLE**: New API, yet to be vetted. - * - * All supported types for interfacing with foreign functions. - * - * @category FFI - */ - export type NativeType = - | NativeNumberType - | NativeBigIntType - | NativeBooleanType - | NativePointerType - | NativeBufferType - | NativeFunctionType - | NativeStructType; - - /** **UNSTABLE**: New API, yet to be vetted. - * - * @category FFI - */ - export type NativeResultType = NativeType | NativeVoidType; - - /** **UNSTABLE**: New API, yet to be vetted. - * - * Type conversion for foreign symbol parameters and unsafe callback return - * types. - * - * @category FFI - */ - type ToNativeType = T extends NativeStructType ? BufferSource - : T extends NativeNumberType ? T extends NativeU8Enum ? U - : T extends NativeI8Enum ? U - : T extends NativeU16Enum ? U - : T extends NativeI16Enum ? U - : T extends NativeU32Enum ? U - : T extends NativeI32Enum ? U - : number - : T extends NativeBigIntType ? number | bigint - : T extends NativeBooleanType ? boolean - : T extends NativePointerType ? T extends NativeTypedPointer ? U | null : PointerValue - : T extends NativeFunctionType ? T extends NativeTypedFunction ? PointerValue | null - : PointerValue - : T extends NativeBufferType ? BufferSource | null - : never; - - /** **UNSTABLE**: New API, yet to be vetted. - * - * Type conversion for unsafe callback return types. - * - * @category FFI - */ - type ToNativeResultType = T extends NativeStructType ? BufferSource - : T extends NativeNumberType ? T extends NativeU8Enum ? U - : T extends NativeI8Enum ? U - : T extends NativeU16Enum ? U - : T extends NativeI16Enum ? U - : T extends NativeU32Enum ? U - : T extends NativeI32Enum ? U - : number - : T extends NativeBigIntType ? number | bigint - : T extends NativeBooleanType ? boolean - : T extends NativePointerType ? T extends NativeTypedPointer ? U | null : PointerValue - : T extends NativeFunctionType ? T extends NativeTypedFunction ? PointerObject | null - : PointerValue - : T extends NativeBufferType ? BufferSource | null - : T extends NativeVoidType ? void - : never; - - /** **UNSTABLE**: New API, yet to be vetted. - * - * A utility type for conversion of parameter types of foreign functions. - * - * @category FFI - */ - type ToNativeParameterTypes = - // - [(T[number])[]] extends [T] ? ToNativeType[] - : [readonly (T[number])[]] extends [T] ? readonly ToNativeType[] - : T extends readonly [...NativeType[]] ? { - [K in keyof T]: ToNativeType; - } - : never; - - /** **UNSTABLE**: New API, yet to be vetted. - * - * Type conversion for foreign symbol return types and unsafe callback - * parameters. - * - * @category FFI - */ - type FromNativeType = T extends NativeStructType ? Uint8Array - : T extends NativeNumberType ? T extends NativeU8Enum ? U - : T extends NativeI8Enum ? U - : T extends NativeU16Enum ? U - : T extends NativeI16Enum ? U - : T extends NativeU32Enum ? U - : T extends NativeI32Enum ? U - : number - : T extends NativeBigIntType ? number | bigint - : T extends NativeBooleanType ? boolean - : T extends NativePointerType ? T extends NativeTypedPointer ? U | null : PointerValue - : T extends NativeBufferType ? PointerValue - : T extends NativeFunctionType ? T extends NativeTypedFunction ? PointerObject | null - : PointerValue - : never; - - /** **UNSTABLE**: New API, yet to be vetted. - * - * Type conversion for foreign symbol return types. - * - * @category FFI - */ - type FromNativeResultType = T extends NativeStructType ? Uint8Array - : T extends NativeNumberType ? T extends NativeU8Enum ? U - : T extends NativeI8Enum ? U - : T extends NativeU16Enum ? U - : T extends NativeI16Enum ? U - : T extends NativeU32Enum ? U - : T extends NativeI32Enum ? U - : number - : T extends NativeBigIntType ? number | bigint - : T extends NativeBooleanType ? boolean - : T extends NativePointerType ? T extends NativeTypedPointer ? U | null : PointerValue - : T extends NativeBufferType ? PointerValue - : T extends NativeFunctionType ? T extends NativeTypedFunction ? PointerObject | null - : PointerValue - : T extends NativeVoidType ? void - : never; - - /** **UNSTABLE**: New API, yet to be vetted. - * - * @category FFI - */ - type FromNativeParameterTypes< - T extends readonly NativeType[], - > = - // - [(T[number])[]] extends [T] ? FromNativeType[] - : [readonly (T[number])[]] extends [T] ? readonly FromNativeType[] - : T extends readonly [...NativeType[]] ? { - [K in keyof T]: FromNativeType; - } - : never; - - /** **UNSTABLE**: New API, yet to be vetted. - * - * The interface for a foreign function as defined by its parameter and result - * types. - * - * @category FFI - */ - export interface ForeignFunction< - Parameters extends readonly NativeType[] = readonly NativeType[], - Result extends NativeResultType = NativeResultType, - NonBlocking extends boolean = boolean, - > { - /** Name of the symbol. - * - * Defaults to the key name in symbols object. */ - name?: string; - /** The parameters of the foreign function. */ - parameters: Parameters; - /** The result (return value) of the foreign function. */ - result: Result; - /** When `true`, function calls will run on a dedicated blocking thread and - * will return a `Promise` resolving to the `result`. */ - nonblocking?: NonBlocking; - /** When `true`, function calls can safely callback into JavaScript or - * trigger a garbage collection event. - * - * @default {false} */ - callback?: boolean; - /** When `true`, dlopen will not fail if the symbol is not found. - * Instead, the symbol will be set to `null`. - * - * @default {false} */ - optional?: boolean; - } - - /** **UNSTABLE**: New API, yet to be vetted. - * - * @category FFI - */ - export interface ForeignStatic { - /** Name of the symbol, defaults to the key name in symbols object. */ - name?: string; - /** The type of the foreign static value. */ - type: Type; - /** When `true`, dlopen will not fail if the symbol is not found. - * Instead, the symbol will be set to `null`. - * - * @default {false} */ - optional?: boolean; - } - - /** **UNSTABLE**: New API, yet to be vetted. - * - * A foreign library interface descriptor. - * - * @category FFI - */ - export interface ForeignLibraryInterface { - [name: string]: ForeignFunction | ForeignStatic; - } - - /** **UNSTABLE**: New API, yet to be vetted. - * - * A utility type that infers a foreign symbol. - * - * @category FFI - */ - type StaticForeignSymbol = T extends ForeignFunction - ? FromForeignFunction - : T extends ForeignStatic ? FromNativeType - : never; - - /** **UNSTABLE**: New API, yet to be vetted. - * - * @category FFI - */ - type FromForeignFunction = T["parameters"] extends readonly [] - ? () => StaticForeignSymbolReturnType - : ( - ...args: ToNativeParameterTypes - ) => StaticForeignSymbolReturnType; - - /** **UNSTABLE**: New API, yet to be vetted. - * - * @category FFI - */ - type StaticForeignSymbolReturnType = ConditionalAsync< - T["nonblocking"], - FromNativeResultType - >; - - /** **UNSTABLE**: New API, yet to be vetted. - * - * @category FFI - */ - type ConditionalAsync = IsAsync extends true ? Promise : T; - - /** **UNSTABLE**: New API, yet to be vetted. - * - * A utility type that infers a foreign library interface. - * - * @category FFI - */ - type StaticForeignLibraryInterface = { - [K in keyof T]: T[K]["optional"] extends true ? StaticForeignSymbol | null - : StaticForeignSymbol; - }; - - /** **UNSTABLE**: New API, yet to be vetted. - * - * A non-null pointer, represented as an object - * at runtime. The object's prototype is `null` - * and cannot be changed. The object cannot be - * assigned to either and is thus entirely read-only. - * - * To interact with memory through a pointer use the - * {@linkcode UnsafePointerView} class. To create a - * pointer from an address or the get the address of - * a pointer use the static methods of the - * {@linkcode UnsafePointer} class. - * - * @category FFI - */ - export type PointerObject = { [brand]: T }; - - /** **UNSTABLE**: New API, yet to be vetted. - * - * Pointers are represented either with a {@linkcode PointerObject} - * object or a `null` if the pointer is null. - * - * @category FFI - */ - export type PointerValue = null | PointerObject; - - /** **UNSTABLE**: New API, yet to be vetted. - * - * A collection of static functions for interacting with pointer objects. - * - * @category FFI - */ - export class UnsafePointer { - /** Create a pointer from a numeric value. This one is really dangerous! */ - static create(value: number | bigint): PointerValue; - /** Returns `true` if the two pointers point to the same address. */ - static equals(a: PointerValue, b: PointerValue): boolean; - /** Return the direct memory pointer to the typed array in memory. */ - static of( - value: Deno.UnsafeCallback | BufferSource, - ): PointerValue; - /** Return a new pointer offset from the original by `offset` bytes. */ - static offset( - value: PointerObject, - offset: number, - ): PointerValue; - /** Get the numeric value of a pointer */ - static value(value: PointerValue): number | bigint; - } - - /** **UNSTABLE**: New API, yet to be vetted. - * - * An unsafe pointer view to a memory location as specified by the `pointer` - * value. The `UnsafePointerView` API follows the standard built in interface - * {@linkcode DataView} for accessing the underlying types at an memory - * location (numbers, strings and raw bytes). - * - * @category FFI - */ - export class UnsafePointerView { - constructor(pointer: PointerObject); - - pointer: PointerObject; - - /** Gets a boolean at the specified byte offset from the pointer. */ - getBool(offset?: number): boolean; - /** Gets an unsigned 8-bit integer at the specified byte offset from the - * pointer. */ - getUint8(offset?: number): number; - /** Gets a signed 8-bit integer at the specified byte offset from the - * pointer. */ - getInt8(offset?: number): number; - /** Gets an unsigned 16-bit integer at the specified byte offset from the - * pointer. */ - getUint16(offset?: number): number; - /** Gets a signed 16-bit integer at the specified byte offset from the - * pointer. */ - getInt16(offset?: number): number; - /** Gets an unsigned 32-bit integer at the specified byte offset from the - * pointer. */ - getUint32(offset?: number): number; - /** Gets a signed 32-bit integer at the specified byte offset from the - * pointer. */ - getInt32(offset?: number): number; - /** Gets an unsigned 64-bit integer at the specified byte offset from the - * pointer. */ - getBigUint64(offset?: number): number | bigint; - /** Gets a signed 64-bit integer at the specified byte offset from the - * pointer. */ - getBigInt64(offset?: number): number | bigint; - /** Gets a signed 32-bit float at the specified byte offset from the - * pointer. */ - getFloat32(offset?: number): number; - /** Gets a signed 64-bit float at the specified byte offset from the - * pointer. */ - getFloat64(offset?: number): number; - /** Gets a pointer at the specified byte offset from the pointer */ - getPointer(offset?: number): PointerValue; - /** Gets a C string (`null` terminated string) at the specified byte offset - * from the pointer. */ - getCString(offset?: number): string; - /** Gets a C string (`null` terminated string) at the specified byte offset - * from the specified pointer. */ - static getCString( - pointer: PointerObject, - offset?: number, - ): string; - /** Gets an `ArrayBuffer` of length `byteLength` at the specified byte - * offset from the pointer. */ - getArrayBuffer(byteLength: number, offset?: number): ArrayBuffer; - /** Gets an `ArrayBuffer` of length `byteLength` at the specified byte - * offset from the specified pointer. */ - static getArrayBuffer( - pointer: PointerObject, - byteLength: number, - offset?: number, - ): ArrayBuffer; - /** Copies the memory of the pointer into a typed array. - * - * Length is determined from the typed array's `byteLength`. - * - * Also takes optional byte offset from the pointer. */ - copyInto(destination: BufferSource, offset?: number): void; - /** Copies the memory of the specified pointer into a typed array. - * - * Length is determined from the typed array's `byteLength`. - * - * Also takes optional byte offset from the pointer. */ - static copyInto( - pointer: PointerObject, - destination: BufferSource, - offset?: number, - ): void; - } - - /** **UNSTABLE**: New API, yet to be vetted. - * - * An unsafe pointer to a function, for calling functions that are not present - * as symbols. - * - * @category FFI - */ - export class UnsafeFnPointer { - /** The pointer to the function. */ - pointer: PointerObject; - /** The definition of the function. */ - definition: Fn; - - constructor(pointer: PointerObject>, definition: Fn); - /** @deprecated Properly type {@linkcode pointer} using {@linkcode NativeTypedFunction} or {@linkcode UnsafeCallbackDefinition} types. */ - constructor(pointer: PointerObject, definition: Fn); - - /** Call the foreign function. */ - call: FromForeignFunction; - } - - /** **UNSTABLE**: New API, yet to be vetted. - * - * Definition of a unsafe callback function. - * - * @category FFI - */ - export interface UnsafeCallbackDefinition< - Parameters extends readonly NativeType[] = readonly NativeType[], - Result extends NativeResultType = NativeResultType, - > { - /** The parameters of the callbacks. */ - parameters: Parameters; - /** The current result of the callback. */ - result: Result; - } - - /** **UNSTABLE**: New API, yet to be vetted. - * - * An unsafe callback function. - * - * @category FFI - */ - type UnsafeCallbackFunction< - Parameters extends readonly NativeType[] = readonly NativeType[], - Result extends NativeResultType = NativeResultType, - > = Parameters extends readonly [] ? () => ToNativeResultType : ( - ...args: FromNativeParameterTypes - ) => ToNativeResultType; - - /** **UNSTABLE**: New API, yet to be vetted. - * - * An unsafe function pointer for passing JavaScript functions as C function - * pointers to foreign function calls. - * - * The function pointer remains valid until the `close()` method is called. - * - * All `UnsafeCallback` are always thread safe in that they can be called from - * foreign threads without crashing. However, they do not wake up the Deno event - * loop by default. - * - * If a callback is to be called from foreign threads, use the `threadSafe()` - * static constructor or explicitly call `ref()` to have the callback wake up - * the Deno event loop when called from foreign threads. This also stops - * Deno's process from exiting while the callback still exists and is not - * unref'ed. - * - * Use `deref()` to then allow Deno's process to exit. Calling `deref()` on - * a ref'ed callback does not stop it from waking up the Deno event loop when - * called from foreign threads. - * - * @category FFI - */ - export class UnsafeCallback< - const Definition extends UnsafeCallbackDefinition = UnsafeCallbackDefinition, - > { - constructor( - definition: Definition, - callback: UnsafeCallbackFunction< - Definition["parameters"], - Definition["result"] - >, - ); - - /** The pointer to the unsafe callback. */ - readonly pointer: PointerObject; - /** The definition of the unsafe callback. */ - readonly definition: Definition; - /** The callback function. */ - readonly callback: UnsafeCallbackFunction< - Definition["parameters"], - Definition["result"] - >; - - /** - * Creates an {@linkcode UnsafeCallback} and calls `ref()` once to allow it to - * wake up the Deno event loop when called from foreign threads. - * - * This also stops Deno's process from exiting while the callback still - * exists and is not unref'ed. - */ - static threadSafe< - Definition extends UnsafeCallbackDefinition = UnsafeCallbackDefinition, - >( - definition: Definition, - callback: UnsafeCallbackFunction< - Definition["parameters"], - Definition["result"] - >, - ): UnsafeCallback; - - /** - * Increments the callback's reference counting and returns the new - * reference count. - * - * After `ref()` has been called, the callback always wakes up the - * Deno event loop when called from foreign threads. - * - * If the callback's reference count is non-zero, it keeps Deno's - * process from exiting. - */ - ref(): number; - - /** - * Decrements the callback's reference counting and returns the new - * reference count. - * - * Calling `unref()` does not stop a callback from waking up the Deno - * event loop when called from foreign threads. - * - * If the callback's reference counter is zero, it no longer keeps - * Deno's process from exiting. - */ - unref(): number; - - /** - * Removes the C function pointer associated with this instance. - * - * Continuing to use the instance or the C function pointer after closing - * the `UnsafeCallback` will lead to errors and crashes. - * - * Calling this method sets the callback's reference counting to zero, - * stops the callback from waking up the Deno event loop when called from - * foreign threads and no longer keeps Deno's process from exiting. - */ - close(): void; - } - - /** **UNSTABLE**: New API, yet to be vetted. - * - * A dynamic library resource. Use {@linkcode Deno.dlopen} to load a dynamic - * library and return this interface. - * - * @category FFI - */ - export interface DynamicLibrary { - /** All of the registered library along with functions for calling them. */ - symbols: StaticForeignLibraryInterface; - /** Removes the pointers associated with the library symbols. - * - * Continuing to use symbols that are part of the library will lead to - * errors and crashes. - * - * Calling this method will also immediately set any references to zero and - * will no longer keep Deno's process from exiting. - */ - close(): void; - } - - /** **UNSTABLE**: New API, yet to be vetted. - * - * Opens an external dynamic library and registers symbols, making foreign - * functions available to be called. - * - * Requires `allow-ffi` permission. Loading foreign dynamic libraries can in - * theory bypass all of the sandbox permissions. While it is a separate - * permission users should acknowledge in practice that is effectively the - * same as running with the `allow-all` permission. - * - * @example Given a C library which exports a foreign function named `add()` - * - * ```ts - * // Determine library extension based on - * // your OS. - * let libSuffix = ""; - * switch (Deno.build.os) { - * case "windows": - * libSuffix = "dll"; - * break; - * case "darwin": - * libSuffix = "dylib"; - * break; - * default: - * libSuffix = "so"; - * break; - * } - * - * const libName = `./libadd.${libSuffix}`; - * // Open library and define exported symbols - * const dylib = Deno.dlopen( - * libName, - * { - * "add": { parameters: ["isize", "isize"], result: "isize" }, - * } as const, - * ); - * - * // Call the symbol `add` - * const result = dylib.symbols.add(35, 34); // 69 - * - * console.log(`Result from external addition of 35 and 34: ${result}`); - * ``` - * - * @tags allow-ffi - * @category FFI - */ - export function dlopen( - filename: string | URL, - symbols: S, - ): DynamicLibrary; - - /** **UNSTABLE**: New API, yet to be vetted. - * - * Creates a presentable WebGPU surface from given window and - * display handles. - * - * The parameters correspond to the table below: - * - * | system | winHandle | displayHandle | - * | ----------------- | ------------- | --------------- | - * | "cocoa" (macOS) | `NSView*` | - | - * | "win32" (Windows) | `HWND` | `HINSTANCE` | - * | "x11" (Linux) | Xlib `Window` | Xlib `Display*` | - * - * @category WebGPU - */ - export class UnsafeWindowSurface { - constructor( - system: "cocoa" | "win32" | "x11", - windowHandle: Deno.PointerValue, - displayHandle: Deno.PointerValue, - ); - getContext(context: "webgpu"): GPUCanvasContext; - present(): void; - } - - /** **UNSTABLE**: New API, yet to be vetted. - * - * These are unstable options which can be used with {@linkcode Deno.run}. - * - * @category Sub Process - */ - interface UnstableRunOptions extends RunOptions { - /** If `true`, clears the environment variables before executing the - * sub-process. - * - * @default {false} */ - clearEnv?: boolean; - /** For POSIX systems, sets the group ID for the sub process. */ - gid?: number; - /** For POSIX systems, sets the user ID for the sub process. */ - uid?: number; - } - - /** **UNSTABLE**: New API, yet to be vetted. - * - * Spawns new subprocess. RunOptions must contain at a minimum the `opt.cmd`, - * an array of program arguments, the first of which is the binary. - * - * ```ts - * const p = Deno.run({ - * cmd: ["curl", "https://example.com"], - * }); - * const status = await p.status(); - * ``` - * - * Subprocess uses same working directory as parent process unless `opt.cwd` - * is specified. - * - * Environmental variables from parent process can be cleared using `opt.clearEnv`. - * Doesn't guarantee that only `opt.env` variables are present, - * as the OS may set environmental variables for processes. - * - * Environmental variables for subprocess can be specified using `opt.env` - * mapping. - * - * `opt.uid` sets the child process’s user ID. This translates to a setuid call - * in the child process. Failure in the setuid call will cause the spawn to fail. - * - * `opt.gid` is similar to `opt.uid`, but sets the group ID of the child process. - * This has the same semantics as the uid field. - * - * By default subprocess inherits stdio of parent process. To change - * this this, `opt.stdin`, `opt.stdout`, and `opt.stderr` can be set - * independently to a resource ID (_rid_) of an open file, `"inherit"`, - * `"piped"`, or `"null"`: - * - * - _number_: the resource ID of an open file/resource. This allows you to - * read or write to a file. - * - `"inherit"`: The default if unspecified. The subprocess inherits from the - * parent. - * - `"piped"`: A new pipe should be arranged to connect the parent and child - * sub-process. - * - `"null"`: This stream will be ignored. This is the equivalent of attaching - * the stream to `/dev/null`. - * - * Details of the spawned process are returned as an instance of - * {@linkcode Deno.Process}. - * - * Requires `allow-run` permission. - * - * @tags allow-run - * @category Sub Process - */ - export function run( - opt: T, - ): Process; - - /** **UNSTABLE**: New API, yet to be vetted. - * - * A custom `HttpClient` for use with {@linkcode fetch} function. This is - * designed to allow custom certificates or proxies to be used with `fetch()`. - * - * @example ```ts - * const caCert = await Deno.readTextFile("./ca.pem"); - * const client = Deno.createHttpClient({ caCerts: [ caCert ] }); - * const req = await fetch("https://myserver.com", { client }); - * ``` - * - * @category Fetch API - */ - export interface HttpClient extends Disposable { - /** Close the HTTP client. */ - close(): void; - } - - /** **UNSTABLE**: New API, yet to be vetted. - * - * The options used when creating a {@linkcode Deno.HttpClient}. - * - * @category Fetch API - */ - export interface CreateHttpClientOptions { - /** A list of root certificates that will be used in addition to the - * default root certificates to verify the peer's certificate. - * - * Must be in PEM format. */ - caCerts?: string[]; - /** A HTTP proxy to use for new connections. */ - proxy?: Proxy; - /** Cert chain in PEM format. */ - cert?: string; - /** Server private key in PEM format. */ - key?: string; - /** Sets the maximum numer of idle connections per host allowed in the pool. */ - poolMaxIdlePerHost?: number; - /** Set an optional timeout for idle sockets being kept-alive. - * Set to false to disable the timeout. */ - poolIdleTimeout?: number | false; - /** - * Whether HTTP/1.1 is allowed or not. - * - * @default {true} - */ - http1?: boolean; - /** Whether HTTP/2 is allowed or not. - * - * @default {true} - */ - http2?: boolean; - /** Whether setting the host header is allowed or not. - * - * @default {false} - */ - allowHost?: boolean; - } - - /** **UNSTABLE**: New API, yet to be vetted. - * - * The definition of a proxy when specifying - * {@linkcode Deno.CreateHttpClientOptions}. - * - * @category Fetch API - */ - export interface Proxy { - /** The string URL of the proxy server to use. */ - url: string; - /** The basic auth credentials to be used against the proxy server. */ - basicAuth?: BasicAuth; - } - - /** **UNSTABLE**: New API, yet to be vetted. - * - * Basic authentication credentials to be used with a {@linkcode Deno.Proxy} - * server when specifying {@linkcode Deno.CreateHttpClientOptions}. - * - * @category Fetch API - */ - export interface BasicAuth { - /** The username to be used against the proxy server. */ - username: string; - /** The password to be used against the proxy server. */ - password: string; - } - - /** **UNSTABLE**: New API, yet to be vetted. - * - * Create a custom HttpClient to use with {@linkcode fetch}. This is an - * extension of the web platform Fetch API which allows Deno to use custom - * TLS certificates and connect via a proxy while using `fetch()`. - * - * @example ```ts - * const caCert = await Deno.readTextFile("./ca.pem"); - * const client = Deno.createHttpClient({ caCerts: [ caCert ] }); - * const response = await fetch("https://myserver.com", { client }); - * ``` - * - * @example ```ts - * const client = Deno.createHttpClient({ - * proxy: { url: "http://myproxy.com:8080" } - * }); - * const response = await fetch("https://myserver.com", { client }); - * ``` - * - * @category Fetch API - */ - export function createHttpClient( - options: CreateHttpClientOptions, - ): HttpClient; - - /** **UNSTABLE**: New API, yet to be vetted. - * - * Represents membership of a IPv4 multicast group. - * - * @category Network - */ - interface MulticastV4Membership { - /** Leaves the multicast group. */ - leave: () => Promise; - /** Sets the multicast loopback option. If enabled, multicast packets will be looped back to the local socket. */ - setLoopback: (loopback: boolean) => Promise; - /** Sets the time-to-live of outgoing multicast packets for this socket. */ - setTTL: (ttl: number) => Promise; - } - - /** **UNSTABLE**: New API, yet to be vetted. - * - * Represents membership of a IPv6 multicast group. - * - * @category Network - */ - interface MulticastV6Membership { - /** Leaves the multicast group. */ - leave: () => Promise; - /** Sets the multicast loopback option. If enabled, multicast packets will be looped back to the local socket. */ - setLoopback: (loopback: boolean) => Promise; - } - - /** **UNSTABLE**: New API, yet to be vetted. - * - * A generic transport listener for message-oriented protocols. - * - * @category Network - */ - export interface DatagramConn extends AsyncIterable<[Uint8Array, Addr]> { - /** Joins an IPv4 multicast group. */ - joinMulticastV4( - address: string, - networkInterface: string, - ): Promise; - - /** Joins an IPv6 multicast group. */ - joinMulticastV6( - address: string, - networkInterface: number, - ): Promise; - - /** Waits for and resolves to the next message to the instance. - * - * Messages are received in the format of a tuple containing the data array - * and the address information. - */ - receive(p?: Uint8Array): Promise<[Uint8Array, Addr]>; - /** Sends a message to the target via the connection. The method resolves - * with the number of bytes sent. */ - send(p: Uint8Array, addr: Addr): Promise; - /** Close closes the socket. Any pending message promises will be rejected - * with errors. */ - close(): void; - /** Return the address of the instance. */ - readonly addr: Addr; - [Symbol.asyncIterator](): AsyncIterableIterator<[Uint8Array, Addr]>; - } - - /** - * @category Network - */ - export interface TcpListenOptions extends ListenOptions { - /** When `true` the SO_REUSEPORT flag will be set on the listener. This - * allows multiple processes to listen on the same address and port. - * - * On Linux this will cause the kernel to distribute incoming connections - * across the different processes that are listening on the same address and - * port. - * - * This flag is only supported on Linux. It is silently ignored on other - * platforms. - * - * @default {false} */ - reusePort?: boolean; - } - - /** **UNSTABLE**: New API, yet to be vetted. - * - * Unstable options which can be set when opening a datagram listener via - * {@linkcode Deno.listenDatagram}. - * - * @category Network - */ - export interface UdpListenOptions extends ListenOptions { - /** When `true` the specified address will be reused, even if another - * process has already bound a socket on it. This effectively steals the - * socket from the listener. - * - * @default {false} */ - reuseAddress?: boolean; - - /** When `true`, sent multicast packets will be looped back to the local socket. - * - * @default {false} */ - loopback?: boolean; - } - - /** **UNSTABLE**: New API, yet to be vetted. - * - * Listen announces on the local transport address. - * - * ```ts - * const listener1 = Deno.listenDatagram({ - * port: 80, - * transport: "udp" - * }); - * const listener2 = Deno.listenDatagram({ - * hostname: "golang.org", - * port: 80, - * transport: "udp" - * }); - * ``` - * - * Requires `allow-net` permission. - * - * @tags allow-net - * @category Network - */ - export function listenDatagram( - options: UdpListenOptions & { transport: "udp" }, - ): DatagramConn; - - /** **UNSTABLE**: New API, yet to be vetted. - * - * Listen announces on the local transport address. - * - * ```ts - * const listener = Deno.listenDatagram({ - * path: "/foo/bar.sock", - * transport: "unixpacket" - * }); - * ``` - * - * Requires `allow-read` and `allow-write` permission. - * - * @tags allow-read, allow-write - * @category Network - */ - export function listenDatagram( - options: UnixListenOptions & { transport: "unixpacket" }, - ): DatagramConn; - - /** **UNSTABLE**: New API, yet to be vetted. - * - * Acquire an advisory file-system lock for the provided file. - * - * @param [exclusive=false] - * @category File System - */ - export function flock(rid: number, exclusive?: boolean): Promise; - - /** **UNSTABLE**: New API, yet to be vetted. - * - * Acquire an advisory file-system lock synchronously for the provided file. - * - * @param [exclusive=false] - * @category File System - */ - export function flockSync(rid: number, exclusive?: boolean): void; - - /** **UNSTABLE**: New API, yet to be vetted. - * - * Release an advisory file-system lock for the provided file. - * - * @category File System - */ - export function funlock(rid: number): Promise; - - /** **UNSTABLE**: New API, yet to be vetted. - * - * Release an advisory file-system lock for the provided file synchronously. - * - * @category File System - */ - export function funlockSync(rid: number): void; - - /** **UNSTABLE**: New API, yet to be vetted. - * - * Open a new {@linkcode Deno.Kv} connection to persist data. - * - * When a path is provided, the database will be persisted to disk at that - * path. Read and write access to the file is required. - * - * When no path is provided, the database will be opened in a default path for - * the current script. This location is persistent across script runs and is - * keyed on the origin storage key (the same key that is used to determine - * `localStorage` persistence). More information about the origin storage key - * can be found in the Deno Manual. - * - * @tags allow-read, allow-write - * @category KV - */ - export function openKv(path?: string): Promise; - - /** **UNSTABLE**: New API, yet to be vetted. - * - * CronScheduleExpression is used as the type of `minute`, `hour`, - * `dayOfMonth`, `month`, and `dayOfWeek` in {@linkcode CronSchedule}. - * @category Cron - */ - type CronScheduleExpression = number | { exact: number | number[] } | { - start?: number; - end?: number; - every?: number; - }; - - /** **UNSTABLE**: New API, yet to be vetted. - * - * CronSchedule is the interface used for JSON format - * cron `schedule`. - * @category Cron - */ - export interface CronSchedule { - minute?: CronScheduleExpression; - hour?: CronScheduleExpression; - dayOfMonth?: CronScheduleExpression; - month?: CronScheduleExpression; - dayOfWeek?: CronScheduleExpression; - } - - /** **UNSTABLE**: New API, yet to be vetted. - * - * Create a cron job that will periodically execute the provided handler - * callback based on the specified schedule. - * - * ```ts - * Deno.cron("sample cron", "20 * * * *", () => { - * console.log("cron job executed"); - * }); - * ``` - * - * ```ts - * Deno.cron("sample cron", { hour: { every: 6 } }, () => { - * console.log("cron job executed"); - * }); - * ``` - * - * `schedule` can be a string in the Unix cron format or in JSON format - * as specified by interface {@linkcode CronSchedule}, where time is specified - * using UTC time zone. - * - * @category Cron - */ - export function cron( - name: string, - schedule: string | CronSchedule, - handler: () => Promise | void, - ): Promise; - - /** **UNSTABLE**: New API, yet to be vetted. - * - * Create a cron job that will periodically execute the provided handler - * callback based on the specified schedule. - * - * ```ts - * Deno.cron("sample cron", "20 * * * *", { - * backoffSchedule: [10, 20] - * }, () => { - * console.log("cron job executed"); - * }); - * ``` - * - * `schedule` can be a string in the Unix cron format or in JSON format - * as specified by interface {@linkcode CronSchedule}, where time is specified - * using UTC time zone. - * - * `backoffSchedule` option can be used to specify the retry policy for failed - * executions. Each element in the array represents the number of milliseconds - * to wait before retrying the execution. For example, `[1000, 5000, 10000]` - * means that a failed execution will be retried at most 3 times, with 1 - * second, 5 seconds, and 10 seconds delay between each retry. - * - * @category Cron - */ - export function cron( - name: string, - schedule: string | CronSchedule, - options: { backoffSchedule?: number[]; signal?: AbortSignal }, - handler: () => Promise | void, - ): Promise; - - /** **UNSTABLE**: New API, yet to be vetted. - * - * A key to be persisted in a {@linkcode Deno.Kv}. A key is a sequence - * of {@linkcode Deno.KvKeyPart}s. - * - * Keys are ordered lexicographically by their parts. The first part is the - * most significant, and the last part is the least significant. The order of - * the parts is determined by both the type and the value of the part. The - * relative significance of the types can be found in documentation for the - * {@linkcode Deno.KvKeyPart} type. - * - * Keys have a maximum size of 2048 bytes serialized. If the size of the key - * exceeds this limit, an error will be thrown on the operation that this key - * was passed to. - * - * @category KV - */ - export type KvKey = readonly KvKeyPart[]; - - /** **UNSTABLE**: New API, yet to be vetted. - * - * A single part of a {@linkcode Deno.KvKey}. Parts are ordered - * lexicographically, first by their type, and within a given type by their - * value. - * - * The ordering of types is as follows: - * - * 1. `Uint8Array` - * 2. `string` - * 3. `number` - * 4. `bigint` - * 5. `boolean` - * - * Within a given type, the ordering is as follows: - * - * - `Uint8Array` is ordered by the byte ordering of the array - * - `string` is ordered by the byte ordering of the UTF-8 encoding of the - * string - * - `number` is ordered following this pattern: `-NaN` - * < `-Infinity` < `-100.0` < `-1.0` < -`0.5` < `-0.0` < `0.0` < `0.5` - * < `1.0` < `100.0` < `Infinity` < `NaN` - * - `bigint` is ordered by mathematical ordering, with the largest negative - * number being the least first value, and the largest positive number - * being the last value - * - `boolean` is ordered by `false` < `true` - * - * This means that the part `1.0` (a number) is ordered before the part `2.0` - * (also a number), but is greater than the part `0n` (a bigint), because - * `1.0` is a number and `0n` is a bigint, and type ordering has precedence - * over the ordering of values within a type. - * - * @category KV - */ - export type KvKeyPart = - | Uint8Array - | string - | number - | bigint - | boolean - | symbol; - - /** **UNSTABLE**: New API, yet to be vetted. - * - * Consistency level of a KV operation. - * - * - `strong` - This operation must be strongly-consistent. - * - `eventual` - Eventually-consistent behavior is allowed. - * - * @category KV - */ - export type KvConsistencyLevel = "strong" | "eventual"; - - /** **UNSTABLE**: New API, yet to be vetted. - * - * A selector that selects the range of data returned by a list operation on a - * {@linkcode Deno.Kv}. - * - * The selector can either be a prefix selector or a range selector. A prefix - * selector selects all keys that start with the given prefix (optionally - * starting at a given key). A range selector selects all keys that are - * lexicographically between the given start and end keys. - * - * @category KV - */ - export type KvListSelector = - | { prefix: KvKey } - | { prefix: KvKey; start: KvKey } - | { prefix: KvKey; end: KvKey } - | { start: KvKey; end: KvKey }; - - /** **UNSTABLE**: New API, yet to be vetted. - * - * A mutation to a key in a {@linkcode Deno.Kv}. A mutation is a - * combination of a key, a value, and a type. The type determines how the - * mutation is applied to the key. - * - * - `set` - Sets the value of the key to the given value, overwriting any - * existing value. Optionally an `expireIn` option can be specified to - * set a time-to-live (TTL) for the key. The TTL is specified in - * milliseconds, and the key will be deleted from the database at earliest - * after the specified number of milliseconds have elapsed. Once the - * specified duration has passed, the key may still be visible for some - * additional time. If the `expireIn` option is not specified, the key will - * not expire. - * - `delete` - Deletes the key from the database. The mutation is a no-op if - * the key does not exist. - * - `sum` - Adds the given value to the existing value of the key. Both the - * value specified in the mutation, and any existing value must be of type - * `Deno.KvU64`. If the key does not exist, the value is set to the given - * value (summed with 0). If the result of the sum overflows an unsigned - * 64-bit integer, the result is wrapped around. - * - `max` - Sets the value of the key to the maximum of the existing value - * and the given value. Both the value specified in the mutation, and any - * existing value must be of type `Deno.KvU64`. If the key does not exist, - * the value is set to the given value. - * - `min` - Sets the value of the key to the minimum of the existing value - * and the given value. Both the value specified in the mutation, and any - * existing value must be of type `Deno.KvU64`. If the key does not exist, - * the value is set to the given value. - * - * @category KV - */ - export type KvMutation = - & { key: KvKey } - & ( - | { type: "set"; value: unknown; expireIn?: number } - | { type: "delete" } - | { type: "sum"; value: KvU64 } - | { type: "max"; value: KvU64 } - | { type: "min"; value: KvU64 } - ); - - /** **UNSTABLE**: New API, yet to be vetted. - * - * An iterator over a range of data entries in a {@linkcode Deno.Kv}. - * - * The cursor getter returns the cursor that can be used to resume the - * iteration from the current position in the future. - * - * @category KV - */ - export class KvListIterator implements AsyncIterableIterator> { - /** - * Returns the cursor of the current position in the iteration. This cursor - * can be used to resume the iteration from the current position in the - * future by passing it to the `cursor` option of the `list` method. - */ - get cursor(): string; - - next(): Promise, undefined>>; - [Symbol.asyncIterator](): AsyncIterableIterator>; - } - - /** **UNSTABLE**: New API, yet to be vetted. - * - * A versioned pair of key and value in a {@linkcode Deno.Kv}. - * - * The `versionstamp` is a string that represents the current version of the - * key-value pair. It can be used to perform atomic operations on the KV store - * by passing it to the `check` method of a {@linkcode Deno.AtomicOperation}. - * - * @category KV - */ - export type KvEntry = { key: KvKey; value: T; versionstamp: string }; - - /** - * **UNSTABLE**: New API, yet to be vetted. - * - * An optional versioned pair of key and value in a {@linkcode Deno.Kv}. - * - * This is the same as a {@linkcode KvEntry}, but the `value` and `versionstamp` - * fields may be `null` if no value exists for the given key in the KV store. - * - * @category KV - */ - export type KvEntryMaybe = KvEntry | { - key: KvKey; - value: null; - versionstamp: null; - }; - - /** **UNSTABLE**: New API, yet to be vetted. - * - * Options for listing key-value pairs in a {@linkcode Deno.Kv}. - * - * @category KV - */ - export interface KvListOptions { - /** - * The maximum number of key-value pairs to return. If not specified, all - * matching key-value pairs will be returned. - */ - limit?: number; - /** - * The cursor to resume the iteration from. If not specified, the iteration - * will start from the beginning. - */ - cursor?: string; - /** - * Whether to reverse the order of the returned key-value pairs. If not - * specified, the order will be ascending from the start of the range as per - * the lexicographical ordering of the keys. If `true`, the order will be - * descending from the end of the range. - * - * The default value is `false`. - */ - reverse?: boolean; - /** - * The consistency level of the list operation. The default consistency - * level is "strong". Some use cases can benefit from using a weaker - * consistency level. For more information on consistency levels, see the - * documentation for {@linkcode Deno.KvConsistencyLevel}. - * - * List operations are performed in batches (in sizes specified by the - * `batchSize` option). The consistency level of the list operation is - * applied to each batch individually. This means that while each batch is - * guaranteed to be consistent within itself, the entire list operation may - * not be consistent across batches because a mutation may be applied to a - * key-value pair between batches, in a batch that has already been returned - * by the list operation. - */ - consistency?: KvConsistencyLevel; - /** - * The size of the batches in which the list operation is performed. Larger - * or smaller batch sizes may positively or negatively affect the - * performance of a list operation depending on the specific use case and - * iteration behavior. Slow iterating queries may benefit from using a - * smaller batch size for increased overall consistency, while fast - * iterating queries may benefit from using a larger batch size for better - * performance. - * - * The default batch size is equal to the `limit` option, or 100 if this is - * unset. The maximum value for this option is 500. Larger values will be - * clamped. - */ - batchSize?: number; - } - - /** @category KV */ - export interface KvCommitResult { - ok: true; - /** The versionstamp of the value committed to KV. */ - versionstamp: string; - } - - /** @category KV */ - export interface KvCommitError { - ok: false; - } - - /** **UNSTABLE**: New API, yet to be vetted. - * - * A check to perform as part of a {@linkcode Deno.AtomicOperation}. The check - * will fail if the versionstamp for the key-value pair in the KV store does - * not match the given versionstamp. A check with a `null` versionstamp checks - * that the key-value pair does not currently exist in the KV store. - * - * @category KV - */ - export interface AtomicCheck { - key: KvKey; - versionstamp: string | null; - } - - /** **UNSTABLE**: New API, yet to be vetted. - * - * An operation on a {@linkcode Deno.Kv} that can be performed - * atomically. Atomic operations do not auto-commit, and must be committed - * explicitly by calling the `commit` method. - * - * Atomic operations can be used to perform multiple mutations on the KV store - * in a single atomic transaction. They can also be used to perform - * conditional mutations by specifying one or more - * {@linkcode Deno.AtomicCheck}s that ensure that a mutation is only performed - * if the key-value pair in the KV has a specific versionstamp. If any of the - * checks fail, the entire operation will fail and no mutations will be made. - * - * The ordering of mutations is guaranteed to be the same as the ordering of - * the mutations specified in the operation. Checks are performed before any - * mutations are performed. The ordering of checks is unobservable. - * - * Atomic operations can be used to implement optimistic locking, where a - * mutation is only performed if the key-value pair in the KV store has not - * been modified since the last read. This can be done by specifying a check - * that ensures that the versionstamp of the key-value pair matches the - * versionstamp that was read. If the check fails, the mutation will not be - * performed and the operation will fail. One can then retry the read-modify- - * write operation in a loop until it succeeds. - * - * The `commit` method of an atomic operation returns a value indicating - * whether checks passed and mutations were performed. If the operation failed - * because of a failed check, the return value will be a - * {@linkcode Deno.KvCommitError} with an `ok: false` property. If the - * operation failed for any other reason (storage error, invalid value, etc.), - * an exception will be thrown. If the operation succeeded, the return value - * will be a {@linkcode Deno.KvCommitResult} object with a `ok: true` property - * and the versionstamp of the value committed to KV. - - * - * @category KV - */ - export class AtomicOperation { - /** - * Add to the operation a check that ensures that the versionstamp of the - * key-value pair in the KV store matches the given versionstamp. If the - * check fails, the entire operation will fail and no mutations will be - * performed during the commit. - */ - check(...checks: AtomicCheck[]): this; - /** - * Add to the operation a mutation that performs the specified mutation on - * the specified key if all checks pass during the commit. The types and - * semantics of all available mutations are described in the documentation - * for {@linkcode Deno.KvMutation}. - */ - mutate(...mutations: KvMutation[]): this; - /** - * Shortcut for creating a `sum` mutation. This method wraps `n` in a - * {@linkcode Deno.KvU64}, so the value of `n` must be in the range - * `[0, 2^64-1]`. - */ - sum(key: KvKey, n: bigint): this; - /** - * Shortcut for creating a `min` mutation. This method wraps `n` in a - * {@linkcode Deno.KvU64}, so the value of `n` must be in the range - * `[0, 2^64-1]`. - */ - min(key: KvKey, n: bigint): this; - /** - * Shortcut for creating a `max` mutation. This method wraps `n` in a - * {@linkcode Deno.KvU64}, so the value of `n` must be in the range - * `[0, 2^64-1]`. - */ - max(key: KvKey, n: bigint): this; - /** - * Add to the operation a mutation that sets the value of the specified key - * to the specified value if all checks pass during the commit. - * - * Optionally an `expireIn` option can be specified to set a time-to-live - * (TTL) for the key. The TTL is specified in milliseconds, and the key will - * be deleted from the database at earliest after the specified number of - * milliseconds have elapsed. Once the specified duration has passed, the - * key may still be visible for some additional time. If the `expireIn` - * option is not specified, the key will not expire. - */ - set(key: KvKey, value: unknown, options?: { expireIn?: number }): this; - /** - * Add to the operation a mutation that deletes the specified key if all - * checks pass during the commit. - */ - delete(key: KvKey): this; - /** - * Add to the operation a mutation that enqueues a value into the queue - * if all checks pass during the commit. - */ - enqueue( - value: unknown, - options?: { - delay?: number; - keysIfUndelivered?: Deno.KvKey[]; - backoffSchedule?: number[]; - }, - ): this; - /** - * Commit the operation to the KV store. Returns a value indicating whether - * checks passed and mutations were performed. If the operation failed - * because of a failed check, the return value will be a {@linkcode - * Deno.KvCommitError} with an `ok: false` property. If the operation failed - * for any other reason (storage error, invalid value, etc.), an exception - * will be thrown. If the operation succeeded, the return value will be a - * {@linkcode Deno.KvCommitResult} object with a `ok: true` property and the - * versionstamp of the value committed to KV. - * - * If the commit returns `ok: false`, one may create a new atomic operation - * with updated checks and mutations and attempt to commit it again. See the - * note on optimistic locking in the documentation for - * {@linkcode Deno.AtomicOperation}. - */ - commit(): Promise; - } - - /** **UNSTABLE**: New API, yet to be vetted. - * - * A key-value database that can be used to store and retrieve data. - * - * Data is stored as key-value pairs, where the key is a {@linkcode Deno.KvKey} - * and the value is an arbitrary structured-serializable JavaScript value. - * Keys are ordered lexicographically as described in the documentation for - * {@linkcode Deno.KvKey}. Keys are unique within a database, and the last - * value set for a given key is the one that is returned when reading the - * key. Keys can be deleted from the database, in which case they will no - * longer be returned when reading keys. - * - * Values can be any structured-serializable JavaScript value (objects, - * arrays, strings, numbers, etc.). The special value {@linkcode Deno.KvU64} - * can be used to store 64-bit unsigned integers in the database. This special - * value can not be nested within other objects or arrays. In addition to the - * regular database mutation operations, the unsigned 64-bit integer value - * also supports `sum`, `max`, and `min` mutations. - * - * Keys are versioned on write by assigning the key an ever-increasing - * "versionstamp". The versionstamp represents the version of a key-value pair - * in the database at some point in time, and can be used to perform - * transactional operations on the database without requiring any locking. - * This is enabled by atomic operations, which can have conditions that ensure - * that the operation only succeeds if the versionstamp of the key-value pair - * matches an expected versionstamp. - * - * Keys have a maximum length of 2048 bytes after serialization. Values have a - * maximum length of 64 KiB after serialization. Serialization of both keys - * and values is somewhat opaque, but one can usually assume that the - * serialization of any value is about the same length as the resulting string - * of a JSON serialization of that same value. If theses limits are exceeded, - * an exception will be thrown. - * - * @category KV - */ - export class Kv implements Disposable { - /** - * Retrieve the value and versionstamp for the given key from the database - * in the form of a {@linkcode Deno.KvEntryMaybe}. If no value exists for - * the key, the returned entry will have a `null` value and versionstamp. - * - * ```ts - * const db = await Deno.openKv(); - * const result = await db.get(["foo"]); - * result.key; // ["foo"] - * result.value; // "bar" - * result.versionstamp; // "00000000000000010000" - * ``` - * - * The `consistency` option can be used to specify the consistency level - * for the read operation. The default consistency level is "strong". Some - * use cases can benefit from using a weaker consistency level. For more - * information on consistency levels, see the documentation for - * {@linkcode Deno.KvConsistencyLevel}. - */ - get( - key: KvKey, - options?: { consistency?: KvConsistencyLevel }, - ): Promise>; - - /** - * Retrieve multiple values and versionstamps from the database in the form - * of an array of {@linkcode Deno.KvEntryMaybe} objects. The returned array - * will have the same length as the `keys` array, and the entries will be in - * the same order as the keys. If no value exists for a given key, the - * returned entry will have a `null` value and versionstamp. - * - * ```ts - * const db = await Deno.openKv(); - * const result = await db.getMany([["foo"], ["baz"]]); - * result[0].key; // ["foo"] - * result[0].value; // "bar" - * result[0].versionstamp; // "00000000000000010000" - * result[1].key; // ["baz"] - * result[1].value; // null - * result[1].versionstamp; // null - * ``` - * - * The `consistency` option can be used to specify the consistency level - * for the read operation. The default consistency level is "strong". Some - * use cases can benefit from using a weaker consistency level. For more - * information on consistency levels, see the documentation for - * {@linkcode Deno.KvConsistencyLevel}. - */ - getMany( - keys: readonly [...{ [K in keyof T]: KvKey }], - options?: { consistency?: KvConsistencyLevel }, - ): Promise<{ [K in keyof T]: KvEntryMaybe }>; - /** - * Set the value for the given key in the database. If a value already - * exists for the key, it will be overwritten. - * - * ```ts - * const db = await Deno.openKv(); - * await db.set(["foo"], "bar"); - * ``` - * - * Optionally an `expireIn` option can be specified to set a time-to-live - * (TTL) for the key. The TTL is specified in milliseconds, and the key will - * be deleted from the database at earliest after the specified number of - * milliseconds have elapsed. Once the specified duration has passed, the - * key may still be visible for some additional time. If the `expireIn` - * option is not specified, the key will not expire. - */ - set( - key: KvKey, - value: unknown, - options?: { expireIn?: number }, - ): Promise; - - /** - * Delete the value for the given key from the database. If no value exists - * for the key, this operation is a no-op. - * - * ```ts - * const db = await Deno.openKv(); - * await db.delete(["foo"]); - * ``` - */ - delete(key: KvKey): Promise; - - /** - * Retrieve a list of keys in the database. The returned list is an - * {@linkcode Deno.KvListIterator} which can be used to iterate over the - * entries in the database. - * - * Each list operation must specify a selector which is used to specify the - * range of keys to return. The selector can either be a prefix selector, or - * a range selector: - * - * - A prefix selector selects all keys that start with the given prefix of - * key parts. For example, the selector `["users"]` will select all keys - * that start with the prefix `["users"]`, such as `["users", "alice"]` - * and `["users", "bob"]`. Note that you can not partially match a key - * part, so the selector `["users", "a"]` will not match the key - * `["users", "alice"]`. A prefix selector may specify a `start` key that - * is used to skip over keys that are lexicographically less than the - * start key. - * - A range selector selects all keys that are lexicographically between - * the given start and end keys (including the start, and excluding the - * end). For example, the selector `["users", "a"], ["users", "n"]` will - * select all keys that start with the prefix `["users"]` and have a - * second key part that is lexicographically between `a` and `n`, such as - * `["users", "alice"]`, `["users", "bob"]`, and `["users", "mike"]`, but - * not `["users", "noa"]` or `["users", "zoe"]`. - * - * ```ts - * const db = await Deno.openKv(); - * const entries = db.list({ prefix: ["users"] }); - * for await (const entry of entries) { - * entry.key; // ["users", "alice"] - * entry.value; // { name: "Alice" } - * entry.versionstamp; // "00000000000000010000" - * } - * ``` - * - * The `options` argument can be used to specify additional options for the - * list operation. See the documentation for {@linkcode Deno.KvListOptions} - * for more information. - */ - list( - selector: KvListSelector, - options?: KvListOptions, - ): KvListIterator; - - /** - * Add a value into the database queue to be delivered to the queue - * listener via {@linkcode Deno.Kv.listenQueue}. - * - * ```ts - * const db = await Deno.openKv(); - * await db.enqueue("bar"); - * ``` - * - * The `delay` option can be used to specify the delay (in milliseconds) - * of the value delivery. The default delay is 0, which means immediate - * delivery. - * - * ```ts - * const db = await Deno.openKv(); - * await db.enqueue("bar", { delay: 60000 }); - * ``` - * - * The `keysIfUndelivered` option can be used to specify the keys to - * be set if the value is not successfully delivered to the queue - * listener after several attempts. The values are set to the value of - * the queued message. - * - * The `backoffSchedule` option can be used to specify the retry policy for - * failed message delivery. Each element in the array represents the number of - * milliseconds to wait before retrying the delivery. For example, - * `[1000, 5000, 10000]` means that a failed delivery will be retried - * at most 3 times, with 1 second, 5 seconds, and 10 seconds delay - * between each retry. - * - * ```ts - * const db = await Deno.openKv(); - * await db.enqueue("bar", { - * keysIfUndelivered: [["foo", "bar"]], - * backoffSchedule: [1000, 5000, 10000], - * }); - * ``` - */ - enqueue( - value: unknown, - options?: { - delay?: number; - keysIfUndelivered?: Deno.KvKey[]; - backoffSchedule?: number[]; - }, - ): Promise; - - /** - * Listen for queue values to be delivered from the database queue, which - * were enqueued with {@linkcode Deno.Kv.enqueue}. The provided handler - * callback is invoked on every dequeued value. A failed callback - * invocation is automatically retried multiple times until it succeeds - * or until the maximum number of retries is reached. - * - * ```ts - * const db = await Deno.openKv(); - * db.listenQueue(async (msg: unknown) => { - * await db.set(["foo"], msg); - * }); - * ``` - */ - // deno-lint-ignore no-explicit-any - listenQueue(handler: (value: any) => Promise | void): Promise; - - /** - * Create a new {@linkcode Deno.AtomicOperation} object which can be used to - * perform an atomic transaction on the database. This does not perform any - * operations on the database - the atomic transaction must be committed - * explicitly using the {@linkcode Deno.AtomicOperation.commit} method once - * all checks and mutations have been added to the operation. - */ - atomic(): AtomicOperation; - - /** - * Watch for changes to the given keys in the database. The returned stream - * is a {@linkcode ReadableStream} that emits a new value whenever any of - * the watched keys change their versionstamp. The emitted value is an array - * of {@linkcode Deno.KvEntryMaybe} objects, with the same length and order - * as the `keys` array. If no value exists for a given key, the returned - * entry will have a `null` value and versionstamp. - * - * The returned stream does not return every single intermediate state of - * the watched keys, but rather only keeps you up to date with the latest - * state of the keys. This means that if a key is modified multiple times - * quickly, you may not receive a notification for every single change, but - * rather only the latest state of the key. - * - * ```ts - * const db = await Deno.openKv(); - * - * const stream = db.watch([["foo"], ["bar"]]); - * for await (const entries of stream) { - * entries[0].key; // ["foo"] - * entries[0].value; // "bar" - * entries[0].versionstamp; // "00000000000000010000" - * entries[1].key; // ["bar"] - * entries[1].value; // null - * entries[1].versionstamp; // null - * } - * ``` - * - * The `options` argument can be used to specify additional options for the - * watch operation. The `raw` option can be used to specify whether a new - * value should be emitted whenever a mutation occurs on any of the watched - * keys (even if the value of the key does not change, such as deleting a - * deleted key), or only when entries have observably changed in some way. - * When `raw: true` is used, it is possible for the stream to occasionally - * emit values even if no mutations have occurred on any of the watched - * keys. The default value for this option is `false`. - */ - watch( - keys: readonly [...{ [K in keyof T]: KvKey }], - options?: { raw?: boolean }, - ): ReadableStream<{ [K in keyof T]: KvEntryMaybe }>; - - /** - * Close the database connection. This will prevent any further operations - * from being performed on the database, and interrupt any in-flight - * operations immediately. - */ - close(): void; - - /** - * Get a symbol that represents the versionstamp of the current atomic - * operation. This symbol can be used as the last part of a key in - * `.set()`, both directly on the `Kv` object and on an `AtomicOperation` - * object created from this `Kv` instance. - */ - commitVersionstamp(): symbol; - - [Symbol.dispose](): void; - } - - /** **UNSTABLE**: New API, yet to be vetted. - * - * Wrapper type for 64-bit unsigned integers for use as values in a - * {@linkcode Deno.Kv}. - * - * @category KV - */ - export class KvU64 { - /** Create a new `KvU64` instance from the given bigint value. If the value - * is signed or greater than 64-bits, an error will be thrown. */ - constructor(value: bigint); - /** The value of this unsigned 64-bit integer, represented as a bigint. */ - readonly value: bigint; - } - - /** - * A namespace containing runtime APIs available in Jupyter notebooks. - * - * When accessed outside of Jupyter notebook context an error will be thrown. - * - * @category Jupyter */ - export namespace jupyter { - /** @category Jupyter */ - export interface DisplayOptions { - raw?: boolean; - update?: boolean; - display_id?: string; - } - - /** @category Jupyter */ - type VegaObject = { - $schema: string; - [key: string]: unknown; - }; - - /** - * A collection of supported media types and data for Jupyter frontends. - * - * @category Jupyter - */ - export type MediaBundle = { - "text/plain"?: string; - "text/html"?: string; - "image/svg+xml"?: string; - "text/markdown"?: string; - "application/javascript"?: string; - - // Images (per Jupyter spec) must be base64 encoded. We could _allow_ - // accepting Uint8Array or ArrayBuffer within `display` calls, however we still - // must encode them for jupyter. - "image/png"?: string; // WISH: Uint8Array | ArrayBuffer - "image/jpeg"?: string; // WISH: Uint8Array | ArrayBuffer - "image/gif"?: string; // WISH: Uint8Array | ArrayBuffer - "application/pdf"?: string; // WISH: Uint8Array | ArrayBuffer - - // NOTE: all JSON types must be objects at the top level (no arrays, strings, or other primitives) - "application/json"?: object; - "application/geo+json"?: object; - "application/vdom.v1+json"?: object; - "application/vnd.plotly.v1+json"?: object; - "application/vnd.vega.v5+json"?: VegaObject; - "application/vnd.vegalite.v4+json"?: VegaObject; - "application/vnd.vegalite.v5+json"?: VegaObject; - - // Must support a catch all for custom media types / mimetypes - [key: string]: string | object | undefined; - }; - - /** @category Jupyter */ - export const $display: unique symbol; - - /** @category Jupyter */ - export type Displayable = { - [$display]: () => MediaBundle | Promise; - }; - - /** - * Display function for Jupyter Deno Kernel. - * Mimics the behavior of IPython's `display(obj, raw=True)` function to allow - * asynchronous displaying of objects in Jupyter. - * - * @param obj - The object to be displayed - * @param options - Display options with a default { raw: true } - * @category Jupyter - */ - export function display(obj: unknown, options?: DisplayOptions): void; - - /** - * Show Markdown in Jupyter frontends with a tagged template function. - * - * Takes a template string and returns a displayable object for Jupyter frontends. - * - * @example - * Create a Markdown view. - * - * ```typescript - * const { md } = Deno.jupyter; - * md`# Notebooks in TypeScript via Deno ![Deno logo](https://github.com/denoland.png?size=32) - * - * * TypeScript ${Deno.version.typescript} - * * V8 ${Deno.version.v8} - * * Deno ${Deno.version.deno} - * - * Interactive compute with Jupyter _built into Deno_! - * ` - * ``` - * - * @category Jupyter - */ - export function md( - strings: TemplateStringsArray, - ...values: unknown[] - ): Displayable; - - /** - * Show HTML in Jupyter frontends with a tagged template function. - * - * Takes a template string and returns a displayable object for Jupyter frontends. - * - * @example - * Create an HTML view. - * ```typescript - * const { html } = Deno.jupyter; - * html`

Hello, world!

` - * ``` - * - * @category Jupyter - */ - export function html( - strings: TemplateStringsArray, - ...values: unknown[] - ): Displayable; - - /** - * SVG Tagged Template Function. - * - * Takes a template string and returns a displayable object for Jupyter frontends. - * - * Example usage: - * - * svg` - * - * ` - * - * @category Jupyter - */ - export function svg( - strings: TemplateStringsArray, - ...values: unknown[] - ): Displayable; - - /** - * Format an object for displaying in Deno - * - * @param obj - The object to be displayed - * @returns MediaBundle - * - * @category Jupyter - */ - export function format(obj: unknown): MediaBundle; - - /** - * Broadcast a message on IO pub channel. - * - * ``` - * await Deno.jupyter.broadcast("display_data", { - * data: { "text/html": "Processing." }, - * metadata: {}, - * transient: { display_id: "progress" } - * }); - * - * await new Promise((resolve) => setTimeout(resolve, 500)); - * - * await Deno.jupyter.broadcast("update_display_data", { - * data: { "text/html": "Processing.." }, - * metadata: {}, - * transient: { display_id: "progress" } - * }); - * ``` - * - * @category Jupyter */ - export function broadcast( - msgType: string, - content: Record, - extra?: { - metadata?: Record; - buffers?: Uint8Array[]; - }, - ): Promise; - } - - /** @category Network */ - export interface NetAddr { - transport: "tcp" | "udp"; - hostname: string; - port: number; - } - - /** @category Network */ - export interface UnixAddr { - transport: "unix" | "unixpacket"; - path: string; - } - - /** @category Network */ - export type Addr = NetAddr | UnixAddr; - - /** A generic network listener for stream-oriented protocols. - * - * @category Network - */ - export interface Listener extends AsyncIterable, Disposable { - /** Waits for and resolves to the next connection to the `Listener`. */ - accept(): Promise; - /** Close closes the listener. Any pending accept promises will be rejected - * with errors. */ - close(): void; - /** Return the address of the `Listener`. */ - readonly addr: A; - - /** - * Return the rid of the `Listener`. - * - * @deprecated This will be removed in Deno 2.0. See the - * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide} - * for migration instructions. - */ - readonly rid: number; - - [Symbol.asyncIterator](): AsyncIterableIterator; - - /** - * Make the listener block the event loop from finishing. - * - * Note: the listener blocks the event loop from finishing by default. - * This method is only meaningful after `.unref()` is called. - */ - ref(): void; - - /** Make the listener not block the event loop from finishing. */ - unref(): void; - } - - /** Specialized listener that accepts TLS connections. - * - * @category Network - */ - export type TlsListener = Listener; - - /** Specialized listener that accepts TCP connections. - * - * @category Network - */ - export type TcpListener = Listener; - - /** Specialized listener that accepts Unix connections. - * - * @category Network - */ - export type UnixListener = Listener; - - /** @category Network */ - export interface Conn extends Reader, Writer, Closer, Disposable { - /** The local address of the connection. */ - readonly localAddr: A; - /** The remote address of the connection. */ - readonly remoteAddr: A; - /** - * The resource ID of the connection. - * - * @deprecated This will be removed in Deno 2.0. See the - * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide} - * for migration instructions. - */ - readonly rid: number; - /** Shuts down (`shutdown(2)`) the write side of the connection. Most - * callers should just use `close()`. */ - closeWrite(): Promise; - - /** Make the connection block the event loop from finishing. - * - * Note: the connection blocks the event loop from finishing by default. - * This method is only meaningful after `.unref()` is called. - */ - ref(): void; - /** Make the connection not block the event loop from finishing. */ - unref(): void; - - readonly readable: ReadableStream; - readonly writable: WritableStream; - } - - /** @category Network */ - export interface TlsHandshakeInfo { - /** - * Contains the ALPN protocol selected during negotiation with the server. - * If no ALPN protocol selected, returns `null`. - */ - alpnProtocol: string | null; - } - - /** @category Network */ - export interface TlsConn extends Conn { - /** Runs the client or server handshake protocol to completion if that has - * not happened yet. Calling this method is optional; the TLS handshake - * will be completed automatically as soon as data is sent or received. */ - handshake(): Promise; - /** - * The resource ID of the connection. - * - * @deprecated This will be removed in Deno 2.0. See the - * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide} - * for migration instructions. - */ - readonly rid: number; - } - - /** @category Network */ - export interface ListenOptions { - /** The port to listen on. */ - port: number; - /** A literal IP address or host name that can be resolved to an IP address. - * - * __Note about `0.0.0.0`__ While listening `0.0.0.0` works on all platforms, - * the browsers on Windows don't work with the address `0.0.0.0`. - * You should show the message like `server running on localhost:8080` instead of - * `server running on 0.0.0.0:8080` if your program supports Windows. - * - * @default {"0.0.0.0"} */ - hostname?: string; - } - - /** @category Network */ - // deno-lint-ignore no-empty-interface - export interface TcpListenOptions extends ListenOptions { - } - - /** Listen announces on the local transport address. - * - * ```ts - * const listener1 = Deno.listen({ port: 80 }) - * const listener2 = Deno.listen({ hostname: "192.0.2.1", port: 80 }) - * const listener3 = Deno.listen({ hostname: "[2001:db8::1]", port: 80 }); - * const listener4 = Deno.listen({ hostname: "golang.org", port: 80, transport: "tcp" }); - * ``` - * - * Requires `allow-net` permission. - * - * @tags allow-net - * @category Network - */ - export function listen( - options: TcpListenOptions & { transport?: "tcp" }, - ): TcpListener; - - /** Options which can be set when opening a Unix listener via - * {@linkcode Deno.listen} or {@linkcode Deno.listenDatagram}. - * - * @category Network - */ - export interface UnixListenOptions { - /** A path to the Unix Socket. */ - path: string; - } - - /** Listen announces on the local transport address. - * - * ```ts - * const listener = Deno.listen({ path: "/foo/bar.sock", transport: "unix" }) - * ``` - * - * Requires `allow-read` and `allow-write` permission. - * - * @tags allow-read, allow-write - * @category Network - */ - // deno-lint-ignore adjacent-overload-signatures - export function listen( - options: UnixListenOptions & { transport: "unix" }, - ): UnixListener; - - /** Provides TLS certified keys, ie: a key that has been certified by a trusted certificate authority. - * A certified key generally consists of a private key and certificate part. - * - * @category Network - */ - export type TlsCertifiedKeyOptions = - | TlsCertifiedKeyPem - | TlsCertifiedKeyFromFile - | TlsCertifiedKeyConnectTls; - - /** - * Provides certified key material from strings. The key material is provided in - * `PEM`-format (Privacy Enhanced Mail, https://www.rfc-editor.org/rfc/rfc1422) which can be identified by having - * `-----BEGIN-----` and `-----END-----` markers at the beginning and end of the strings. This type of key is not compatible - * with `DER`-format keys which are binary. - * - * Deno supports RSA, EC, and PKCS8-format keys. - * - * ```ts - * const key = { - * key: "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n", - * cert: "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n" } - * }; - * ``` - * - * @category Network - */ - export interface TlsCertifiedKeyPem { - /** The format of this key material, which must be PEM. */ - keyFormat?: "pem"; - /** Private key in `PEM` format. RSA, EC, and PKCS8-format keys are supported. */ - key: string; - /** Certificate chain in `PEM` format. */ - cert: string; - } - - /** - * @deprecated This will be removed in Deno 2.0. See the - * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide} - * for migration instructions. - * - * @category Network - */ - export interface TlsCertifiedKeyFromFile { - /** Path to a file containing a PEM formatted CA certificate. Requires - * `--allow-read`. - * - * @tags allow-read - * @deprecated This will be removed in Deno 2.0. See the - * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide} - * for migration instructions. - */ - certFile: string; - /** Path to a file containing a private key file. Requires `--allow-read`. - * - * @tags allow-read - * @deprecated This will be removed in Deno 2.0. See the - * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide} - * for migration instructions. - */ - keyFile: string; - } - - /** - * @deprecated This will be removed in Deno 2.0. See the - * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide} - * for migration instructions. - * - * @category Network - */ - export interface TlsCertifiedKeyConnectTls { - /** - * Certificate chain in `PEM` format. - * - * @deprecated This will be removed in Deno 2.0. See the - * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide} - * for migration instructions. - */ - certChain: string; - /** - * Private key in `PEM` format. RSA, EC, and PKCS8-format keys are supported. - * - * @deprecated This will be removed in Deno 2.0. See the - * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide} - * for migration instructions. - */ - privateKey: string; - } - - /** @category Network */ - export interface ListenTlsOptions extends TcpListenOptions { - transport?: "tcp"; - - /** Application-Layer Protocol Negotiation (ALPN) protocols to announce to - * the client. If not specified, no ALPN extension will be included in the - * TLS handshake. - */ - alpnProtocols?: string[]; - } - - /** Listen announces on the local transport address over TLS (transport layer - * security). - * - * ```ts - * using listener = Deno.listenTls({ - * port: 443, - * cert: Deno.readTextFileSync("./server.crt"), - * key: Deno.readTextFileSync("./server.key"), - * }); - * ``` - * - * Requires `allow-net` permission. - * - * @tags allow-net - * @category Network - */ - export function listenTls( - options: ListenTlsOptions & TlsCertifiedKeyOptions, - ): TlsListener; - - /** @category Network */ - export interface ConnectOptions { - /** The port to connect to. */ - port: number; - /** A literal IP address or host name that can be resolved to an IP address. - * If not specified, - * - * @default {"127.0.0.1"} */ - hostname?: string; - transport?: "tcp"; - } - - /** - * Connects to the hostname (default is "127.0.0.1") and port on the named - * transport (default is "tcp"), and resolves to the connection (`Conn`). - * - * ```ts - * const conn1 = await Deno.connect({ port: 80 }); - * const conn2 = await Deno.connect({ hostname: "192.0.2.1", port: 80 }); - * const conn3 = await Deno.connect({ hostname: "[2001:db8::1]", port: 80 }); - * const conn4 = await Deno.connect({ hostname: "golang.org", port: 80, transport: "tcp" }); - * ``` - * - * Requires `allow-net` permission for "tcp". - * - * @tags allow-net - * @category Network - */ - export function connect(options: ConnectOptions): Promise; - - /** @category Network */ - export interface TcpConn extends Conn { - /** - * Enable/disable the use of Nagle's algorithm. - * - * @param [noDelay=true] - */ - setNoDelay(noDelay?: boolean): void; - /** Enable/disable keep-alive functionality. */ - setKeepAlive(keepAlive?: boolean): void; - /** - * The resource ID of the connection. - * - * @deprecated This will be removed in Deno 2.0. See the - * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide} - * for migration instructions. - */ - readonly rid: number; - } - - /** @category Network */ - export interface UnixConnectOptions { - transport: "unix"; - path: string; - } - - /** @category Network */ - export interface UnixConn extends Conn { - /** - * The resource ID of the connection. - * - * @deprecated This will be removed in Deno 2.0. See the - * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide} - * for migration instructions. - */ - readonly rid: number; - } - - /** Connects to the hostname (default is "127.0.0.1") and port on the named - * transport (default is "tcp"), and resolves to the connection (`Conn`). - * - * ```ts - * const conn1 = await Deno.connect({ port: 80 }); - * const conn2 = await Deno.connect({ hostname: "192.0.2.1", port: 80 }); - * const conn3 = await Deno.connect({ hostname: "[2001:db8::1]", port: 80 }); - * const conn4 = await Deno.connect({ hostname: "golang.org", port: 80, transport: "tcp" }); - * const conn5 = await Deno.connect({ path: "/foo/bar.sock", transport: "unix" }); - * ``` - * - * Requires `allow-net` permission for "tcp" and `allow-read` for "unix". - * - * @tags allow-net, allow-read - * @category Network - */ - // deno-lint-ignore adjacent-overload-signatures - export function connect(options: UnixConnectOptions): Promise; - - /** @category Network */ - export interface ConnectTlsOptions { - /** The port to connect to. */ - port: number; - /** A literal IP address or host name that can be resolved to an IP address. - * - * @default {"127.0.0.1"} */ - hostname?: string; - /** Path to a file containing a PEM formatted list of root certificates that will - * be used in addition to the default root certificates to verify the peer's certificate. Requires - * `--allow-read`. - * - * @tags allow-read - * @deprecated This will be removed in Deno 2.0. See the - * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide} - * for migration instructions. - */ - certFile?: string; - /** A list of root certificates that will be used in addition to the - * default root certificates to verify the peer's certificate. - * - * Must be in PEM format. */ - caCerts?: string[]; - /** Application-Layer Protocol Negotiation (ALPN) protocols supported by - * the client. If not specified, no ALPN extension will be included in the - * TLS handshake. - */ - alpnProtocols?: string[]; - } - - /** Establishes a secure connection over TLS (transport layer security) using - * an optional cert file, hostname (default is "127.0.0.1") and port. The - * cert file is optional and if not included Mozilla's root certificates will - * be used (see also https://github.com/ctz/webpki-roots for specifics) - * - * ```ts - * const caCert = await Deno.readTextFile("./certs/my_custom_root_CA.pem"); - * const conn1 = await Deno.connectTls({ port: 80 }); - * const conn2 = await Deno.connectTls({ caCerts: [caCert], hostname: "192.0.2.1", port: 80 }); - * const conn3 = await Deno.connectTls({ hostname: "[2001:db8::1]", port: 80 }); - * const conn4 = await Deno.connectTls({ caCerts: [caCert], hostname: "golang.org", port: 80}); - * ``` - * - * Requires `allow-net` permission. - * - * @tags allow-net - * @category Network - */ - export function connectTls(options: ConnectTlsOptions): Promise; - - /** Establishes a secure connection over TLS (transport layer security) using - * an optional cert file, client certificate, hostname (default is "127.0.0.1") and - * port. The cert file is optional and if not included Mozilla's root certificates will - * be used (see also https://github.com/ctz/webpki-roots for specifics) - * - * ```ts - * const caCert = await Deno.readTextFile("./certs/my_custom_root_CA.pem"); - * const key = "----BEGIN PRIVATE KEY----..."; - * const cert = "----BEGIN CERTIFICATE----..."; - * const conn1 = await Deno.connectTls({ port: 80, key, cert }); - * const conn2 = await Deno.connectTls({ caCerts: [caCert], hostname: "192.0.2.1", port: 80, key, cert }); - * const conn3 = await Deno.connectTls({ hostname: "[2001:db8::1]", port: 80, key, cert }); - * const conn4 = await Deno.connectTls({ caCerts: [caCert], hostname: "golang.org", port: 80, key, cert }); - * ``` - * - * Requires `allow-net` permission. - * - * @tags allow-net - * @category Network - */ - export function connectTls( - options: ConnectTlsOptions & TlsCertifiedKeyOptions, - ): Promise; - - /** @category Network */ - export interface StartTlsOptions { - /** A literal IP address or host name that can be resolved to an IP address. - * - * @default {"127.0.0.1"} */ - hostname?: string; - /** A list of root certificates that will be used in addition to the - * default root certificates to verify the peer's certificate. - * - * Must be in PEM format. */ - caCerts?: string[]; - /** Application-Layer Protocol Negotiation (ALPN) protocols to announce to - * the client. If not specified, no ALPN extension will be included in the - * TLS handshake. - */ - alpnProtocols?: string[]; - } - - /** Start TLS handshake from an existing connection using an optional list of - * CA certificates, and hostname (default is "127.0.0.1"). Specifying CA certs - * is optional. By default the configured root certificates are used. Using - * this function requires that the other end of the connection is prepared for - * a TLS handshake. - * - * Note that this function *consumes* the TCP connection passed to it, thus the - * original TCP connection will be unusable after calling this. Additionally, - * you need to ensure that the TCP connection is not being used elsewhere when - * calling this function in order for the TCP connection to be consumed properly. - * For instance, if there is a `Promise` that is waiting for read operation on - * the TCP connection to complete, it is considered that the TCP connection is - * being used elsewhere. In such a case, this function will fail. - * - * ```ts - * const conn = await Deno.connect({ port: 80, hostname: "127.0.0.1" }); - * const caCert = await Deno.readTextFile("./certs/my_custom_root_CA.pem"); - * // `conn` becomes unusable after calling `Deno.startTls` - * const tlsConn = await Deno.startTls(conn, { caCerts: [caCert], hostname: "localhost" }); - * ``` - * - * Requires `allow-net` permission. - * - * @tags allow-net - * @category Network - */ - export function startTls( - conn: TcpConn, - options?: StartTlsOptions, - ): Promise; - - /** Shutdown socket send operations. - * - * Matches behavior of POSIX shutdown(3). - * - * ```ts - * const listener = Deno.listen({ port: 80 }); - * const conn = await listener.accept(); - * Deno.shutdown(conn.rid); - * ``` - * - * @deprecated This will be removed in Deno 2.0. See the - * {@link https://docs.deno.com/runtime/manual/advanced/migrate_deprecations | Deno 1.x to 2.x Migration Guide} - * for migration instructions. - * - * @category Network - */ - export function shutdown(rid: number): Promise; -} diff --git a/tsconfig.json b/tsconfig.json index 326dd224..fac8a718 100644 --- a/tsconfig.json +++ b/tsconfig.json @@ -19,7 +19,7 @@ "composite": true, "types": [ "node", - "deno", + "deno/ns", "vite/client" ], "lib": [ From ad9ad041abba5efd2f294043f3ef7c051b7ec459 Mon Sep 17 00:00:00 2001 From: alina sireneva Date: Tue, 30 Apr 2024 05:34:43 +0300 Subject: [PATCH 09/10] test(e2e-deno): ported tests from e2e-node --- e2e/deno/.gitignore | 3 +- e2e/deno/tests/01.auth.ts | 83 +++++++++++++ e2e/deno/tests/02.methods.ts | 47 ++++++++ e2e/deno/tests/03.files.ts | 170 +++++++++++++++++++++++++++ e2e/deno/tests/04.updates.ts | 47 ++++++++ e2e/deno/tests/05.worker.ts | 79 +++++++++++++ e2e/deno/tests/_worker.ts | 18 +++ e2e/deno/utils.ts | 8 +- packages/deno/src/utils/exit-hook.ts | 2 +- 9 files changed, 451 insertions(+), 6 deletions(-) create mode 100644 e2e/deno/tests/01.auth.ts create mode 100644 e2e/deno/tests/02.methods.ts create mode 100644 e2e/deno/tests/03.files.ts create mode 100644 e2e/deno/tests/04.updates.ts create mode 100644 e2e/deno/tests/05.worker.ts create mode 100644 e2e/deno/tests/_worker.ts diff --git a/e2e/deno/.gitignore b/e2e/deno/.gitignore index 75a15d22..6771fc36 100644 --- a/e2e/deno/.gitignore +++ b/e2e/deno/.gitignore @@ -1,3 +1,4 @@ /.jsr-data .env -/deno.lock \ No newline at end of file +/deno.lock +/.sessions \ No newline at end of file diff --git a/e2e/deno/tests/01.auth.ts b/e2e/deno/tests/01.auth.ts new file mode 100644 index 00000000..1b739983 --- /dev/null +++ b/e2e/deno/tests/01.auth.ts @@ -0,0 +1,83 @@ +import { assertEquals } from 'https://deno.land/std@0.223.0/assert/mod.ts' + +import { MtcuteError } from '@mtcute/core' +import { BaseTelegramClient, TelegramClient } from '@mtcute/core/client.js' + +import { getApiParams } from '../utils.ts' + +const getAccountId = () => + Math.floor(Math.random() * 10000) + .toString() + .padStart(4, '0') + +Deno.test('1. authorization', { sanitizeResources: false }, async (t) => { + await t.step('should authorize in default dc', async () => { + const base = new BaseTelegramClient(getApiParams('dc2.session')) + const tg = new TelegramClient({ client: base }) + + // reset storage just in case + await base.mt.storage.load() + await base.storage.clear(true) + + while (true) { + const phone = `999662${getAccountId()}` + let user + + try { + user = await tg.start({ + phone, + code: () => '22222', + }) + } catch (e) { + if (e instanceof MtcuteError && e.message.match(/Signup is no longer supported|2FA is enabled/)) { + // retry with another number + continue + } else { + await tg.close() + throw e + } + } + + await tg.close() + + assertEquals(user.isSelf, true) + assertEquals(user.phoneNumber, phone) + break + } + }) + + await t.step('should authorize in dc 1', async () => { + const base = new BaseTelegramClient(getApiParams('dc1.session')) + const tg = new TelegramClient({ client: base }) + + // reset storage just in case + await base.mt.storage.load() + await base.mt.storage.clear(true) + + while (true) { + const phone = `999661${getAccountId()}` + let user + + try { + user = await tg.start({ + phone, + code: () => '11111', + }) + } catch (e) { + if (e instanceof MtcuteError && e.message.match(/Signup is no longer supported|2FA is enabled/)) { + // retry with another number + continue + } else { + await tg.close() + throw e + } + } + + await tg.close() + + assertEquals(user.isSelf, true) + assertEquals(user.phoneNumber, phone) + break + } + }) +}) diff --git a/e2e/deno/tests/02.methods.ts b/e2e/deno/tests/02.methods.ts new file mode 100644 index 00000000..e3e5a140 --- /dev/null +++ b/e2e/deno/tests/02.methods.ts @@ -0,0 +1,47 @@ +import { assertEquals, assertNotEquals } from 'https://deno.land/std@0.223.0/assert/mod.ts' + +import { TelegramClient } from '@mtcute/core/client.js' + +import { getApiParams } from '../utils.ts' + +Deno.test('2. calling methods', { sanitizeResources: false }, async (t) => { + const tg = new TelegramClient(getApiParams('dc2.session')) + + await tg.connect() + + await t.step('getUsers(@BotFather)', async () => { + const [user] = await tg.getUsers('botfather') + + assertEquals(user?.isBot, true) + assertEquals(user?.displayName, 'BotFather') + }) + + await t.step('getUsers(@BotFather) - cached', async () => { + const [user] = await tg.getUsers('botfather') + + assertEquals(user?.isBot, true) + assertEquals(user?.displayName, 'BotFather') + }) + + await t.step('getHistory(777000)', async () => { + const history = await tg.getHistory(777000, { limit: 5 }) + + assertEquals(history[0].chat.chatType, 'private') + assertEquals(history[0].chat.id, 777000) + assertEquals(history[0].chat.firstName, 'Telegram') + }) + + await t.step('updateProfile', async () => { + const bio = `mtcute e2e ${new Date().toISOString()}` + + const oldSelf = await tg.getFullChat('self') + const res = await tg.updateProfile({ bio }) + const newSelf = await tg.getFullChat('self') + + assertEquals(res.isSelf, true) + assertNotEquals(oldSelf.bio, newSelf.bio) + assertEquals(newSelf.bio, bio) + }) + + await tg.close() +}) diff --git a/e2e/deno/tests/03.files.ts b/e2e/deno/tests/03.files.ts new file mode 100644 index 00000000..3cbbbf5a --- /dev/null +++ b/e2e/deno/tests/03.files.ts @@ -0,0 +1,170 @@ +import { assertEquals } from 'https://deno.land/std@0.223.0/assert/mod.ts' +import { createHash } from 'node:crypto' + +import { FileDownloadLocation, Thumbnail } from '@mtcute/core' +import { TelegramClient } from '@mtcute/core/client.js' +import { sleep } from '@mtcute/core/utils.js' + +import { getApiParams } from '../utils.ts' + +const CINNAMOROLL_PFP_CHAT = 'test_file_dc2' +const CINNAMOROLL_PFP_THUMB_SHA256 = '3e6f220235a12547c16129f50c19ed3224d39b827414d1d500f79569a3431eae' +const CINNAMOROLL_PFP_SHA256 = '4d9836a71ac039f5656cde55b83525871549bfbff9cfb658c3f8381c5ba89ce8' + +const UWU_MSG = 'https://t.me/test_file_dc2/8' +const UWU_SHA256 = '357b78c9f9d20e813f729a19dd90c6727f30ebd4c8c83557022285f283a705b9' + +const SHREK_MSG = 'https://t.me/test_file_dc2/11' +const SHREK_SHA256 = 'd3e6434e027f3d31dc3e05c6ea2eaf84fdd1fb00774a215f89d9ed8b56f86258' + +const LARGE_MSG = 'https://t.me/test_file_dc2/12' + +async function downloadAsSha256(client: TelegramClient, location: FileDownloadLocation): Promise { + const sha = createHash('sha256') + + for await (const chunk of client.downloadAsIterable(location)) { + sha.update(chunk) + } + + return sha.digest('hex') +} + +Deno.test('3. working with files', { sanitizeResources: false }, async (t) => { + // sometimes test dcs are overloaded and we get FILE_REFERENCE_EXPIRED + // because we got multiple -500:No workers running errors in a row + // we currently don't have file references database, so we can just retry the test for now + // + // ...except we can't under deno because it's not implemented + // https://github.com/denoland/deno/issues/19882 + // this.retries(2) + + await t.step('same-dc', async (t) => { + const tg = new TelegramClient(getApiParams('dc2.session')) + + await tg.connect() + + await t.step('should download pfp thumbs', async () => { + const chat = await tg.getChat(CINNAMOROLL_PFP_CHAT) + if (!chat.photo) throw new Error('Chat has no photo') + + assertEquals(await downloadAsSha256(tg, chat.photo.big), CINNAMOROLL_PFP_THUMB_SHA256) + }) + + await t.step('should download animated pfps', async () => { + const chat = await tg.getFullChat(CINNAMOROLL_PFP_CHAT) + const thumb = chat.fullPhoto?.getThumbnail(Thumbnail.THUMB_VIDEO_PROFILE) + if (!thumb) throw new Error('Chat has no animated pfp') + + assertEquals(await downloadAsSha256(tg, thumb), CINNAMOROLL_PFP_SHA256) + }) + + await t.step('should download photos', async () => { + const msg = await tg.getMessageByLink(UWU_MSG) + + if (msg?.media?.type !== 'photo') { + throw new Error('Message not found or not a photo') + } + + assertEquals(await downloadAsSha256(tg, msg.media), UWU_SHA256) + }) + + await t.step('should download documents', async () => { + const msg = await tg.getMessageByLink(SHREK_MSG) + + if (msg?.media?.type !== 'document') { + throw new Error('Message not found or not a document') + } + + assertEquals(await downloadAsSha256(tg, msg.media), SHREK_SHA256) + }) + + await t.step('should cancel downloads', async () => { + const msg = await tg.getMessageByLink(LARGE_MSG) + + if (msg?.media?.type !== 'document') { + throw new Error('Message not found or not a document') + } + + const media = msg.media + + const abort = new AbortController() + + let downloaded = 0 + + async function download() { + const dl = tg.downloadAsIterable(media, { abortSignal: abort.signal }) + + try { + for await (const chunk of dl) { + downloaded += chunk.length + } + } catch (e) { + if (!(e instanceof DOMException && e.name === 'AbortError')) throw e + } + } + + const promise = download() + + // let it download for 10 seconds + await sleep(10000) + abort.abort() + // abort and snap the downloaded amount + const downloadedBefore = downloaded + + const avgSpeed = downloaded / 10 + // eslint-disable-next-line no-console + console.log('Average speed: %d KiB/s', avgSpeed / 1024) + + // wait a bit more to make sure it's aborted + await sleep(2000) + await promise + + assertEquals(downloaded, downloadedBefore, 'nothing should be downloaded after abort') + }) + + await tg.close() + }) + + await t.step('cross-dc', async (t) => { + const tg = new TelegramClient(getApiParams('dc1.session')) + + await tg.connect() + + await t.step('should download pfp thumbs', async () => { + const chat = await tg.getChat(CINNAMOROLL_PFP_CHAT) + if (!chat.photo) throw new Error('Chat has no photo') + + assertEquals(await downloadAsSha256(tg, chat.photo.big), CINNAMOROLL_PFP_THUMB_SHA256) + }) + + await t.step('should download animated pfps', async () => { + const chat = await tg.getFullChat(CINNAMOROLL_PFP_CHAT) + const thumb = chat.fullPhoto?.getThumbnail(Thumbnail.THUMB_VIDEO_PROFILE) + if (!thumb) throw new Error('Chat has no animated pfp') + + assertEquals(await downloadAsSha256(tg, thumb), CINNAMOROLL_PFP_SHA256) + }) + + await t.step('should download photos', async () => { + const msg = await tg.getMessageByLink(UWU_MSG) + + if (msg?.media?.type !== 'photo') { + throw new Error('Message not found or not a photo') + } + + assertEquals(await downloadAsSha256(tg, msg.media), UWU_SHA256) + }) + + await t.step('should download documents', async () => { + const msg = await tg.getMessageByLink(SHREK_MSG) + + if (msg?.media?.type !== 'document') { + throw new Error('Message not found or not a document') + } + + assertEquals(await downloadAsSha256(tg, msg.media), SHREK_SHA256) + }) + + await tg.close() + }) +}) diff --git a/e2e/deno/tests/04.updates.ts b/e2e/deno/tests/04.updates.ts new file mode 100644 index 00000000..37bc49e1 --- /dev/null +++ b/e2e/deno/tests/04.updates.ts @@ -0,0 +1,47 @@ +import { assertEquals, assertNotEquals } from 'https://deno.land/std@0.223.0/assert/mod.ts' + +import { Message } from '@mtcute/core' +import { TelegramClient } from '@mtcute/core/client.js' + +import { getApiParams, waitFor } from '../utils.ts' + +Deno.test('4. handling updates', { sanitizeResources: false }, async (t) => { + const tg1 = new TelegramClient(getApiParams('dc1.session')) + tg1.log.prefix = '[tg1] ' + const tg2 = new TelegramClient(getApiParams('dc2.session')) + tg2.log.prefix = '[tg2] ' + + await tg1.connect() + await tg1.startUpdatesLoop() + await tg2.connect() + + await t.step('should send and receive messages', async () => { + const tg1Messages: Message[] = [] + + tg1.on('new_message', (msg) => tg1Messages.push(msg)) + + const [tg1User] = await tg1.getUsers('self') + let username = tg1User!.username + + if (!username) { + username = `mtcute_e2e_${Math.random().toString(36).slice(2)}` + await tg1.setMyUsername(username) + } + + const messageText = `mtcute test message ${Math.random().toString(36).slice(2)}` + const sentMsg = await tg2.sendText(username, messageText) + + assertEquals(sentMsg.text, messageText) + assertEquals(sentMsg.chat.id, tg1User!.id) + + await waitFor(() => { + assertNotEquals( + tg1Messages.find((msg) => msg.text === messageText), + undefined, + ) + }) + }) + + await tg1.close() + await tg2.close() +}) diff --git a/e2e/deno/tests/05.worker.ts b/e2e/deno/tests/05.worker.ts new file mode 100644 index 00000000..fe8ea4ce --- /dev/null +++ b/e2e/deno/tests/05.worker.ts @@ -0,0 +1,79 @@ +import { assertEquals, assertGreater, assertInstanceOf } from 'https://deno.land/std@0.223.0/assert/mod.ts' + +import { TelegramClient } from '@mtcute/core/client.js' +import { Message, TelegramWorkerPort, tl } from '@mtcute/deno' + +import { getApiParams, waitFor } from '../utils.ts' +import type { CustomMethods } from './_worker.ts' + +Deno.test('5. worker', { sanitizeResources: false }, async (t) => { + const worker = new Worker(new URL('_worker.ts', import.meta.url), { + type: 'module', + }) + + const port = new TelegramWorkerPort({ + worker, + }) + const portClient = new TelegramClient({ client: port }) + + await t.step('should make api calls', async function () { + const res = await port.call({ _: 'help.getConfig' }) + + assertEquals(res._, 'config') + }) + + await t.step('should call custom methods', async function () { + const hello = await port.invokeCustom('hello') + assertEquals(hello, 'world') + + const sum = await port.invokeCustom('sum', 2, 3) + assertEquals(sum, 5) + }) + + await t.step('should throw errors', async function () { + try { + await port.call({ _: 'test.useConfigSimple' }) + throw new Error('should have thrown') + } catch (e) { + assertInstanceOf(e, tl.RpcError) + } + }) + + await t.step('should receive updates', async function () { + const client2 = new TelegramClient(getApiParams('dc2.session')) + + try { + await client2.connect() + await port.startUpdatesLoop() + + const me = await portClient.getMe() + let username = me.username + + if (!username) { + username = `mtcute_e2e_${Math.random().toString(36).slice(2, 8)}` + await portClient.setMyUsername(username) + } + + const msgs: Message[] = [] + portClient.on('new_message', (msg) => { + msgs.push(msg) + }) + + const testText = `test ${Math.random()}` + await client2.sendText(username, testText) + + await waitFor(() => { + assertGreater(msgs.length, 0) + assertEquals(msgs[0].text, testText) + }) + } catch (e) { + await client2.close() + throw e + } + + await client2.close() + }) + + await port.close() + worker.terminate() +}) diff --git a/e2e/deno/tests/_worker.ts b/e2e/deno/tests/_worker.ts new file mode 100644 index 00000000..1b5e3938 --- /dev/null +++ b/e2e/deno/tests/_worker.ts @@ -0,0 +1,18 @@ +import { WorkerCustomMethods } from '@mtcute/core/worker.js' +import { BaseTelegramClient, TelegramWorker } from '@mtcute/deno' + +import { getApiParams } from '../utils.ts' + +const customMethods = { + hello: async () => 'world', + sum: async (a: number, b: number) => a + b, +} as const satisfies WorkerCustomMethods +export type CustomMethods = typeof customMethods + +const client = new BaseTelegramClient(getApiParams('dc1.session')) + +// eslint-disable-next-line no-new +new TelegramWorker({ + client, + customMethods, +}) diff --git a/e2e/deno/utils.ts b/e2e/deno/utils.ts index 8714b990..dfba3630 100644 --- a/e2e/deno/utils.ts +++ b/e2e/deno/utils.ts @@ -1,22 +1,22 @@ import { MaybePromise, MemoryStorage } from '@mtcute/core' import { setPlatform } from '@mtcute/core/platform.js' import { LogManager, sleep } from '@mtcute/core/utils.js' -import { DenoCryptoProvider, DenoPlatform, TcpTransport } from '@mtcute/deno' +import { DenoCryptoProvider, DenoPlatform, SqliteStorage, TcpTransport } from '@mtcute/deno' export const getApiParams = (storage?: string) => { - if (storage) throw new Error('unsupported yet') - if (!Deno.env.has('API_ID') || !Deno.env.has('API_HASH')) { throw new Error('API_ID and API_HASH env variables must be set') } + Deno.mkdirSync('.sessions', { recursive: true }) + setPlatform(new DenoPlatform()) return { apiId: parseInt(Deno.env.get('API_ID')!), apiHash: Deno.env.get('API_HASH')!, testMode: true, - storage: new MemoryStorage(), + storage: storage ? new SqliteStorage(`.sessions/${storage}`) : new MemoryStorage(), logLevel: LogManager.VERBOSE, transport: () => new TcpTransport(), crypto: new DenoCryptoProvider(), diff --git a/packages/deno/src/utils/exit-hook.ts b/packages/deno/src/utils/exit-hook.ts index aa43b595..ecaa0e40 100644 --- a/packages/deno/src/utils/exit-hook.ts +++ b/packages/deno/src/utils/exit-hook.ts @@ -6,7 +6,7 @@ export function beforeExit(fn: () => void): () => void { if (!registered) { registered = true - window.addEventListener('unload', () => { + globalThis.addEventListener('unload', () => { for (const callback of callbacks) { callback() } From ba0fec6340805da11106d28baeb23c84bb3a2d20 Mon Sep 17 00:00:00 2001 From: alina sireneva Date: Tue, 30 Apr 2024 05:38:11 +0300 Subject: [PATCH 10/10] ci(e2e-deno): hopefully made it a bit less flaky --- e2e/deno/cli.sh | 14 +++++++++++--- 1 file changed, 11 insertions(+), 3 deletions(-) diff --git a/e2e/deno/cli.sh b/e2e/deno/cli.sh index 07c64d6a..79c7c8ff 100755 --- a/e2e/deno/cli.sh +++ b/e2e/deno/cli.sh @@ -45,19 +45,27 @@ case "$method" in source .env fi + export JSR_URL=http://localhost:4873 + if [ ! -z ${DOCKER+x} ]; then # running behind a socat proxy seems to fix some of the docker networking issues (thx kamillaova) socat TCP-LISTEN:4873,fork,reuseaddr TCP4:jsr:80 & socat_pid=$! + # run `deno cache` with a few retries to make sure everything is cached + for i in {1..5}; do + if deno cache tests/*.ts; then + break + fi + done + trap "kill $socat_pid" EXIT fi - export JSR_URL=http://localhost:4873 if [ $# -eq 0 ]; then - deno test -A tests/**/*.ts + deno test -A --unstable-ffi tests/**/*.ts else - deno test -A $@ + deno test -A --unstable-ffi $@ fi ;; "run-docker")