From e435c2be158ce8657dbff0664b6db222fe4e586c Mon Sep 17 00:00:00 2001 From: crowlKats Date: Fri, 13 Mar 2020 10:22:22 +0100 Subject: [PATCH] Remove doc strings from cli/js TS files (#4329) Co-authored-by: Ryan Dahl --- cli/js/buffer.ts | 63 ------ cli/js/build.ts | 3 - cli/js/compiler.ts | 12 - cli/js/compiler/api.ts | 205 ----------------- cli/js/compiler/bootstrap.ts | 12 - cli/js/compiler/bundler.ts | 5 - cli/js/compiler/host.ts | 22 -- cli/js/compiler/imports.ts | 19 -- cli/js/compiler/sourcefile.ts | 18 -- cli/js/compiler/type_directives.ts | 20 -- cli/js/compiler/util.ts | 22 -- cli/js/deno.ts | 3 - cli/js/diagnostics.ts | 15 -- cli/js/diagnostics_util.ts | 5 - cli/js/error_stack.ts | 24 -- cli/js/file_info.ts | 48 ---- cli/js/files.ts | 34 --- cli/js/io.ts | 79 ------- cli/js/net.ts | 62 ------ cli/js/ops/compiler.ts | 3 - cli/js/ops/errors.ts | 30 --- cli/js/ops/fs/chmod.ts | 12 - cli/js/ops/fs/chown.ts | 18 -- cli/js/ops/fs/copy_file.ts | 16 -- cli/js/ops/fs/dir.ts | 17 -- cli/js/ops/fs/link.ts | 10 - cli/js/ops/fs/make_temp.ts | 62 ------ cli/js/ops/fs/mkdir.ts | 20 -- cli/js/ops/fs/open.ts | 34 --- cli/js/ops/fs/read_dir.ts | 13 -- cli/js/ops/fs/read_link.ts | 10 - cli/js/ops/fs/realpath.ts | 8 - cli/js/ops/fs/remove.ts | 16 -- cli/js/ops/fs/rename.ts | 15 -- cli/js/ops/fs/seek.ts | 14 -- cli/js/ops/fs/stat.ts | 29 --- cli/js/ops/fs/symlink.ts | 18 -- cli/js/ops/fs/truncate.ts | 11 - cli/js/ops/fs/umask.ts | 6 - cli/js/ops/fs/utime.ts | 18 -- cli/js/ops/get_random_values.ts | 6 - cli/js/ops/io.ts | 36 --- cli/js/ops/net.ts | 8 - cli/js/ops/os.ts | 148 ------------- cli/js/ops/process.ts | 5 - cli/js/ops/resources.ts | 4 - cli/js/ops/runtime.ts | 19 -- cli/js/ops/tty.ts | 2 - cli/js/permissions.ts | 24 -- cli/js/process.ts | 32 --- cli/js/read_file.ts | 14 -- cli/js/repl.ts | 8 - cli/js/runtime.ts | 5 - cli/js/runtime_worker.ts | 6 - cli/js/signals.ts | 55 ----- cli/js/symbols.ts | 5 - cli/js/tls.ts | 16 -- cli/js/util.ts | 23 -- cli/js/version.ts | 4 - cli/js/web/blob.ts | 1 - cli/js/web/console.ts | 30 --- cli/js/web/custom_event.ts | 3 - cli/js/web/dom_iterable.ts | 4 - cli/js/web/dom_types.ts | 207 ------------------ cli/js/web/event.ts | 25 --- cli/js/web/event_target.ts | 3 - cli/js/web/fetch.ts | 1 - cli/js/web/form_data.ts | 31 --- cli/js/web/performance.ts | 7 - cli/js/web/request.ts | 16 -- cli/js/web/streams/mod.ts | 7 - cli/js/web/streams/queue-mixin.ts | 7 - cli/js/web/streams/queue.ts | 7 - .../readable-byte-stream-controller.ts | 7 - cli/js/web/streams/readable-internals.ts | 7 - .../streams/readable-stream-byob-reader.ts | 7 - .../streams/readable-stream-byob-request.ts | 7 - .../readable-stream-default-controller.ts | 7 - .../streams/readable-stream-default-reader.ts | 7 - cli/js/web/streams/readable-stream.ts | 7 - cli/js/web/streams/shared-internals.ts | 13 -- cli/js/web/streams/strategies.ts | 7 - cli/js/web/text_encoding.ts | 8 - cli/js/web/timers.ts | 3 - cli/js/web/url_search_params.ts | 78 ------- cli/js/web/util.ts | 23 -- cli/js/write_file.ts | 24 -- 87 files changed, 2025 deletions(-) diff --git a/cli/js/buffer.ts b/cli/js/buffer.ts index f0893a5339..91c06a202c 100644 --- a/cli/js/buffer.ts +++ b/cli/js/buffer.ts @@ -27,9 +27,6 @@ function copyBytes(dst: Uint8Array, src: Uint8Array, off = 0): number { return src.byteLength; } -/** A Buffer is a variable-sized buffer of bytes with read() and write() - * methods. Based on https://golang.org/pkg/bytes/#Buffer - */ export class Buffer implements Reader, SyncReader, Writer, SyncWriter { private buf: Uint8Array; // contents are the bytes buf[off : len(buf)] private off = 0; // read at buf[off], write at buf[buf.byteLength] @@ -43,50 +40,27 @@ export class Buffer implements Reader, SyncReader, Writer, SyncWriter { this.buf = new Uint8Array(ab); } - /** bytes() 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()). 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. - */ bytes(): Uint8Array { return this.buf.subarray(this.off); } - /** toString() returns the contents of the unread portion of the buffer - * as a string. Warning - if multibyte characters are present when data is - * flowing through the buffer, this method may result in incorrect strings - * due to a character being split. - */ toString(): string { const decoder = new TextDecoder(); return decoder.decode(this.buf.subarray(this.off)); } - /** empty() returns whether the unread portion of the buffer is empty. */ empty(): boolean { return this.buf.byteLength <= this.off; } - /** length is a getter that returns the number of bytes of the unread - * portion of the buffer - */ get length(): number { return this.buf.byteLength - this.off; } - /** Returns the capacity of the buffer's underlying byte slice, that is, - * the total space allocated for the buffer's data. - */ get capacity(): number { return this.buf.buffer.byteLength; } - /** truncate() 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 { if (n === 0) { this.reset(); @@ -98,19 +72,11 @@ export class Buffer implements Reader, SyncReader, Writer, SyncWriter { this._reslice(this.off + n); } - /** reset() 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 { this._reslice(0); this.off = 0; } - /** _tryGrowByReslice() is a version of grow for the fast-case - * where the internal buffer only needs to be resliced. It returns the index - * where bytes should be written and whether it succeeded. - * It returns -1 if a reslice was not needed. - */ private _tryGrowByReslice(n: number): number { const l = this.buf.byteLength; if (n <= this.capacity - l) { @@ -125,10 +91,6 @@ export class Buffer implements Reader, SyncReader, Writer, SyncWriter { this.buf = new Uint8Array(this.buf.buffer, 0, len); } - /** readSync() reads the next len(p) bytes from the buffer or until the buffer - * is drained. The return value n is the number of bytes read. If the - * buffer has no data to return, eof in the response will be true. - */ readSync(p: Uint8Array): number | EOF { if (this.empty()) { // Buffer is empty, reset to recover space. @@ -159,10 +121,6 @@ export class Buffer implements Reader, SyncReader, Writer, SyncWriter { return Promise.resolve(n); } - /** _grow() grows the buffer to guarantee space for n more bytes. - * It returns the index where bytes should be written. - * If the buffer can't grow it will throw with Error. - */ private _grow(n: number): number { const m = this.length; // If buffer is empty, reset to recover space. @@ -195,12 +153,6 @@ export class Buffer implements Reader, SyncReader, Writer, SyncWriter { return m; } - /** grow() 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 panic. If - * the buffer can't grow it will throw Error. - * Based on https://golang.org/pkg/bytes/#Buffer.Grow - */ grow(n: number): void { if (n < 0) { throw Error("Buffer.grow: negative count"); @@ -209,11 +161,6 @@ export class Buffer implements Reader, SyncReader, Writer, SyncWriter { this._reslice(m); } - /** readFrom() reads data from r until EOF and appends it to the buffer, - * growing the buffer as needed. It returns the number of bytes read. If the - * buffer becomes too large, readFrom will panic with Error. - * Based on https://golang.org/pkg/bytes/#Buffer.ReadFrom - */ async readFrom(r: Reader): Promise { let n = 0; while (true) { @@ -233,8 +180,6 @@ export class Buffer implements Reader, SyncReader, Writer, SyncWriter { } } - /** Sync version of `readFrom` - */ readFromSync(r: SyncReader): number { let n = 0; while (true) { @@ -255,24 +200,18 @@ export class Buffer implements Reader, SyncReader, Writer, SyncWriter { } } -/** Read `r` until EOF and return the content as `Uint8Array`. - */ export async function readAll(r: Reader): Promise { const buf = new Buffer(); await buf.readFrom(r); return buf.bytes(); } -/** Read synchronously `r` until EOF and return the content as `Uint8Array`. - */ export function readAllSync(r: SyncReader): Uint8Array { const buf = new Buffer(); buf.readFromSync(r); return buf.bytes(); } -/** Write all the content of `arr` to `w`. - */ export async function writeAll(w: Writer, arr: Uint8Array): Promise { let nwritten = 0; while (nwritten < arr.length) { @@ -280,8 +219,6 @@ export async function writeAll(w: Writer, arr: Uint8Array): Promise { } } -/** Write synchronously all the content of `arr` to `w`. - */ export function writeAllSync(w: SyncWriter, arr: Uint8Array): void { let nwritten = 0; while (nwritten < arr.length) { diff --git a/cli/js/build.ts b/cli/js/build.ts index 7e46ffe97a..c347061390 100644 --- a/cli/js/build.ts +++ b/cli/js/build.ts @@ -5,12 +5,9 @@ export type OperatingSystem = "mac" | "win" | "linux"; export type Arch = "x64" | "arm64"; // Do not add unsupported platforms. -/** Build related information */ export interface BuildInfo { - /** The CPU architecture. */ arch: Arch; - /** The operating system. */ os: OperatingSystem; } diff --git a/cli/js/compiler.ts b/cli/js/compiler.ts index ed156ef0ab..1dddd984cb 100644 --- a/cli/js/compiler.ts +++ b/cli/js/compiler.ts @@ -70,13 +70,11 @@ interface CompilerRequestRuntimeTranspile { options?: string; } -/** The format of the work message payload coming from the privileged side */ type CompilerRequest = | CompilerRequestCompile | CompilerRequestRuntimeCompile | CompilerRequestRuntimeTranspile; -/** The format of the result sent back when doing a compilation. */ interface CompileResult { emitSkipped: boolean; diagnostics?: Diagnostic; @@ -89,8 +87,6 @@ type RuntimeCompileResult = [ type RuntimeBundleResult = [undefined | DiagnosticItem[], string]; -/** `Compile` are requests from the internals of Deno; eg. used when - * the `run` or `bundle` subcommand is used. */ async function compile( request: CompilerRequestCompile ): Promise { @@ -186,14 +182,6 @@ async function compile( return result; } -/**`RuntimeCompile` are requests from a runtime user; it can be both - * "compile" and "bundle". - * - * The process is similar to a request from the privileged - * side, but unline `compile`, `runtimeCompile` allows to specify - * additional file mappings which can be used instead of relying - * on Deno defaults. - */ async function runtimeCompile( request: CompilerRequestRuntimeCompile ): Promise { diff --git a/cli/js/compiler/api.ts b/cli/js/compiler/api.ts index e6e1d5eeea..409ad94db2 100644 --- a/cli/js/compiler/api.ts +++ b/cli/js/compiler/api.ts @@ -7,115 +7,61 @@ import { DiagnosticItem } from "../diagnostics.ts"; import * as util from "../util.ts"; import * as runtimeCompilerOps from "../ops/runtime_compiler.ts"; -/** A specific subset TypeScript compiler options that can be supported by - * the Deno TypeScript compiler. */ export interface CompilerOptions { - /** Allow JavaScript files to be compiled. Defaults to `true`. */ allowJs?: boolean; - /** Allow default imports from modules with no default export. This does not - * affect code emit, just typechecking. Defaults to `false`. */ allowSyntheticDefaultImports?: boolean; - /** Allow accessing UMD globals from modules. Defaults to `false`. */ allowUmdGlobalAccess?: boolean; - /** Do not report errors on unreachable code. Defaults to `false`. */ allowUnreachableCode?: boolean; - /** Do not report errors on unused labels. Defaults to `false` */ allowUnusedLabels?: boolean; - /** Parse in strict mode and emit `"use strict"` for each source file. - * Defaults to `true`. */ alwaysStrict?: boolean; - /** Base directory to resolve non-relative module names. Defaults to - * `undefined`. */ baseUrl?: string; - /** Report errors in `.js` files. Use in conjunction with `allowJs`. Defaults - * to `false`. */ checkJs?: boolean; - /** Generates corresponding `.d.ts` file. Defaults to `false`. */ declaration?: boolean; - /** Output directory for generated declaration files. */ declarationDir?: string; - /** Generates a source map for each corresponding `.d.ts` file. Defaults to - * `false`. */ declarationMap?: boolean; - /** Provide full support for iterables in `for..of`, spread and - * destructuring when targeting ES5 or ES3. Defaults to `false`. */ downlevelIteration?: boolean; - /** Emit a UTF-8 Byte Order Mark (BOM) in the beginning of output files. - * Defaults to `false`. */ emitBOM?: boolean; - /** Only emit `.d.ts` declaration files. Defaults to `false`. */ emitDeclarationOnly?: boolean; - /** Emit design-type metadata for decorated declarations in source. See issue - * [microsoft/TypeScript#2577](https://github.com/Microsoft/TypeScript/issues/2577) - * for details. Defaults to `false`. */ emitDecoratorMetadata?: boolean; - /** Emit `__importStar` and `__importDefault` helpers for runtime babel - * ecosystem compatibility and enable `allowSyntheticDefaultImports` for type - * system compatibility. Defaults to `true`. */ esModuleInterop?: boolean; - /** Enables experimental support for ES decorators. Defaults to `false`. */ experimentalDecorators?: boolean; - /** Emit a single file with source maps instead of having a separate file. - * Defaults to `false`. */ inlineSourceMap?: boolean; - /** Emit the source alongside the source maps within a single file; requires - * `inlineSourceMap` or `sourceMap` to be set. Defaults to `false`. */ inlineSources?: boolean; - /** Perform additional checks to ensure that transpile only would be safe. - * Defaults to `false`. */ isolatedModules?: boolean; - /** Support JSX in `.tsx` files: `"react"`, `"preserve"`, `"react-native"`. - * Defaults to `"react"`. */ jsx?: "react" | "preserve" | "react-native"; - /** Specify the JSX factory function to use when targeting react JSX emit, - * e.g. `React.createElement` or `h`. Defaults to `React.createElement`. */ jsxFactory?: string; - /** Resolve keyof to string valued property names only (no numbers or - * symbols). Defaults to `false`. */ keyofStringsOnly?: string; - /** Emit class fields with ECMAScript-standard semantics. Defaults to `false`. - * Does not apply to `"esnext"` target. */ useDefineForClassFields?: boolean; - /** List of library files to be included in the compilation. If omitted, - * then the Deno main runtime libs are used. */ lib?: string[]; - /** The locale to use to show error messages. */ locale?: string; - /** Specifies the location where debugger should locate map files instead of - * generated locations. Use this flag if the `.map` files will be located at - * run-time in a different location than the `.js` files. The location - * specified will be embedded in the source map to direct the debugger where - * the map files will be located. Defaults to `undefined`. */ mapRoot?: string; - /** Specify the module format for the emitted code. Defaults to - * `"esnext"`. */ module?: | "none" | "commonjs" @@ -126,115 +72,58 @@ export interface CompilerOptions { | "es2015" | "esnext"; - /** Do not generate custom helper functions like `__extends` in compiled - * output. Defaults to `false`. */ noEmitHelpers?: boolean; - /** Report errors for fallthrough cases in switch statement. Defaults to - * `false`. */ noFallthroughCasesInSwitch?: boolean; - /** Raise error on expressions and declarations with an implied any type. - * Defaults to `true`. */ noImplicitAny?: boolean; - /** Report an error when not all code paths in function return a value. - * Defaults to `false`. */ noImplicitReturns?: boolean; - /** Raise error on `this` expressions with an implied `any` type. Defaults to - * `true`. */ noImplicitThis?: boolean; - /** Do not emit `"use strict"` directives in module output. Defaults to - * `false`. */ noImplicitUseStrict?: boolean; - /** Do not add triple-slash references or module import targets to the list of - * compiled files. Defaults to `false`. */ noResolve?: boolean; - /** Disable strict checking of generic signatures in function types. Defaults - * to `false`. */ noStrictGenericChecks?: boolean; - /** Report errors on unused locals. Defaults to `false`. */ noUnusedLocals?: boolean; - /** Report errors on unused parameters. Defaults to `false`. */ noUnusedParameters?: boolean; - /** Redirect output structure to the directory. This only impacts - * `Deno.compile` and only changes the emitted file names. Defaults to - * `undefined`. */ outDir?: string; - /** List of path mapping entries for module names to locations relative to the - * `baseUrl`. Defaults to `undefined`. */ paths?: Record; - /** Do not erase const enum declarations in generated code. Defaults to - * `false`. */ preserveConstEnums?: boolean; - /** Remove all comments except copy-right header comments beginning with - * `/*!`. Defaults to `true`. */ removeComments?: boolean; - /** Include modules imported with `.json` extension. Defaults to `true`. */ resolveJsonModule?: boolean; - /** Specifies the root directory of input files. Only use to control the - * output directory structure with `outDir`. Defaults to `undefined`. */ rootDir?: string; - /** List of _root_ folders whose combined content represent the structure of - * the project at runtime. Defaults to `undefined`. */ rootDirs?: string[]; - /** Generates corresponding `.map` file. Defaults to `false`. */ sourceMap?: boolean; - /** Specifies the location where debugger should locate TypeScript files - * instead of source locations. Use this flag if the sources will be located - * at run-time in a different location than that at design-time. The location - * specified will be embedded in the sourceMap to direct the debugger where - * the source files will be located. Defaults to `undefined`. */ sourceRoot?: string; - /** Enable all strict type checking options. Enabling `strict` enables - * `noImplicitAny`, `noImplicitThis`, `alwaysStrict`, `strictBindCallApply`, - * `strictNullChecks`, `strictFunctionTypes` and - * `strictPropertyInitialization`. Defaults to `true`. */ strict?: boolean; - /** Enable stricter checking of the `bind`, `call`, and `apply` methods on - * functions. Defaults to `true`. */ strictBindCallApply?: boolean; - /** Disable bivariant parameter checking for function types. Defaults to - * `true`. */ strictFunctionTypes?: boolean; - /** Ensure non-undefined class properties are initialized in the constructor. - * This option requires `strictNullChecks` be enabled in order to take effect. - * Defaults to `true`. */ strictPropertyInitialization?: boolean; - /** In strict null checking mode, the `null` and `undefined` values are not in - * the domain of every type and are only assignable to themselves and `any` - * (the one exception being that `undefined` is also assignable to `void`). */ strictNullChecks?: boolean; - /** Suppress excess property checks for object literals. Defaults to - * `false`. */ suppressExcessPropertyErrors?: boolean; - /** Suppress `noImplicitAny` errors for indexing objects lacking index - * signatures. */ suppressImplicitAnyIndexErrors?: boolean; - /** Specify ECMAScript target version. Defaults to `esnext`. */ target?: | "es3" | "es5" @@ -247,59 +136,20 @@ export interface CompilerOptions { | "es2020" | "esnext"; - /** List of names of type definitions to include. Defaults to `undefined`. - * - * The type definitions are resolved according to the normal Deno resolution - * irrespective of if sources are provided on the call. Like other Deno - * modules, there is no "magical" resolution. For example: - * - * Deno.compile( - * "./foo.js", - * undefined, - * { - * types: [ "./foo.d.ts", "https://deno.land/x/example/types.d.ts" ] - * } - * ); - * - */ types?: string[]; } -/** Internal function to just validate that the specifier looks relative, that - * it starts with `./`. */ function checkRelative(specifier: string): string { return specifier.match(/^([\.\/\\]|https?:\/{2}|file:\/{2})/) ? specifier : `./${specifier}`; } -/** The results of a transpile only command, where the `source` contains the - * emitted source, and `map` optionally contains the source map. - */ export interface TranspileOnlyResult { source: string; map?: string; } -/** Takes a set of TypeScript sources and resolves with a map where the key was - * the original file name provided in sources and the result contains the - * `source` and optionally the `map` from the transpile operation. This does no - * type checking and validation, it effectively "strips" the types from the - * file. - * - * const results = await Deno.transpileOnly({ - * "foo.ts": `const foo: string = "foo";` - * }); - * - * @param sources A map where the key is the filename and the value is the text - * to transpile. The filename is only used in the transpile and - * not resolved, for example to fill in the source name in the - * source map. - * @param options An option object of options to send to the compiler. This is - * a subset of ts.CompilerOptions which can be supported by Deno. - * Many of the options related to type checking and emitting - * type declaration files will have no impact on the output. - */ export async function transpileOnly( sources: Record, options: CompilerOptions = {} @@ -313,33 +163,6 @@ export async function transpileOnly( return JSON.parse(result); } -/** Takes a root module name, any optionally a record set of sources. Resolves - * with a compiled set of modules. If just a root name is provided, the modules - * will be resolved as if the root module had been passed on the command line. - * - * If sources are passed, all modules will be resolved out of this object, where - * the key is the module name and the value is the content. The extension of - * the module name will be used to determine the media type of the module. - * - * const [ maybeDiagnostics1, output1 ] = await Deno.compile("foo.ts"); - * - * const [ maybeDiagnostics2, output2 ] = await Deno.compile("/foo.ts", { - * "/foo.ts": `export * from "./bar.ts";`, - * "/bar.ts": `export const bar = "bar";` - * }); - * - * @param rootName The root name of the module which will be used as the - * "starting point". If no `sources` is specified, Deno will - * resolve the module externally as if the `rootName` had been - * specified on the command line. - * @param sources An optional key/value map of sources to be used when resolving - * modules, where the key is the module name, and the value is - * the source content. The extension of the key will determine - * the media type of the file when processing. If supplied, - * Deno will not attempt to resolve any modules externally. - * @param options An optional object of options to send to the compiler. This is - * a subset of ts.CompilerOptions which can be supported by Deno. - */ export async function compile( rootName: string, sources?: Record, @@ -360,34 +183,6 @@ export async function compile( return JSON.parse(result); } -/** Takes a root module name, and optionally a record set of sources. Resolves - * with a single JavaScript string that is like the output of a `deno bundle` - * command. If just a root name is provided, the modules will be resolved as if - * the root module had been passed on the command line. - * - * If sources are passed, all modules will be resolved out of this object, where - * the key is the module name and the value is the content. The extension of the - * module name will be used to determine the media type of the module. - * - * const [ maybeDiagnostics1, output1 ] = await Deno.bundle("foo.ts"); - * - * const [ maybeDiagnostics2, output2 ] = await Deno.bundle("/foo.ts", { - * "/foo.ts": `export * from "./bar.ts";`, - * "/bar.ts": `export const bar = "bar";` - * }); - * - * @param rootName The root name of the module which will be used as the - * "starting point". If no `sources` is specified, Deno will - * resolve the module externally as if the `rootName` had been - * specified on the command line. - * @param sources An optional key/value map of sources to be used when resolving - * modules, where the key is the module name, and the value is - * the source content. The extension of the key will determine - * the media type of the file when processing. If supplied, - * Deno will not attempt to resolve any modules externally. - * @param options An optional object of options to send to the compiler. This is - * a subset of ts.CompilerOptions which can be supported by Deno. - */ export async function bundle( rootName: string, sources?: Record, diff --git a/cli/js/compiler/bootstrap.ts b/cli/js/compiler/bootstrap.ts index d4642d041f..978ddbaf89 100644 --- a/cli/js/compiler/bootstrap.ts +++ b/cli/js/compiler/bootstrap.ts @@ -31,22 +31,10 @@ host.getSourceFile( ts.ScriptTarget.ESNext ); -/** - * This function spins up TS compiler and loads all available libraries - * into memory (including ones specified above). - * - * Used to generate the foundational AST for all other compilations, so it can - * be cached as part of the snapshot and available to speed up startup. - */ export const TS_SNAPSHOT_PROGRAM = ts.createProgram({ rootNames: [`${ASSETS}/bootstrap.ts`], options, host }); -/** A module loader which is concatenated into bundle files. - * - * We read all static assets during the snapshotting process, which is - * why this is located in compiler_bootstrap. - */ export const SYSTEM_LOADER = getAsset("system_loader.js"); diff --git a/cli/js/compiler/bundler.ts b/cli/js/compiler/bundler.ts index ab987a7fc2..8e35befc82 100644 --- a/cli/js/compiler/bundler.ts +++ b/cli/js/compiler/bundler.ts @@ -4,10 +4,8 @@ import { SYSTEM_LOADER } from "./bootstrap.ts"; import { commonPath, normalizeString, CHAR_FORWARD_SLASH } from "./util.ts"; import { assert } from "../util.ts"; -/** Local state of what the root exports are of a root module. */ let rootExports: string[] | undefined; -/** Take a URL and normalize it, resolving relative path parts. */ function normalizeUrl(rootName: string): string { const match = /^(\S+:\/{2,3})(.+)$/.exec(rootName); if (match) { @@ -23,8 +21,6 @@ function normalizeUrl(rootName: string): string { } } -/** Given a root name, contents, and source files, enrich the data of the - * bundle with a loader and re-export the exports of the root name. */ export function buildBundle( rootName: string, data: string, @@ -63,7 +59,6 @@ export function buildBundle( return `${SYSTEM_LOADER}\n${data}\n${instantiate}`; } -/** Set the rootExports which will by the `emitBundle()` */ export function setRootExports(program: ts.Program, rootModule: string): void { // get a reference to the type checker, this will let us find symbols from // the AST. diff --git a/cli/js/compiler/host.ts b/cli/js/compiler/host.ts index 8032d83b3c..627c529702 100644 --- a/cli/js/compiler/host.ts +++ b/cli/js/compiler/host.ts @@ -6,26 +6,17 @@ import { cwd } from "../ops/fs/dir.ts"; import { assert, notImplemented } from "../util.ts"; import * as util from "../util.ts"; -/** Specifies the target that the host should use to inform the TypeScript - * compiler of what types should be used to validate the program against. */ export enum CompilerHostTarget { - /** The main isolate library, where the main program runs. */ Main = "main", - /** The runtime API library. */ Runtime = "runtime", - /** The worker isolate library, where worker programs run. */ Worker = "worker" } export interface CompilerHostOptions { - /** Flag determines if the host should assume a single bundle output. */ bundle?: boolean; - /** Determines what the default library that should be used when type checking - * TS code. */ target: CompilerHostTarget; - /** A function to be used when the program emit occurs to write out files. */ writeFile: WriteFileCallback; } @@ -34,8 +25,6 @@ export interface ConfigureResponse { diagnostics?: ts.Diagnostic[]; } -/** Options that need to be used when generating a bundle (either trusted or - * runtime). */ export const defaultBundlerOptions: ts.CompilerOptions = { allowJs: true, inlineSourceMap: false, @@ -46,7 +35,6 @@ export const defaultBundlerOptions: ts.CompilerOptions = { sourceMap: false }; -/** Default options used by the compiler Host when compiling. */ export const defaultCompileOptions: ts.CompilerOptions = { allowJs: false, allowNonTsExtensions: true, @@ -62,12 +50,10 @@ export const defaultCompileOptions: ts.CompilerOptions = { target: ts.ScriptTarget.ESNext }; -/** Options that need to be used when doing a runtime (non bundled) compilation */ export const defaultRuntimeCompileOptions: ts.CompilerOptions = { outDir: undefined }; -/** Default options used when doing a transpile only. */ export const defaultTranspileOptions: ts.CompilerOptions = { esModuleInterop: true, module: ts.ModuleKind.ESNext, @@ -76,8 +62,6 @@ export const defaultTranspileOptions: ts.CompilerOptions = { target: ts.ScriptTarget.ESNext }; -/** Options that either do nothing in Deno, or would cause undesired behavior - * if modified. */ const ignoredCompilerOptions: readonly string[] = [ "allowSyntheticDefaultImports", "baseUrl", @@ -164,7 +148,6 @@ export class Host implements ts.CompilerHost { /* Deno specific APIs */ - /** Provides the `ts.HostCompiler` interface for Deno. */ constructor({ bundle = false, target, writeFile }: CompilerHostOptions) { this._target = target; this._writeFile = writeFile; @@ -174,9 +157,6 @@ export class Host implements ts.CompilerHost { } } - /** Take a configuration string, parse it, and use it to merge with the - * compiler's configuration options. The method returns an array of compiler - * options which were ignored, or `undefined`. */ configure(path: string, configurationText: string): ConfigureResponse { util.log("compiler::host.configure", path); assert(configurationText); @@ -208,8 +188,6 @@ export class Host implements ts.CompilerHost { }; } - /** Merge options into the host's current set of compiler options and return - * the merged set. */ mergeOptions(...options: ts.CompilerOptions[]): ts.CompilerOptions { Object.assign(this._options, ...options); return Object.assign({}, this._options); diff --git a/cli/js/compiler/imports.ts b/cli/js/compiler/imports.ts index 077303b61e..a3246c32f7 100644 --- a/cli/js/compiler/imports.ts +++ b/cli/js/compiler/imports.ts @@ -7,7 +7,6 @@ import { assert } from "../util.ts"; import * as util from "../util.ts"; import * as compilerOps from "../ops/compiler.ts"; -/** Resolve a path to the final path segment passed. */ function resolvePath(...pathSegments: string[]): string { let resolvedPath = ""; let resolvedAbsolute = false; @@ -45,8 +44,6 @@ function resolvePath(...pathSegments: string[]): string { else return "."; } -/** Resolve a relative specifier based on the referrer. Used when resolving - * modules internally within the runtime compiler API. */ function resolveSpecifier(specifier: string, referrer: string): string { if (!specifier.startsWith(".")) { return specifier; @@ -58,7 +55,6 @@ function resolveSpecifier(specifier: string, referrer: string): string { return resolvePath(path, specifier); } -/** Ops to Rust to resolve modules' URLs. */ export function resolveModules( specifiers: string[], referrer?: string @@ -67,7 +63,6 @@ export function resolveModules( return compilerOps.resolveModules(specifiers, referrer); } -/** Ops to Rust to fetch modules meta data. */ function fetchSourceFiles( specifiers: string[], referrer?: string @@ -76,8 +71,6 @@ function fetchSourceFiles( return compilerOps.fetchSourceFiles(specifiers, referrer); } -/** Given a filename, determine the media type based on extension. Used when - * resolving modules internally in a runtime compile. */ function getMediaType(filename: string): MediaType { const maybeExtension = /\.([a-zA-Z]+)$/.exec(filename); if (!maybeExtension) { @@ -104,12 +97,6 @@ function getMediaType(filename: string): MediaType { } } -/** Recursively process the imports of modules from within the supplied sources, - * generating `SourceFile`s of any imported files. - * - * Specifiers are supplied in an array of tuples where the first is the - * specifier that will be requested in the code and the second is the specifier - * that should be actually resolved. */ export function processLocalImports( sources: Record, specifiers: Array<[string, string]>, @@ -148,12 +135,6 @@ export function processLocalImports( return moduleNames; } -/** Recursively process the imports of modules, generating `SourceFile`s of any - * imported files. - * - * Specifiers are supplied in an array of tuples where the first is the - * specifier that will be requested in the code and the second is the specifier - * that should be actually resolved. */ export async function processImports( specifiers: Array<[string, string]>, referrer?: string, diff --git a/cli/js/compiler/sourcefile.ts b/cli/js/compiler/sourcefile.ts index cfa09cde32..159ccda857 100644 --- a/cli/js/compiler/sourcefile.ts +++ b/cli/js/compiler/sourcefile.ts @@ -15,7 +15,6 @@ export enum MediaType { Unknown = 6 } -/** The shape of the SourceFile that comes from the privileged side */ export interface SourceFileJson { url: string; filename: string; @@ -25,7 +24,6 @@ export interface SourceFileJson { export const ASSETS = "$asset$"; -/** Returns the TypeScript Extension enum for a given media type. */ function getExtension(fileName: string, mediaType: MediaType): ts.Extension { switch (mediaType) { case MediaType.JavaScript: @@ -49,15 +47,10 @@ function getExtension(fileName: string, mediaType: MediaType): ts.Extension { } } -/** A self registering abstraction of source files. */ export class SourceFile { extension!: ts.Extension; filename!: string; - /** An array of tuples which represent the imports for the source file. The - * first element is the one that will be requested at compile time, the - * second is the one that should be actually resolved. This provides the - * feature of type directives for Deno. */ importedFiles?: Array<[string, string]>; mediaType!: MediaType; @@ -75,8 +68,6 @@ export class SourceFile { SourceFile._moduleCache.set(this.url, this); } - /** Cache the source file to be able to be retrieved by `moduleSpecifier` and - * `containingFile`. */ cache(moduleSpecifier: string, containingFile?: string): void { containingFile = containingFile || ""; let innerCache = SourceFile._specifierCache.get(containingFile); @@ -87,7 +78,6 @@ export class SourceFile { innerCache.set(moduleSpecifier, this); } - /** Process the imports for the file and return them. */ imports(processJsImports: boolean): Array<[string, string]> { if (this.processed) { throw new Error("SourceFile has already been processed."); @@ -152,19 +142,13 @@ export class SourceFile { return files; } - /** A cache of all the source files which have been loaded indexed by the - * url. */ private static _moduleCache: Map = new Map(); - /** A cache of source files based on module specifiers and containing files - * which is used by the TypeScript compiler to resolve the url */ private static _specifierCache: Map< string, Map > = new Map(); - /** Retrieve a `SourceFile` based on a `moduleSpecifier` and `containingFile` - * or return `undefined` if not preset. */ static getUrl( moduleSpecifier: string, containingFile: string @@ -177,12 +161,10 @@ export class SourceFile { return undefined; } - /** Retrieve a `SourceFile` based on a `url` */ static get(url: string): SourceFile | undefined { return this._moduleCache.get(url); } - /** Determine if a source file exists or not */ static has(url: string): boolean { return this._moduleCache.has(url); } diff --git a/cli/js/compiler/type_directives.ts b/cli/js/compiler/type_directives.ts index 0f4ce932ca..299532f983 100644 --- a/cli/js/compiler/type_directives.ts +++ b/cli/js/compiler/type_directives.ts @@ -6,7 +6,6 @@ interface FileReference { end: number; } -/** Remap the module name based on any supplied type directives passed. */ export function getMappedModuleName( source: FileReference, typeDirectives: Map @@ -20,29 +19,10 @@ export function getMappedModuleName( return source.fileName; } -/** Matches directives that look something like this and parses out the value - * of the directive: - * - * // @deno-types="./foo.d.ts" - * - * [See Diagram](http://bit.ly/31nZPCF) - */ const typeDirectiveRegEx = /@deno-types\s*=\s*(["'])((?:(?=(\\?))\3.)*?)\1/gi; -/** Matches `import`, `import from` or `export from` statements and parses out the value of the - * module specifier in the second capture group: - * - * import "./foo.js" - * import * as foo from "./foo.js" - * export { a, b, c } from "./bar.js" - * - * [See Diagram](http://bit.ly/2lOsp0K) - */ const importExportRegEx = /(?:import|export)(?:\s+|\s+[\s\S]*?from\s+)?(["'])((?:(?=(\\?))\3.)*?)\1/; -/** Parses out any Deno type directives that are part of the source code, or - * returns `undefined` if there are not any. - */ export function parseTypeDirectives( sourceCode: string | undefined ): Map | undefined { diff --git a/cli/js/compiler/util.ts b/cli/js/compiler/util.ts index c1afbd581c..09725fc223 100644 --- a/cli/js/compiler/util.ts +++ b/cli/js/compiler/util.ts @@ -11,16 +11,12 @@ import * as util from "../util.ts"; import { assert } from "../util.ts"; import { writeFileSync } from "../write_file.ts"; -/** Type for the write fall callback that allows delegation from the compiler - * host on writing files. */ export type WriteFileCallback = ( fileName: string, data: string, sourceFiles?: readonly ts.SourceFile[] ) => void; -/** An object which is passed to `createWriteFile` to be used to read and set - * state related to the emit of a program. */ export interface WriteFileState { type: CompilerRequestType; bundle?: boolean; @@ -42,7 +38,6 @@ export enum CompilerRequestType { export const OUT_DIR = "$deno$"; -/** Cache the contents of a file on the trusted side. */ function cache( moduleId: string, emittedFileName: string, @@ -81,13 +76,10 @@ function cache( } } -/** Retrieve an asset from Rust. */ export function getAsset(name: string): string { return compilerOps.getAsset(name); } -/** Generates a `writeFile` function which can be passed to the compiler `Host` - * to use when emitting files. */ export function createWriteFile(state: WriteFileState): WriteFileCallback { const encoder = new TextEncoder(); if (state.type === CompilerRequestType.Compile) { @@ -171,8 +163,6 @@ export interface ConvertCompilerOptionsResult { options: ts.CompilerOptions; } -/** Take a runtime set of compiler options as stringified JSON and convert it - * to a set of TypeScript compiler options. */ export function convertCompilerOptions( str: string ): ConvertCompilerOptionsResult { @@ -269,7 +259,6 @@ export function convertCompilerOptions( }; } -/** An array of TypeScript diagnostic types we ignore. */ export const ignoredDiagnostics = [ // TS2306: File 'file:///Users/rld/src/deno/cli/tests/subdir/amd_like.js' is // not a module. @@ -301,8 +290,6 @@ export const ignoredDiagnostics = [ 7016 ]; -/** When doing a host configuration, processing the response and logging out - * and options which were ignored. */ export function processConfigureResponse( configResult: ConfigureResponse, configPath: string @@ -322,7 +309,6 @@ export function processConfigureResponse( export const CHAR_DOT = 46; /* . */ export const CHAR_FORWARD_SLASH = 47; /* / */ -/** Resolves `.` and `..` elements in a path with directory names */ export function normalizeString( path: string, allowAboveRoot: boolean, @@ -390,12 +376,6 @@ export function normalizeString( return res; } -/** Return the common path shared by the `paths`. - * - * @param paths The set of paths to compare. - * @param sep An optional separator to use. Defaults to `/`. - * @internal - */ export function commonPath(paths: string[], sep = "/"): string { const [first = "", ...remaining] = paths; if (first === "" || remaining.length === 0) { @@ -420,8 +400,6 @@ export function commonPath(paths: string[], sep = "/"): string { return prefix.endsWith(sep) ? prefix : `${prefix}${sep}`; } -/** Utility function to turn the number of bytes into a human readable - * unit */ function humanFileSize(bytes: number): string { const thresh = 1000; if (Math.abs(bytes) < thresh) { diff --git a/cli/js/deno.ts b/cli/js/deno.ts index 2ecd7680c1..b22f076ef7 100644 --- a/cli/js/deno.ts +++ b/cli/js/deno.ts @@ -122,13 +122,10 @@ export { test, runTests } from "./testing.ts"; // These are internal Deno APIs. We are marking them as internal so they do not // appear in the runtime type library. -/** @internal */ export { core } from "./core.ts"; -/** The current process id of the runtime. */ export let pid: number; -/** Reflects the NO_COLOR environment variable: https://no-color.org/ */ export let noColor: boolean; export { symbols } from "./symbols.ts"; diff --git a/cli/js/diagnostics.ts b/cli/js/diagnostics.ts index f0171bac61..41a8ea8b21 100644 --- a/cli/js/diagnostics.ts +++ b/cli/js/diagnostics.ts @@ -4,7 +4,6 @@ // compiler, which is strongly influenced by the format of TypeScript // diagnostics. -/** The log category for a diagnostic message */ export enum DiagnosticCategory { Log = 0, Debug = 1, @@ -22,45 +21,31 @@ export interface DiagnosticMessageChain { } export interface DiagnosticItem { - /** A string message summarizing the diagnostic. */ message: string; - /** An ordered array of further diagnostics. */ messageChain?: DiagnosticMessageChain; - /** Information related to the diagnostic. This is present when there is a - * suggestion or other additional diagnostic information */ relatedInformation?: DiagnosticItem[]; - /** The text of the source line related to the diagnostic */ sourceLine?: string; - /** The line number that is related to the diagnostic */ lineNumber?: number; - /** The name of the script resource related to the diagnostic */ scriptResourceName?: string; - /** The start position related to the diagnostic */ startPosition?: number; - /** The end position related to the diagnostic */ endPosition?: number; - /** The category of the diagnostic */ category: DiagnosticCategory; - /** A number identifier */ code: number; - /** The the start column of the sourceLine related to the diagnostic */ startColumn?: number; - /** The end column of the sourceLine related to the diagnostic */ endColumn?: number; } export interface Diagnostic { - /** An array of diagnostic items. */ items: DiagnosticItem[]; } diff --git a/cli/js/diagnostics_util.ts b/cli/js/diagnostics_util.ts index f7d0f5b72b..24a8936789 100644 --- a/cli/js/diagnostics_util.ts +++ b/cli/js/diagnostics_util.ts @@ -71,7 +71,6 @@ function getSourceInformation( }; } -/** Converts a TypeScript diagnostic message chain to a Deno one. */ function fromDiagnosticMessageChain( messageChain: ts.DiagnosticMessageChain[] | undefined ): DiagnosticMessageChain[] | undefined { @@ -89,7 +88,6 @@ function fromDiagnosticMessageChain( }); } -/** Parse out information from a TypeScript diagnostic structure. */ function parseDiagnostic( item: ts.Diagnostic | ts.DiagnosticRelatedInformation ): DiagnosticItem { @@ -130,8 +128,6 @@ function parseDiagnostic( return sourceInfo ? { ...base, ...sourceInfo } : base; } -/** Convert a diagnostic related information array into a Deno diagnostic - * array. */ function parseRelatedInformation( relatedInformation: readonly ts.DiagnosticRelatedInformation[] ): DiagnosticItem[] { @@ -142,7 +138,6 @@ function parseRelatedInformation( return result; } -/** Convert TypeScript diagnostics to Deno diagnostics. */ export function fromTypeScriptDiagnostic( diagnostics: readonly ts.Diagnostic[] ): Diagnostic { diff --git a/cli/js/error_stack.ts b/cli/js/error_stack.ts index 8d2badc20a..6ec8752e6e 100644 --- a/cli/js/error_stack.ts +++ b/cli/js/error_stack.ts @@ -5,9 +5,6 @@ import { applySourceMap, Location } from "./ops/errors.ts"; import { assert } from "./util.ts"; import { exposeForTest } from "./internals.ts"; -/** Mutate the call site so that it returns the location, instead of its - * original location. - */ function patchCallSite(callSite: CallSite, location: Location): CallSite { return { getThis(): unknown { @@ -61,10 +58,6 @@ function patchCallSite(callSite: CallSite, location: Location): CallSite { }; } -/** Return a string representations of a CallSite's method call name - * - * This is adapted directly from V8. - */ function getMethodCall(callSite: CallSite): string { let result = ""; @@ -100,10 +93,6 @@ function getMethodCall(callSite: CallSite): string { return result; } -/** Return a string representations of a CallSite's file location - * - * This is adapted directly from V8. - */ function getFileLocation(callSite: CallSite): string { if (callSite.isNative()) { return "native"; @@ -137,10 +126,6 @@ function getFileLocation(callSite: CallSite): string { return result; } -/** Convert a CallSite to a string. - * - * This is adapted directly from V8. - */ function callSiteToString(callSite: CallSite): string { let result = ""; const functionName = callSite.getFunctionName(); @@ -178,9 +163,6 @@ function callSiteToString(callSite: CallSite): string { return result; } -/** A replacement for the default stack trace preparer which will op into Rust - * to apply source maps to individual sites - */ function prepareStackTrace( error: Error, structuredStackTrace: CallSite[] @@ -211,12 +193,6 @@ function prepareStackTrace( ); } -/** Sets the `prepareStackTrace` method on the Error constructor which will - * op into Rust to remap source code for caught errors where the `.stack` is - * being accessed. - * - * See: https://v8.dev/docs/stack-trace-api - */ // @internal export function setPrepareStackTrace(ErrorConstructor: typeof Error): void { ErrorConstructor.prepareStackTrace = prepareStackTrace; diff --git a/cli/js/file_info.ts b/cli/js/file_info.ts index 884f850d20..e7ac646fbf 100644 --- a/cli/js/file_info.ts +++ b/cli/js/file_info.ts @@ -2,71 +2,23 @@ import { StatResponse } from "./ops/fs/stat.ts"; import { build } from "./build.ts"; -/** A FileInfo describes a file and is returned by `stat`, `lstat`, - * `statSync`, `lstatSync`. A list of FileInfo is returned by `readdir`, - * `readdirSync`. */ export interface FileInfo { - /** The size of the file, in bytes. */ len: 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. */ modified: number | 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. */ accessed: number | null; - /** The last access 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. */ created: number | null; - /** The file or directory name. */ name: string | null; - /** ID of the device containing the file. - * - * _Linux/Mac OS only._ */ dev: number | null; - /** Inode number. - * - * _Linux/Mac OS only._ */ ino: number | null; - /** **UNSTABLE**: Match behavior with Go on windows for `mode`. - * - * The underlying raw `st_mode` bits that contain the standard Unix - * permissions for this file/directory. */ 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; - /** User 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; - /** Returns whether this is info for a regular file. This result is mutually - * exclusive to `FileInfo.isDirectory` and `FileInfo.isSymlink`. */ isFile(): boolean; - /** Returns whether this is info for a regular directory. This result is - * mutually exclusive to `FileInfo.isFile` and `FileInfo.isSymlink`. */ isDirectory(): boolean; - /** Returns whether this is info for a symlink. This result is - * mutually exclusive to `FileInfo.isFile` and `FileInfo.isDirectory`. */ isSymlink(): boolean; } diff --git a/cli/js/files.ts b/cli/js/files.ts index 945390ca0c..b9da1363f0 100644 --- a/cli/js/files.ts +++ b/cli/js/files.ts @@ -22,12 +22,6 @@ import { } from "./ops/fs/open.ts"; export { OpenOptions, OpenMode } from "./ops/fs/open.ts"; -/** Synchronously open a file and return an instance of the `File` object. - * - * const file = Deno.openSync("/foo/bar.txt", { read: true, write: true }); - * - * Requires `allow-read` and `allow-write` permissions depending on mode. - */ export function openSync(path: string, mode?: OpenOptions): File; export function openSync(path: string, mode?: OpenMode): File; export function openSync( @@ -48,12 +42,6 @@ export function openSync( return new File(rid); } -/** Open a file and resolve to an instance of the `File` object. - * - * const file = await Deno.open("/foo/bar.txt", { read: true, write: true }); - * - * Requires `allow-read` and `allow-write` permissions depending on mode. - */ export async function open(path: string, options?: OpenOptions): Promise; export async function open(path: string, mode?: OpenMode): Promise; export async function open( @@ -74,29 +62,14 @@ export async function open( return new File(rid); } -/** Creates a file if none exists or truncates an existing file and returns - * an instance of `Deno.File`. - * - * const file = Deno.createSync("/foo/bar.txt"); - * - * Requires `allow-read` and `allow-write` permissions. - */ export function createSync(path: string): File { return openSync(path, "w+"); } -/** Creates a file if none exists or truncates an existing file and resolves to - * an instance of `Deno.File`. - * - * const file = await Deno.create("/foo/bar.txt"); - * - * Requires `allow-read` and `allow-write` permissions. - */ export function create(path: string): Promise { return open(path, "w+"); } -/** The Deno abstraction for reading and writing files. */ export class File implements Reader, @@ -137,17 +110,10 @@ export class File } } -/** An instance of `Deno.File` for `stdin`. */ export const stdin = new File(0); -/** An instance of `Deno.File` for `stdout`. */ export const stdout = new File(1); -/** An instance of `Deno.File` for `stderr`. */ export const stderr = new File(2); -/** Check if OpenOptions is set to valid combination of options. - * @returns Tuple representing if openMode is valid and error message if it's not - * @internal - */ function checkOpenOptions(options: OpenOptions): void { if (Object.values(options).filter(val => val === true).length === 0) { throw new Error("OpenOptions requires at least one option to be true"); diff --git a/cli/js/io.ts b/cli/js/io.ts index e7311d0f4b..5e0ee79035 100644 --- a/cli/js/io.ts +++ b/cli/js/io.ts @@ -8,7 +8,6 @@ export type EOF = typeof EOF; // Seek whence values. // https://golang.org/pkg/io/#pkg-constants -/** **UNSTABLE**: might remove `"SEEK_"` prefix. Might not use all-caps. */ export enum SeekMode { SEEK_START = 0, SEEK_CURRENT = 1, @@ -17,76 +16,21 @@ export enum SeekMode { // Reader is the interface that wraps the basic read() method. // https://golang.org/pkg/io/#Reader -/** **UNSTABLE**: might make `Reader` into iterator of some sort. */ 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 - * `Deno.EOF` symbol. - * - * When `read()` encounters an error, it rejects with an error. - * - * Callers should always process the `n` > `0` bytes returned before - * considering the `EOF`. 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`. - */ read(p: Uint8Array): Promise; } export interface SyncReader { - /** 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()` 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, `read()` conventionally returns what is - * available instead of waiting for more. - * - * When `readSync()` encounters end-of-file condition, it returns `Deno.EOF` - * symbol. - * - * When `readSync()` encounters an error, it throws with an error. - * - * Callers should always process the `n` > `0` bytes returned before - * considering the `EOF`. 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`. - */ readSync(p: Uint8Array): number | EOF; } // Writer is the interface that wraps the basic write() method. // https://golang.org/pkg/io/#Writer 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. - * - * Implementations should not retain a reference to `p`. - */ write(p: Uint8Array): Promise; } export interface SyncWriter { - /** 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; } @@ -99,16 +43,6 @@ export interface Closer { // https://golang.org/pkg/io/#Seeker export interface Seeker { - /** Seek sets the offset for the next `read()` or `write()` to offset, - * interpreted according to `whence`: `SEEK_START` means relative to the - * start of the file, `SEEK_CURRENT` means relative to the current offset, - * and `SEEK_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 cursor - * position. - */ seek(offset: number, whence: SeekMode): Promise; } @@ -134,13 +68,6 @@ export interface ReadWriteCloser extends Reader, Writer, Closer {} // https://golang.org/pkg/io/#ReadWriteSeeker export interface ReadWriteSeeker extends Reader, Writer, Seeker {} -/** Copies from `src` to `dst` until either `EOF` is reached on `src` or an - * error occurs. It resolves to the number of bytes copied or rejects with - * the first error encountered while copying. - * - * Because `copy()` is defined to read from `src` until `EOF`, it does not - * treat an `EOF` from `read()` as an error to be reported. - */ // https://golang.org/pkg/io/#Copy export async function copy(dst: Writer, src: Reader): Promise { let n = 0; @@ -157,12 +84,6 @@ export async function copy(dst: Writer, src: Reader): Promise { return n; } -/** Turns `r` into async iterator. - * - * for await (const chunk of toAsyncIterator(reader)) { - * console.log(chunk); - * } - */ export function toAsyncIterator(r: Reader): AsyncIterableIterator { const b = new Uint8Array(1024); return { diff --git a/cli/js/net.ts b/cli/js/net.ts index 52c5583391..570bada49d 100644 --- a/cli/js/net.ts +++ b/cli/js/net.ts @@ -19,36 +19,23 @@ export interface UDPAddr { port: number; } -/** A socket is a generic transport listener for message-oriented protocols */ export interface UDPConn extends AsyncIterable<[Uint8Array, Addr]> { - /** Waits for and resolves to the next message to the `Socket`. */ receive(p?: Uint8Array): Promise<[Uint8Array, Addr]>; - /** Sends a message to the target. */ send(p: Uint8Array, addr: UDPAddr): Promise; - /** Close closes the socket. Any pending message promises will be rejected - * with errors. - */ close(): void; - /** Return the address of the `Socket`. */ addr: Addr; [Symbol.asyncIterator](): AsyncIterator<[Uint8Array, Addr]>; } -/** A Listener is a generic transport listener for stream-oriented protocols. */ export interface Listener extends AsyncIterable { - /** 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`. */ addr: Addr; [Symbol.asyncIterator](): AsyncIterator; @@ -73,16 +60,10 @@ export class ConnImpl implements Conn { close(this.rid); } - /** closeRead shuts down (shutdown(2)) the reading side of the TCP connection. - * Most callers should just use close(). - */ closeRead(): void { netOps.shutdown(this.rid, netOps.ShutdownMode.Read); } - /** closeWrite shuts down (shutdown(2)) the writing side of the TCP - * connection. Most callers should just use close(). - */ closeWrite(): void { netOps.shutdown(this.rid, netOps.ShutdownMode.Write); } @@ -162,19 +143,10 @@ export class UDPConnImpl implements UDPConn { } export interface Conn extends Reader, Writer, Closer { - /** The local address of the connection. */ localAddr: Addr; - /** The remote address of the connection. */ remoteAddr: Addr; - /** The resource ID of the connection. */ rid: number; - /** Shuts down (`shutdown(2)`) the reading side of the TCP connection. Most - * callers should just use `close()`. - */ closeRead(): void; - /** Shuts down (`shutdown(2)`) the writing side of the TCP connection. Most - * callers should just use `close()`. - */ closeWrite(): void; } @@ -184,23 +156,6 @@ export interface ListenOptions { transport?: Transport; } -/** Listen announces on the local transport address. - * - * @param options - * @param options.port The port to connect to. (Required.) - * @param options.hostname A literal IP address or host name that can be - * resolved to an IP address. If not specified, defaults to 0.0.0.0 - * @param options.transport Must be "tcp" or "udp". Defaults to "tcp". Later we plan to add "tcp4", - * "tcp6", "udp4", "udp6", "ip", "ip4", "ip6", "unix", "unixgram" and - * "unixpacket". - * - * Examples: - * - * listen({ port: 80 }) - * listen({ hostname: "192.0.2.1", port: 80 }) - * listen({ hostname: "[2001:db8::1]", port: 80 }); - * listen({ hostname: "golang.org", port: 80, transport: "tcp" }) - */ export function listen( options: ListenOptions & { transport?: "tcp" } ): Listener; @@ -225,23 +180,6 @@ export interface ConnectOptions { transport?: Transport; } -/** Connects to the address on the named transport. - * - * @param options - * @param options.port The port to connect to. (Required.) - * @param options.hostname A literal IP address or host name that can be - * resolved to an IP address. If not specified, defaults to 127.0.0.1 - * @param options.transport Must be "tcp" or "udp". Defaults to "tcp". Later we plan to add "tcp4", - * "tcp6", "udp4", "udp6", "ip", "ip4", "ip6", "unix", "unixgram" and - * "unixpacket". - * - * Examples: - * - * connect({ port: 80 }) - * connect({ hostname: "192.0.2.1", port: 80 }) - * connect({ hostname: "[2001:db8::1]", port: 80 }); - * connect({ hostname: "golang.org", port: 80, transport: "tcp" }) - */ export async function connect({ port, hostname = "127.0.0.1", diff --git a/cli/js/ops/compiler.ts b/cli/js/ops/compiler.ts index b45ad42b2c..0cbde6543a 100644 --- a/cli/js/ops/compiler.ts +++ b/cli/js/ops/compiler.ts @@ -4,7 +4,6 @@ import { sendAsync, sendSync } from "./dispatch_json.ts"; import { TextDecoder, TextEncoder } from "../web/text_encoding.ts"; import { core } from "../core.ts"; -/** Ops to Rust to resolve modules' URLs. */ export function resolveModules( specifiers: string[], referrer?: string @@ -12,7 +11,6 @@ export function resolveModules( return sendSync("op_resolve_modules", { specifiers, referrer }); } -/** Ops to Rust to fetch modules meta data. */ export function fetchSourceFiles( specifiers: string[], referrer?: string @@ -33,7 +31,6 @@ export function fetchSourceFiles( const encoder = new TextEncoder(); const decoder = new TextDecoder(); -/** This op is also used during snapshotting */ export function getAsset(name: string): string { const opId = core.ops()["op_fetch_asset"]; // We really don't want to depend on JSON dispatch during snapshotting, so diff --git a/cli/js/ops/errors.ts b/cli/js/ops/errors.ts index f96e376d6e..39793a85d1 100644 --- a/cli/js/ops/errors.ts +++ b/cli/js/ops/errors.ts @@ -2,48 +2,18 @@ import { DiagnosticItem } from "../diagnostics.ts"; import { sendSync } from "./dispatch_json.ts"; -/** - * Format an array of diagnostic items and return them as a single string. - * @param items An array of diagnostic items to format - */ export function formatDiagnostics(items: DiagnosticItem[]): string { return sendSync("op_format_diagnostic", { items }); } export interface Location { - /** The full url for the module, e.g. `file://some/file.ts` or - * `https://some/file.ts`. */ filename: string; - /** The line number in the file. It is assumed to be 1-indexed. */ line: number; - /** The column number in the file. It is assumed to be 1-indexed. */ column: number; } -/** Given a current location in a module, lookup the source location and - * return it. - * - * When Deno transpiles code, it keep source maps of the transpiled code. This - * function can be used to lookup the original location. This is automatically - * done when accessing the `.stack` of an error, or when an uncaught error is - * logged. This function can be used to perform the lookup for creating better - * error handling. - * - * **Note:** `line` and `column` are 1 indexed, which matches display - * expectations, but is not typical of most index numbers in Deno. - * - * An example: - * - * const orig = Deno.applySourceMap({ - * location: "file://my/module.ts", - * line: 5, - * column: 15 - * }); - * console.log(`${orig.filename}:${orig.line}:${orig.column}`); - * - */ export function applySourceMap(location: Location): Location { const { filename, line, column } = location; // On this side, line/column are 1 based, but in the source maps, they are diff --git a/cli/js/ops/fs/chmod.ts b/cli/js/ops/fs/chmod.ts index 9e748672f5..91e898360c 100644 --- a/cli/js/ops/fs/chmod.ts +++ b/cli/js/ops/fs/chmod.ts @@ -1,22 +1,10 @@ // Copyright 2018-2020 the Deno authors. All rights reserved. MIT license. import { sendSync, sendAsync } from "../dispatch_json.ts"; -/** Synchronously changes the permission of a specific file/directory of - * specified path. Ignores the process's umask. - * - * Deno.chmodSync("/path/to/file", 0o666); - * - * Requires `allow-write` permission. */ export function chmodSync(path: string, mode: number): void { sendSync("op_chmod", { path, mode }); } -/** Changes the permission of a specific file/directory of specified path. - * Ignores the process's umask. - * - * await Deno.chmod("/path/to/file", 0o666); - * - * Requires `allow-write` permission. */ export async function chmod(path: string, mode: number): Promise { await sendAsync("op_chmod", { path, mode }); } diff --git a/cli/js/ops/fs/chown.ts b/cli/js/ops/fs/chown.ts index 6f871f3133..d6e3702c6f 100644 --- a/cli/js/ops/fs/chown.ts +++ b/cli/js/ops/fs/chown.ts @@ -1,28 +1,10 @@ // Copyright 2018-2020 the Deno authors. All rights reserved. MIT license. import { sendSync, sendAsync } from "../dispatch_json.ts"; -/** Synchronously change owner of a regular file or directory. Linux/Mac OS - * only at the moment. - * - * Requires `allow-write` permission. - * - * @param path path to the file - * @param uid user id of the new owner - * @param gid group id of the new owner - */ export function chownSync(path: string, uid: number, gid: number): void { sendSync("op_chown", { path, uid, gid }); } -/** Change owner of a regular file or directory. Linux/Mac OS only at the - * moment. - * - * Requires `allow-write` permission. - * - * @param path path to the file - * @param uid user id of the new owner - * @param gid group id of the new owner - */ export async function chown( path: string, uid: number, diff --git a/cli/js/ops/fs/copy_file.ts b/cli/js/ops/fs/copy_file.ts index 6bd49fe2c4..4c8c746678 100644 --- a/cli/js/ops/fs/copy_file.ts +++ b/cli/js/ops/fs/copy_file.ts @@ -1,26 +1,10 @@ // Copyright 2018-2020 the Deno authors. All rights reserved. MIT license. import { sendSync, sendAsync } from "../dispatch_json.ts"; -/** 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. - * - * Deno.copyFileSync("from.txt", "to.txt"); - * - * Requires `allow-read` permission on fromPath. - * Requires `allow-write` permission on toPath. */ export function copyFileSync(fromPath: string, toPath: string): void { sendSync("op_copy_file", { from: fromPath, to: toPath }); } -/** 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. - * - * await Deno.copyFile("from.txt", "to.txt"); - * - * Requires `allow-read` permission on fromPath. - * Requires `allow-write` permission on toPath. */ export async function copyFile( fromPath: string, toPath: string diff --git a/cli/js/ops/fs/dir.ts b/cli/js/ops/fs/dir.ts index e9e95005b9..14b6240ed2 100644 --- a/cli/js/ops/fs/dir.ts +++ b/cli/js/ops/fs/dir.ts @@ -1,27 +1,10 @@ // Copyright 2018-2020 the Deno authors. All rights reserved. MIT license. import { sendSync } from "../dispatch_json.ts"; -/** - * **UNSTABLE**: maybe needs permissions. - * - * 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. - * - * Throws `Deno.errors.NotFound` if directory not available. - */ export function cwd(): string { return sendSync("op_cwd"); } -/** - * **UNSTABLE**: maybe needs permissions. - * - * Change the current working directory to the specified path. - * - * Throws `Deno.errors.NotFound` if directory not available. - */ export function chdir(directory: string): void { sendSync("op_chdir", { directory }); } diff --git a/cli/js/ops/fs/link.ts b/cli/js/ops/fs/link.ts index 0f083dd7b9..24a874d479 100644 --- a/cli/js/ops/fs/link.ts +++ b/cli/js/ops/fs/link.ts @@ -1,20 +1,10 @@ // Copyright 2018-2020 the Deno authors. All rights reserved. MIT license. import { sendSync, sendAsync } from "../dispatch_json.ts"; -/** Creates `newname` as a hard link to `oldname`. - * - * Deno.linkSync("old/name", "new/name"); - * - * Requires `allow-read` and `allow-write` permissions. */ export function linkSync(oldname: string, newname: string): void { sendSync("op_link", { oldname, newname }); } -/** Creates `newname` as a hard link to `oldname`. - * - * await Deno.link("old/name", "new/name"); - * - * Requires `allow-read` and `allow-write` permissions. */ export async function link(oldname: string, newname: string): Promise { await sendAsync("op_link", { oldname, newname }); } diff --git a/cli/js/ops/fs/make_temp.ts b/cli/js/ops/fs/make_temp.ts index 1fbff41d00..cc8a76435e 100644 --- a/cli/js/ops/fs/make_temp.ts +++ b/cli/js/ops/fs/make_temp.ts @@ -2,87 +2,25 @@ import { sendSync, sendAsync } from "../dispatch_json.ts"; export interface MakeTempOptions { - /** Directory where the temporary directory should be created (defaults to - * the env variable TMPDIR, or the system's default, usually /tmp). */ 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; } -/** Synchronously creates a new temporary directory in the directory `dir`, - * its name beginning with `prefix` and ending with `suffix`. - * - * It returns the full path to the newly created directory. - * - * If `dir` is unspecified, uses the default directory for temporary files. - * Multiple programs calling this function simultaneously will create different - * directories. It is the caller's responsibility to remove the directory when - * no longer needed. - * - * const tempDirName0 = Deno.makeTempDirSync(); - * const tempDirName1 = Deno.makeTempDirSync({ prefix: 'my_temp' }); - * - * Requires `allow-write` permission. */ export function makeTempDirSync(options: MakeTempOptions = {}): string { return sendSync("op_make_temp_dir", options); } -/** Creates a new temporary directory in the directory `dir`, its name - * beginning with `prefix` and ending with `suffix`. - * - * It resolves to the full path to the newly created directory. - * - * If `dir` is unspecified, uses the default directory for temporary files. - * Multiple programs calling this function simultaneously will create different - * directories. It is the caller's responsibility to remove the directory when - * no longer needed. - * - * const tempDirName0 = await Deno.makeTempDir(); - * const tempDirName1 = await Deno.makeTempDir({ prefix: 'my_temp' }); - * - * Requires `allow-write` permission. */ export async function makeTempDir( options: MakeTempOptions = {} ): Promise { return await sendAsync("op_make_temp_dir", options); } -/** Synchronously creates a new temporary file in the directory `dir`, its name - * beginning with `prefix` and ending with `suffix`. - * - * It returns the full path to the newly created file. - * - * If `dir` is unspecified, uses the default directory for temporary files. - * Multiple programs calling this function simultaneously will create different - * files. It is the caller's responsibility to remove the file when - * no longer needed. - * - * const tempFileName0 = Deno.makeTempFileSync(); - * const tempFileName1 = Deno.makeTempFileSync({ prefix: 'my_temp' }); - * - * Requires `allow-write` permission. */ export function makeTempFileSync(options: MakeTempOptions = {}): string { return sendSync("op_make_temp_file", options); } -/** Creates a new temporary file in the directory `dir`, its name - * beginning with `prefix` and ending with `suffix`. - * - * It resolves to the full path to the newly created file. - * - * If `dir` is unspecified, uses the default directory for temporary files. - * Multiple programs calling this function simultaneously will create different - * files. It is the caller's responsibility to remove the file when - * no longer needed. - * - * const tempFileName0 = await Deno.makeTempFile(); - * const tempFileName1 = await Deno.makeTempFile({ prefix: 'my_temp' }); - * - * Requires `allow-write` permission. */ export async function makeTempFile( options: MakeTempOptions = {} ): Promise { diff --git a/cli/js/ops/fs/mkdir.ts b/cli/js/ops/fs/mkdir.ts index 0bd088defd..8ecc516761 100644 --- a/cli/js/ops/fs/mkdir.ts +++ b/cli/js/ops/fs/mkdir.ts @@ -28,24 +28,10 @@ function mkdirArgs( } export interface MkdirOptions { - /** Defaults to `false`. 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. */ recursive?: boolean; - /** Permissions to use when creating the directory (defaults to `0o777`, - * before the process's umask). - * Ignored on Windows. */ mode?: number; } -/** Synchronously creates a new directory with the specified path. - * - * Deno.mkdirSync("new_dir"); - * Deno.mkdirSync("nested/directories", { recursive: true }); - * - * Requires `allow-write` permission. */ export function mkdirSync( path: string, optionsOrRecursive?: MkdirOptions | boolean, @@ -54,12 +40,6 @@ export function mkdirSync( sendSync("op_mkdir", mkdirArgs(path, optionsOrRecursive, mode)); } -/** Creates a new directory with the specified path. - * - * await Deno.mkdir("new_dir"); - * await Deno.mkdir("nested/directories", { recursive: true }); - * - * Requires `allow-write` permission. */ export async function mkdir( path: string, optionsOrRecursive?: MkdirOptions | boolean, diff --git a/cli/js/ops/fs/open.ts b/cli/js/ops/fs/open.ts index e166ef16b4..0d3c236675 100644 --- a/cli/js/ops/fs/open.ts +++ b/cli/js/ops/fs/open.ts @@ -2,48 +2,14 @@ import { sendSync, sendAsync } from "../dispatch_json.ts"; export interface OpenOptions { - /** Sets the option for read access. This option, when `true`, means that the - * file should be read-able if opened. */ 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. */ 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 }`. */ 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` - * length if it already exists. The file must be opened with write access - * for truncate to work. */ 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. */ create?: boolean; - /** Defaults to `false`. 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. */ createNew?: boolean; } -/** A set of string literals which specify the open mode of a file. - * - * |Value |Description | - * |------|--------------------------------------------------------------------------------------------------| - * |`"r"` |Read-only. Default. Starts at beginning of file. | - * |`"r+"`|Read-write. Start at beginning of file. | - * |`"w"` |Write-only. Opens and truncates existing file or creates new one for writing only. | - * |`"w+"`|Read-write. Opens and truncates existing file or creates new one for writing and reading. | - * |`"a"` |Write-only. Opens existing file or creates new one. Each write appends content to the end of file.| - * |`"a+"`|Read-write. Behaves like `"a"` and allows to read from file. | - * |`"x"` |Write-only. Exclusive create - creates new file only if one doesn't exist already. | - * |`"x+"`|Read-write. Behaves like `x` and allows reading from file. | - */ export type OpenMode = "r" | "r+" | "w" | "w+" | "a" | "a+" | "x" | "x+"; export function openSync( diff --git a/cli/js/ops/fs/read_dir.ts b/cli/js/ops/fs/read_dir.ts index 75c821c338..c48104d4b8 100644 --- a/cli/js/ops/fs/read_dir.ts +++ b/cli/js/ops/fs/read_dir.ts @@ -15,23 +15,10 @@ function res(response: ReadDirResponse): FileInfo[] { ); } -/** Synchronously reads the directory given by `path` and returns an array of - * `Deno.FileInfo`. - * - * const files = Deno.readdirSync("/"); - * - * Requires `allow-read` permission. */ export function readdirSync(path: string): FileInfo[] { return res(sendSync("op_read_dir", { path })); } -/** UNSTABLE: Maybe need to return an `AsyncIterable`. - * - * Reads the directory given by `path` and resolves to an array of `Deno.FileInfo`. - * - * const files = await Deno.readdir("/"); - * - * Requires `allow-read` permission. */ export async function readdir(path: string): Promise { return res(await sendAsync("op_read_dir", { path })); } diff --git a/cli/js/ops/fs/read_link.ts b/cli/js/ops/fs/read_link.ts index b5ac82cd7e..3c74e1f2e9 100644 --- a/cli/js/ops/fs/read_link.ts +++ b/cli/js/ops/fs/read_link.ts @@ -1,20 +1,10 @@ // Copyright 2018-2020 the Deno authors. All rights reserved. MIT license. import { sendSync, sendAsync } from "../dispatch_json.ts"; -/** Returns the destination of the named symbolic link. - * - * const targetPath = Deno.readlinkSync("symlink/path"); - * - * Requires `allow-read` permission. */ export function readlinkSync(path: string): string { return sendSync("op_read_link", { path }); } -/** Resolves to the destination of the named symbolic link. - * - * const targetPath = await Deno.readlink("symlink/path"); - * - * Requires `allow-read` permission. */ export async function readlink(path: string): Promise { return await sendAsync("op_read_link", { path }); } diff --git a/cli/js/ops/fs/realpath.ts b/cli/js/ops/fs/realpath.ts index c8070edea4..625e6702dd 100644 --- a/cli/js/ops/fs/realpath.ts +++ b/cli/js/ops/fs/realpath.ts @@ -1,18 +1,10 @@ // Copyright 2018-2020 the Deno authors. All rights reserved. MIT license. import { sendSync, sendAsync } from "../dispatch_json.ts"; -/** Returns absolute normalized path with symbolic links resolved synchronously. - * - * const realPath = Deno.realpathSync("./some/path"); - */ export function realpathSync(path: string): string { return sendSync("op_realpath", { path }); } -/** Returns absolute normalized path with symbolic links resolved. - * - * const realPath = await Deno.realpath("./some/path"); - */ export async function realpath(path: string): Promise { return await sendAsync("op_realpath", { path }); } diff --git a/cli/js/ops/fs/remove.ts b/cli/js/ops/fs/remove.ts index 5650357938..d5af82f9b9 100644 --- a/cli/js/ops/fs/remove.ts +++ b/cli/js/ops/fs/remove.ts @@ -2,29 +2,13 @@ import { sendSync, sendAsync } from "../dispatch_json.ts"; export interface RemoveOptions { - /** Defaults to `false`. If set to `true`, path will be removed even if - * it's a non-empty directory. */ recursive?: boolean; } -/** Synchronously removes the named file or directory. Throws error if - * permission denied, path not found, or path is a non-empty directory and - * the `recursive` option isn't set to `true`. - * - * Deno.removeSync("/path/to/dir/or/file", { recursive: false }); - * - * Requires `allow-write` permission. */ export function removeSync(path: string, options: RemoveOptions = {}): void { sendSync("op_remove", { path, recursive: !!options.recursive }); } -/** Removes the named file or directory. Throws error if permission denied, - * path not found, or path is a non-empty directory and the `recursive` - * option isn't set to `true`. - * - * await Deno.remove("/path/to/dir/or/file", { recursive: false }); - * - * Requires `allow-write` permission. */ export async function remove( path: string, options: RemoveOptions = {} diff --git a/cli/js/ops/fs/rename.ts b/cli/js/ops/fs/rename.ts index 016ebc2d76..9f02c8bc06 100644 --- a/cli/js/ops/fs/rename.ts +++ b/cli/js/ops/fs/rename.ts @@ -1,25 +1,10 @@ // Copyright 2018-2020 the Deno authors. All rights reserved. MIT license. import { sendSync, sendAsync } from "../dispatch_json.ts"; -/** Synchronously renames (moves) `oldpath` to `newpath`. 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. - * - * Deno.renameSync("old/path", "new/path"); - * - * Requires `allow-read` and `allow-write` permissions. */ export function renameSync(oldpath: string, newpath: string): void { sendSync("op_rename", { oldpath, newpath }); } -/** Renames (moves) `oldpath` to `newpath`. 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. - * - * await Deno.rename("old/path", "new/path"); - * - * Requires `allow-read` and `allow-write`. */ export async function rename(oldpath: string, newpath: string): Promise { await sendAsync("op_rename", { oldpath, newpath }); } diff --git a/cli/js/ops/fs/seek.ts b/cli/js/ops/fs/seek.ts index 313d365c60..a3b055c95b 100644 --- a/cli/js/ops/fs/seek.ts +++ b/cli/js/ops/fs/seek.ts @@ -2,13 +2,6 @@ import { sendSync, sendAsync } from "../dispatch_json.ts"; import { SeekMode } from "../../io.ts"; -/** Synchronously seek a file ID to the given offset under mode given by `whence`. - * - * Returns the number of cursor position. - * - * const file = Deno.openSync("/foo/bar.txt"); - * const position = Deno.seekSync(file.rid, 0, 0); - */ export function seekSync( rid: number, offset: number, @@ -17,13 +10,6 @@ export function seekSync( return sendSync("op_seek", { rid, offset, whence }); } -/** Seek a file ID to the given offset under mode given by `whence`. - * - * Resolves with the number of cursor position. - * - * const file = await Deno.open("/foo/bar.txt"); - * const position = await Deno.seek(file.rid, 0, 0); - */ export async function seek( rid: number, offset: number, diff --git a/cli/js/ops/fs/stat.ts b/cli/js/ops/fs/stat.ts index 6a764a8bb6..032cc97ee2 100644 --- a/cli/js/ops/fs/stat.ts +++ b/cli/js/ops/fs/stat.ts @@ -2,7 +2,6 @@ import { sendSync, sendAsync } from "../dispatch_json.ts"; import { FileInfo, FileInfoImpl } from "../../file_info.ts"; -/** @internal */ export interface StatResponse { isFile: boolean; isSymlink: boolean; @@ -23,13 +22,6 @@ export interface StatResponse { blocks: number; } -/** Resolves to a `Deno.FileInfo` for the specified `path`. If `path` is a - * symlink, information for the symlink will be returned. - * - * const fileInfo = await Deno.lstat("hello.txt"); - * assert(fileInfo.isFile()); - * - * Requires `allow-read` permission. */ export async function lstat(path: string): Promise { const res = (await sendAsync("op_stat", { path, @@ -38,13 +30,6 @@ export async function lstat(path: string): Promise { return new FileInfoImpl(res); } -/** Synchronously returns a `Deno.FileInfo` for the specified `path`. If - * `path` is a symlink, information for the symlink will be returned. - * - * const fileInfo = Deno.lstatSync("hello.txt"); - * assert(fileInfo.isFile()); - * - * Requires `allow-read` permission. */ export function lstatSync(path: string): FileInfo { const res = sendSync("op_stat", { path, @@ -53,13 +38,6 @@ export function lstatSync(path: string): FileInfo { return new FileInfoImpl(res); } -/** Resolves to a `Deno.FileInfo` for the specified `path`. Will always - * follow symlinks. - * - * const fileInfo = await Deno.stat("hello.txt"); - * assert(fileInfo.isFile()); - * - * Requires `allow-read` permission. */ export async function stat(path: string): Promise { const res = (await sendAsync("op_stat", { path, @@ -68,13 +46,6 @@ export async function stat(path: string): Promise { return new FileInfoImpl(res); } -/** Synchronously returns a `Deno.FileInfo` for the specified `path`. Will - * always follow symlinks. - * - * const fileInfo = Deno.statSync("hello.txt"); - * assert(fileInfo.isFile()); - * - * Requires `allow-read` permission. */ export function statSync(path: string): FileInfo { const res = sendSync("op_stat", { path, diff --git a/cli/js/ops/fs/symlink.ts b/cli/js/ops/fs/symlink.ts index 3bb7c3335a..ad49bfdd79 100644 --- a/cli/js/ops/fs/symlink.ts +++ b/cli/js/ops/fs/symlink.ts @@ -3,15 +3,6 @@ import { sendSync, sendAsync } from "../dispatch_json.ts"; import * as util from "../../util.ts"; import { build } from "../../build.ts"; -/** **UNSTABLE**: `type` argument type may be changed to `"dir" | "file"`. - * - * Creates `newname` as a symbolic link to `oldname`. The type argument can be - * set to `dir` or `file`. Is only available on Windows and ignored on other - * platforms. - * - * Deno.symlinkSync("old/name", "new/name"); - * - * Requires `allow-read` and `allow-write` permissions. */ export function symlinkSync( oldname: string, newname: string, @@ -23,15 +14,6 @@ export function symlinkSync( sendSync("op_symlink", { oldname, newname }); } -/** **UNSTABLE**: `type` argument may be changed to "dir" | "file" - * - * Creates `newname` as a symbolic link to `oldname`. The type argument can be - * set to `dir` or `file`. Is only available on Windows and ignored on other - * platforms. - * - * await Deno.symlink("old/name", "new/name"); - * - * Requires `allow-read` and `allow-write` permissions. */ export async function symlink( oldname: string, newname: string, diff --git a/cli/js/ops/fs/truncate.ts b/cli/js/ops/fs/truncate.ts index 578e37aa36..861e843f86 100644 --- a/cli/js/ops/fs/truncate.ts +++ b/cli/js/ops/fs/truncate.ts @@ -13,21 +13,10 @@ function coerceLen(len?: number): number { return len; } -/** Synchronously truncates or extends the specified file, to reach the - * specified `len`. - * - * Deno.truncateSync("hello.txt", 10); - * - * Requires `allow-write` permission. */ export function truncateSync(path: string, len?: number): void { sendSync("op_truncate", { path, len: coerceLen(len) }); } -/** Truncates or extends the specified file, to reach the specified `len`. - * - * await Deno.truncate("hello.txt", 10); - * - * Requires `allow-write` permission. */ export async function truncate(path: string, len?: number): Promise { await sendAsync("op_truncate", { path, len: coerceLen(len) }); } diff --git a/cli/js/ops/fs/umask.ts b/cli/js/ops/fs/umask.ts index ee56fecb56..38bf8ff6c6 100644 --- a/cli/js/ops/fs/umask.ts +++ b/cli/js/ops/fs/umask.ts @@ -1,12 +1,6 @@ // Copyright 2018-2020 the Deno authors. All rights reserved. MIT license. import { sendSync } from "../dispatch_json.ts"; -/** - * **UNSTABLE**: maybe needs `allow-env` permissions. - * - * If `mask` is provided, sets the process umask. Always returns what the umask - * was before the call. - */ export function umask(mask?: number): number { return sendSync("op_umask", { mask }); } diff --git a/cli/js/ops/fs/utime.ts b/cli/js/ops/fs/utime.ts index f684ac80a0..13cac8cb63 100644 --- a/cli/js/ops/fs/utime.ts +++ b/cli/js/ops/fs/utime.ts @@ -5,15 +5,6 @@ function toSecondsFromEpoch(v: number | Date): number { return v instanceof Date ? v.valueOf() / 1000 : v; } -/** **UNSTABLE**: needs investigation into high precision time. - * - * Synchronously changes the access and modification times of a file system - * object referenced by `path`. Given times are either in seconds (UNIX epoch - * time) or as `Date` objects. - * - * Deno.utimeSync("myfile.txt", 1556495550, new Date()); - * - * Requires `allow-write` permission. */ export function utimeSync( path: string, atime: number | Date, @@ -27,15 +18,6 @@ export function utimeSync( }); } -/** **UNSTABLE**: needs investigation into high precision time. - * - * Changes the access and modification times of a file system object - * referenced by `path`. Given times are either in seconds (UNIX epoch time) - * or as `Date` objects. - * - * await Deno.utime("myfile.txt", 1556495550, new Date()); - * - * Requires `allow-write` permission. */ export async function utime( path: string, atime: number | Date, diff --git a/cli/js/ops/get_random_values.ts b/cli/js/ops/get_random_values.ts index 0e384c2593..1dc56b6987 100644 --- a/cli/js/ops/get_random_values.ts +++ b/cli/js/ops/get_random_values.ts @@ -2,12 +2,6 @@ import { sendSync } from "./dispatch_json.ts"; import { assert } from "../util.ts"; -/** Synchronously collects cryptographically secure random values. The - * underlying CSPRNG in use is Rust's `rand::rngs::ThreadRng`. - * - * const arr = new Uint8Array(32); - * crypto.getRandomValues(arr); - */ export function getRandomValues< T extends | Int8Array diff --git a/cli/js/ops/io.ts b/cli/js/ops/io.ts index 9f53707b7c..38963e3608 100644 --- a/cli/js/ops/io.ts +++ b/cli/js/ops/io.ts @@ -10,15 +10,6 @@ import { OPS_CACHE } from "../runtime.ts"; let OP_READ = -1; let OP_WRITE = -1; -/** Synchronously read from a file ID into an array buffer. - * - * Returns `number | EOF` for the operation. - * - * const file = Deno.openSync("/foo/bar.txt"); - * const buf = new Uint8Array(100); - * const nread = Deno.readSync(file.rid, buf); - * const text = new TextDecoder().decode(buf); - */ export function readSync(rid: number, p: Uint8Array): number | EOF { if (p.length == 0) { return 0; @@ -36,15 +27,6 @@ export function readSync(rid: number, p: Uint8Array): number | EOF { } } -/** Read from a resource ID into an array buffer. - * - * Resolves to the `number | EOF` for the operation. - * - * const file = await Deno.open("/foo/bar.txt"); - * const buf = new Uint8Array(100); - * const nread = await Deno.read(file.rid, buf); - * const text = new TextDecoder().decode(buf); - */ export async function read(rid: number, p: Uint8Array): Promise { if (p.length == 0) { return 0; @@ -62,15 +44,6 @@ export async function read(rid: number, p: Uint8Array): Promise { } } -/** Synchronously write to the resource ID the contents of the array buffer. - * - * Resolves to the number of bytes written. - * - * const encoder = new TextEncoder(); - * const data = encoder.encode("Hello world\n"); - * const file = Deno.openSync("/foo/bar.txt", {create: true, write: true}); - * Deno.writeSync(file.rid, data); - */ export function writeSync(rid: number, p: Uint8Array): number { if (OP_WRITE < 0) { OP_WRITE = OPS_CACHE["op_write"]; @@ -83,15 +56,6 @@ export function writeSync(rid: number, p: Uint8Array): number { } } -/** Write to the resource ID the contents of the array buffer. - * - * Resolves to the number of bytes written. - * - * const encoder = new TextEncoder(); - * const data = encoder.encode("Hello world\n"); - * const file = await Deno.open("/foo/bar.txt", {create: true, write: true}); - * await Deno.write(file.rid, data); - */ export async function write(rid: number, p: Uint8Array): Promise { if (OP_WRITE < 0) { OP_WRITE = OPS_CACHE["op_write"]; diff --git a/cli/js/ops/net.ts b/cli/js/ops/net.ts index a026189d27..a108e1c721 100644 --- a/cli/js/ops/net.ts +++ b/cli/js/ops/net.ts @@ -13,14 +13,6 @@ export enum ShutdownMode { ReadWrite // unused } -/** Shut down socket send and receive operations. - * - * Matches behavior of POSIX shutdown(3). - * - * const listener = Deno.listen({ port: 80 }); - * const conn = await listener.accept(); - * Deno.shutdown(conn.rid, Deno.ShutdownMode.Write); - */ export function shutdown(rid: number, how: ShutdownMode): void { sendSync("op_shutdown", { rid, how }); } diff --git a/cli/js/ops/os.ts b/cli/js/ops/os.ts index 5d30262837..d2fa4f2bbe 100644 --- a/cli/js/ops/os.ts +++ b/cli/js/ops/os.ts @@ -2,34 +2,18 @@ import { sendSync } from "./dispatch_json.ts"; import { errors } from "../errors.ts"; -/** Get the loadavg. - * Requires the `--allow-env` flag. - * - * console.log(Deno.loadavg()); - */ export function loadavg(): number[] { return sendSync("op_loadavg"); } -/** Get the hostname. - * Requires the `--allow-env` flag. - * - * console.log(Deno.hostname()); - */ export function hostname(): string { return sendSync("op_hostname"); } -/** Get OS release. - * Requires the `--allow-env` flag. - * - * console.log(Deno.osRelease()); - */ export function osRelease(): string { return sendSync("op_os_release"); } -/** Exit the Deno process with optional exit code. */ export function exit(code = 0): never { sendSync("op_exit", { code }); throw new Error("Code not reachable"); @@ -43,18 +27,6 @@ function getEnv(key: string): string | undefined { return sendSync("op_get_env", { key })[0]; } -/** Returns a snapshot of the environment variables at invocation. Mutating a - * property in the object will set that variable in the environment for - * the process. The environment object will only accept `string`s - * as values. - * - * console.log(Deno.env("SHELL")); - * const myEnv = Deno.env(); - * console.log(myEnv.SHELL); - * myEnv.TEST_VAR = "HELLO"; - * const newEnv = Deno.env(); - * console.log(myEnv.TEST_VAR == newEnv.TEST_VAR); - */ export function env(): { [index: string]: string }; export function env(key: string): string | undefined; export function env( @@ -90,122 +62,6 @@ type DirKind = | "tmp" | "video"; -/** - * Returns the user and platform specific directories. - * Requires the `--allow-env` flag. - * Returns null if there is no applicable directory or if any other error - * occurs. - * - * Argument values: "home", "cache", "config", "executable", "data", - * "data_local", "audio", "desktop", "document", "download", "font", "picture", - * "public", "template", "video" - * - * "cache" - * |Platform | Value | Example | - * | ------- | ----------------------------------- | ---------------------------- | - * | Linux | `$XDG_CACHE_HOME` or `$HOME`/.cache | /home/alice/.cache | - * | macOS | `$HOME`/Library/Caches | /Users/Alice/Library/Caches | - * | Windows | `{FOLDERID_LocalAppData}` | C:\Users\Alice\AppData\Local | - * - * "config" - * |Platform | Value | Example | - * | ------- | ------------------------------------- | -------------------------------- | - * | Linux | `$XDG_CONFIG_HOME` or `$HOME`/.config | /home/alice/.config | - * | macOS | `$HOME`/Library/Preferences | /Users/Alice/Library/Preferences | - * | Windows | `{FOLDERID_RoamingAppData}` | C:\Users\Alice\AppData\Roaming | - * - * "executable" - * |Platform | Value | Example | - * | ------- | --------------------------------------------------------------- | -----------------------| - * | Linux | `XDG_BIN_HOME` or `$XDG_DATA_HOME`/../bin or `$HOME`/.local/bin | /home/alice/.local/bin | - * | macOS | - | - | - * | Windows | - | - | - * - * "data" - * |Platform | Value | Example | - * | ------- | ---------------------------------------- | ---------------------------------------- | - * | Linux | `$XDG_DATA_HOME` or `$HOME`/.local/share | /home/alice/.local/share | - * | macOS | `$HOME`/Library/Application Support | /Users/Alice/Library/Application Support | - * | Windows | `{FOLDERID_RoamingAppData}` | C:\Users\Alice\AppData\Roaming | - * - * "data_local" - * |Platform | Value | Example | - * | ------- | ---------------------------------------- | ---------------------------------------- | - * | Linux | `$XDG_DATA_HOME` or `$HOME`/.local/share | /home/alice/.local/share | - * | macOS | `$HOME`/Library/Application Support | /Users/Alice/Library/Application Support | - * | Windows | `{FOLDERID_LocalAppData}` | C:\Users\Alice\AppData\Local | - * - * "audio" - * |Platform | Value | Example | - * | ------- | ------------------ | -------------------- | - * | Linux | `XDG_MUSIC_DIR` | /home/alice/Music | - * | macOS | `$HOME`/Music | /Users/Alice/Music | - * | Windows | `{FOLDERID_Music}` | C:\Users\Alice\Music | - * - * "desktop" - * |Platform | Value | Example | - * | ------- | -------------------- | ---------------------- | - * | Linux | `XDG_DESKTOP_DIR` | /home/alice/Desktop | - * | macOS | `$HOME`/Desktop | /Users/Alice/Desktop | - * | Windows | `{FOLDERID_Desktop}` | C:\Users\Alice\Desktop | - * - * "document" - * |Platform | Value | Example | - * | ------- | ---------------------- | ------------------------ | - * | Linux | `XDG_DOCUMENTS_DIR` | /home/alice/Documents | - * | macOS | `$HOME`/Documents | /Users/Alice/Documents | - * | Windows | `{FOLDERID_Documents}` | C:\Users\Alice\Documents | - * - * "download" - * |Platform | Value | Example | - * | ------- | ---------------------- | ------------------------ | - * | Linux | `XDG_DOWNLOAD_DIR` | /home/alice/Downloads | - * | macOS | `$HOME`/Downloads | /Users/Alice/Downloads | - * | Windows | `{FOLDERID_Downloads}` | C:\Users\Alice\Downloads | - * - * "font" - * |Platform | Value | Example | - * | ------- | ---------------------------------------------------- | ------------------------------ | - * | Linux | `$XDG_DATA_HOME`/fonts or `$HOME`/.local/share/fonts | /home/alice/.local/share/fonts | - * | macOS | `$HOME/Library/Fonts` | /Users/Alice/Library/Fonts | - * | Windows | – | – | - * - * "picture" - * |Platform | Value | Example | - * | ------- | --------------------- | ----------------------- | - * | Linux | `XDG_PICTURES_DIR` | /home/alice/Pictures | - * | macOS | `$HOME`/Pictures | /Users/Alice/Pictures | - * | Windows | `{FOLDERID_Pictures}` | C:\Users\Alice\Pictures | - * - * "public" - * |Platform | Value | Example | - * | ------- | --------------------- | ------------------- | - * | Linux | `XDG_PUBLICSHARE_DIR` | /home/alice/Public | - * | macOS | `$HOME`/Public | /Users/Alice/Public | - * | Windows | `{FOLDERID_Public}` | C:\Users\Public | - * - * "template" - * |Platform | Value | Example | - * | ------- | ---------------------- | ---------------------------------------------------------- | - * | Linux | `XDG_TEMPLATES_DIR` | /home/alice/Templates | - * | macOS | – | – | - * | Windows | `{FOLDERID_Templates}` | C:\Users\Alice\AppData\Roaming\Microsoft\Windows\Templates | - * - * "tmp" - * - * |Platform | Value | Example | - * | ------- | ---------------------- | ---------------------------------------------------------- | - * | Linux | `TMPDIR` | /tmp | - * | macOS | `TMPDIR` | /tmp | - * | Windows | `{TMP}` | C:\Users\Alice\AppData\Local\Temp | - * - * "video" - * |Platform | Value | Example | - * | ------- | ------------------- | --------------------- | - * | Linux | `XDG_VIDEOS_DIR` | /home/alice/Videos | - * | macOS | `$HOME`/Movies | /Users/Alice/Movies | - * | Windows | `{FOLDERID_Videos}` | C:\Users\Alice\Videos | - */ export function dir(kind: DirKind): string | null { try { return sendSync("op_get_dir", { kind }); @@ -217,10 +73,6 @@ export function dir(kind: DirKind): string | null { } } -/** - * Returns the path to the current deno executable. - * Requires the `--allow-env` flag. - */ export function execPath(): string { return sendSync("op_exec_path"); } diff --git a/cli/js/ops/process.ts b/cli/js/ops/process.ts index 31ce0b33ef..7644bf6e75 100644 --- a/cli/js/ops/process.ts +++ b/cli/js/ops/process.ts @@ -2,11 +2,6 @@ import { sendSync, sendAsync } from "./dispatch_json.ts"; import { assert } from "../util.ts"; -/** Send a signal to process under given PID. Unix only at this moment. - * If pid is negative, the signal will be sent to the process group identified - * by -pid. - * Requires the `--allow-run` flag. - */ export function kill(pid: number, signo: number): void { sendSync("op_kill", { pid, signo }); } diff --git a/cli/js/ops/resources.ts b/cli/js/ops/resources.ts index b04810989e..dacdaa6596 100644 --- a/cli/js/ops/resources.ts +++ b/cli/js/ops/resources.ts @@ -5,9 +5,6 @@ export interface ResourceMap { [rid: number]: string; } -/** Returns a map of open _file like_ resource ids along with their string - * representation. - */ export function resources(): ResourceMap { const res = sendSync("op_resources") as Array<[number, string]>; const resources: ResourceMap = {}; @@ -17,7 +14,6 @@ export function resources(): ResourceMap { return resources; } -/** Close the given resource ID. */ export function close(rid: number): void { sendSync("op_close", { rid }); } diff --git a/cli/js/ops/runtime.ts b/cli/js/ops/runtime.ts index 7538ce12f7..262e462319 100644 --- a/cli/js/ops/runtime.ts +++ b/cli/js/ops/runtime.ts @@ -43,25 +43,6 @@ export interface Metrics { bytesReceived: number; } -/** Receive metrics from the privileged side of Deno. - * - * > 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 │ - * └─────────────────────────┴────────┘ - */ export function metrics(): Metrics { return sendSync("op_metrics"); } diff --git a/cli/js/ops/tty.ts b/cli/js/ops/tty.ts index 2ad44d025e..2d56496231 100644 --- a/cli/js/ops/tty.ts +++ b/cli/js/ops/tty.ts @@ -1,11 +1,9 @@ import { sendSync } from "./dispatch_json.ts"; -/** Check if a given resource is TTY. */ export function isatty(rid: number): boolean { return sendSync("op_isatty", { rid }); } -/** Set TTY to be under raw mode or not. */ export function setRaw(rid: number, mode: boolean): void { sendSync("op_set_raw", { rid, diff --git a/cli/js/permissions.ts b/cli/js/permissions.ts index 8fad8b691a..097c5048aa 100644 --- a/cli/js/permissions.ts +++ b/cli/js/permissions.ts @@ -1,9 +1,6 @@ // Copyright 2018-2020 the Deno authors. All rights reserved. MIT license. import * as permissionsOps from "./ops/permissions.ts"; -/** Permissions as granted by the caller - * See: https://w3c.github.io/permissions/#permission-registry - */ export type PermissionName = | "read" | "write" @@ -14,7 +11,6 @@ export type PermissionName = | "hrtime"; // NOTE: Keep in sync with cli/permissions.rs -/** https://w3c.github.io/permissions/#status-of-a-permission */ export type PermissionState = "granted" | "denied" | "prompt"; interface RunPermissionDescriptor { @@ -37,7 +33,6 @@ interface PluginPermissionDescriptor { interface HrtimePermissionDescriptor { name: "hrtime"; } -/** See: https://w3c.github.io/permissions/#permission-descriptor */ type PermissionDescriptor = | RunPermissionDescriptor | ReadWritePermissionDescriptor @@ -46,41 +41,22 @@ type PermissionDescriptor = | PluginPermissionDescriptor | HrtimePermissionDescriptor; -/** https://w3c.github.io/permissions/#permissionstatus */ export class PermissionStatus { constructor(public state: PermissionState) {} // TODO(kt3k): implement onchange handler } export class Permissions { - /** Queries the permission. - * const status = await Deno.permissions.query({ name: "read", path: "/etc" }); - * if (status.state === "granted") { - * file = await Deno.readFile("/etc/passwd"); - * } - */ async query(desc: PermissionDescriptor): Promise { const state = permissionsOps.query(desc); return new PermissionStatus(state); } - /** Revokes the permission. - * const status = await Deno.permissions.revoke({ name: "run" }); - * assert(status.state !== "granted") - */ async revoke(desc: PermissionDescriptor): Promise { const state = permissionsOps.revoke(desc); return new PermissionStatus(state); } - /** Requests the permission. - * const status = await Deno.permissions.request({ name: "env" }); - * if (status.state === "granted") { - * console.log(Deno.homeDir()); - * } else { - * console.log("'env' permission is denied."); - * } - */ async request(desc: PermissionDescriptor): Promise { const state = permissionsOps.request(desc); return new PermissionStatus(state); diff --git a/cli/js/process.ts b/cli/js/process.ts index 7e17da5b66..9d0751eca2 100644 --- a/cli/js/process.ts +++ b/cli/js/process.ts @@ -5,17 +5,6 @@ import { ReadCloser, WriteCloser } from "./io.ts"; import { readAll } from "./buffer.ts"; import { kill, runStatus as runStatusOp, run as runOp } from "./ops/process.ts"; -/** How to handle subprocess stdio. - * - * "inherit" The default if unspecified. The child inherits from the - * corresponding parent descriptor. - * - * "piped" A new pipe should be arranged to connect the parent and child - * subprocesses. - * - * "null" This stream will be ignored. This is the equivalent of attaching the - * stream to /dev/null. - */ export type ProcessStdio = "inherit" | "piped" | "null"; // TODO Maybe extend VSCode's 'CommandOptions'? @@ -70,10 +59,6 @@ export class Process { return await runStatus(this.rid); } - /** Buffer the stdout and return it as Uint8Array after EOF. - * You must set stdout to "piped" when creating the process. - * This calls close() on stdout after its done. - */ async output(): Promise { if (!this.stdout) { throw new Error("Process.output: stdout is undefined"); @@ -85,10 +70,6 @@ export class Process { } } - /** Buffer the stderr and return it as Uint8Array after EOF. - * You must set stderr to "piped" when creating the process. - * This calls close() on stderr after its done. - */ async stderrOutput(): Promise { if (!this.stderr) { throw new Error("Process.stderrOutput: stderr is undefined"); @@ -126,19 +107,6 @@ interface RunResponse { stdoutRid: number | null; stderrRid: number | null; } -/** - * Spawns new subprocess. - * - * Subprocess uses same working directory as parent process unless `opt.cwd` - * is specified. - * - * Environmental variables for subprocess can be specified using `opt.env` - * mapping. - * - * By default subprocess inherits stdio of parent process. To change that - * `opt.stdout`, `opt.stderr` and `opt.stdin` can be specified independently - - * they can be set to either `ProcessStdio` or `rid` of open file. - */ export function run({ args, cwd = undefined, diff --git a/cli/js/read_file.ts b/cli/js/read_file.ts index 43372ca455..317401af5c 100644 --- a/cli/js/read_file.ts +++ b/cli/js/read_file.ts @@ -2,13 +2,6 @@ import { open, openSync } from "./files.ts"; import { readAll, readAllSync } from "./buffer.ts"; -/** Reads and returns the entire contents of a file. - * - * const decoder = new TextDecoder("utf-8"); - * const data = Deno.readFileSync("hello.txt"); - * console.log(decoder.decode(data)); - * - * Requires `allow-read` permission. */ export function readFileSync(path: string): Uint8Array { const file = openSync(path); const contents = readAllSync(file); @@ -16,13 +9,6 @@ export function readFileSync(path: string): Uint8Array { return contents; } -/** Reads and resolves to the entire contents of a file. - * - * const decoder = new TextDecoder("utf-8"); - * const data = await Deno.readFile("hello.txt"); - * console.log(decoder.decode(data)); - * - * Requires `allow-read` permission. */ export async function readFile(path: string): Promise { const file = await open(path); const contents = await readAll(file); diff --git a/cli/js/repl.ts b/cli/js/repl.ts index 581834cfd8..f1b0723c87 100644 --- a/cli/js/repl.ts +++ b/cli/js/repl.ts @@ -5,18 +5,10 @@ import { stringifyArgs } from "./web/console.ts"; import { startRepl, readline } from "./ops/repl.ts"; import { close } from "./ops/resources.ts"; -/** - * REPL logging. - * In favor of console.log to avoid unwanted indentation - */ function replLog(...args: unknown[]): void { core.print(stringifyArgs(args) + "\n"); } -/** - * REPL logging for errors. - * In favor of console.error to avoid unwanted indentation - */ function replError(...args: unknown[]): void { core.print(stringifyArgs(args) + "\n", true); } diff --git a/cli/js/runtime.ts b/cli/js/runtime.ts index 3f2340b400..db755d9547 100644 --- a/cli/js/runtime.ts +++ b/cli/js/runtime.ts @@ -29,11 +29,6 @@ export function initOps(): void { } } -/** - * This function bootstraps JS runtime, unfortunately some of runtime - * code depends on information like "os" and thus getting this information - * is required at startup. - */ export function start(source?: string): Start { initOps(); // First we send an empty `Start` message to let the privileged side know we diff --git a/cli/js/runtime_worker.ts b/cli/js/runtime_worker.ts index 3468e81099..bd051dbf25 100644 --- a/cli/js/runtime_worker.ts +++ b/cli/js/runtime_worker.ts @@ -88,12 +88,6 @@ export const workerRuntimeGlobalProperties = { workerMessageRecvCallback: nonEnumerable(workerMessageRecvCallback) }; -/** - * Main method to initialize worker runtime. - * - * It sets up global variables for DedicatedWorkerScope, - * and initializes ops. - */ export function bootstrapWorkerRuntime(name: string): void { if (hasBootstrapped) { throw new Error("Worker runtime already bootstrapped"); diff --git a/cli/js/signals.ts b/cli/js/signals.ts index 3295b9e806..28bc271c41 100644 --- a/cli/js/signals.ts +++ b/cli/js/signals.ts @@ -72,8 +72,6 @@ enum MacOSSignal { SIGUSR2 = 31 } -/** Signals numbers. This is platform dependent. - */ export const Signal: { [key: string]: number } = {}; export function setSignals(): void { @@ -84,31 +82,6 @@ export function setSignals(): void { } } -/** - * Returns the stream of the given signal number. You can use it as an async - * iterator. - * - * for await (const _ of Deno.signal(Deno.Signal.SIGTERM)) { - * console.log("got SIGTERM!"); - * } - * - * You can also use it as a promise. In this case you can only receive the - * first one. - * - * await Deno.signal(Deno.Signal.SIGTERM); - * console.log("SIGTERM received!") - * - * If you want to stop receiving the signals, you can use .dispose() method - * of the signal stream object. - * - * const sig = Deno.signal(Deno.Signal.SIGTERM); - * setTimeout(() => { sig.dispose(); }, 5000); - * for await (const _ of sig) { - * console.log("SIGTERM!") - * } - * - * The above for-await loop exits after 5 seconds when sig.dispose() is called. - */ export function signal(signo: number): SignalStream { if (build.os === "win") { throw new Error("not implemented!"); @@ -117,73 +90,45 @@ export function signal(signo: number): SignalStream { } export const signals = { - /** Returns the stream of SIGALRM signals. - * This method is the shorthand for Deno.signal(Deno.Signal.SIGALRM). */ alarm(): SignalStream { return signal(Signal.SIGALRM); }, - /** Returns the stream of SIGCHLD signals. - * This method is the shorthand for Deno.signal(Deno.Signal.SIGCHLD). */ child(): SignalStream { return signal(Signal.SIGCHLD); }, - /** Returns the stream of SIGHUP signals. - * This method is the shorthand for Deno.signal(Deno.Signal.SIGHUP). */ hungup(): SignalStream { return signal(Signal.SIGHUP); }, - /** Returns the stream of SIGINT signals. - * This method is the shorthand for Deno.signal(Deno.Signal.SIGINT). */ interrupt(): SignalStream { return signal(Signal.SIGINT); }, - /** Returns the stream of SIGIO signals. - * This method is the shorthand for Deno.signal(Deno.Signal.SIGIO). */ io(): SignalStream { return signal(Signal.SIGIO); }, - /** Returns the stream of SIGPIPE signals. - * This method is the shorthand for Deno.signal(Deno.Signal.SIGPIPE). */ pipe(): SignalStream { return signal(Signal.SIGPIPE); }, - /** Returns the stream of SIGQUIT signals. - * This method is the shorthand for Deno.signal(Deno.Signal.SIGQUIT). */ quit(): SignalStream { return signal(Signal.SIGQUIT); }, - /** Returns the stream of SIGTERM signals. - * This method is the shorthand for Deno.signal(Deno.Signal.SIGTERM). */ terminate(): SignalStream { return signal(Signal.SIGTERM); }, - /** Returns the stream of SIGUSR1 signals. - * This method is the shorthand for Deno.signal(Deno.Signal.SIGUSR1). */ userDefined1(): SignalStream { return signal(Signal.SIGUSR1); }, - /** Returns the stream of SIGUSR2 signals. - * This method is the shorthand for Deno.signal(Deno.Signal.SIGUSR2). */ userDefined2(): SignalStream { return signal(Signal.SIGUSR2); }, - /** Returns the stream of SIGWINCH signals. - * This method is the shorthand for Deno.signal(Deno.Signal.SIGWINCH). */ windowChange(): SignalStream { return signal(Signal.SIGWINCH); } }; -/** SignalStream represents the stream of signals, implements both - * AsyncIterator and PromiseLike */ export class SignalStream implements AsyncIterableIterator, PromiseLike { private rid: number; - /** The promise of polling the signal, - * resolves with false when it receives signal, - * Resolves with true when the signal stream is disposed. */ private pollingPromise: Promise = Promise.resolve(false); - /** The flag, which is true when the stream is disposed. */ private disposed = false; constructor(signo: number) { this.rid = bindSignal(signo).rid; diff --git a/cli/js/symbols.ts b/cli/js/symbols.ts index 9d8928cf2b..785b47357f 100644 --- a/cli/js/symbols.ts +++ b/cli/js/symbols.ts @@ -2,12 +2,7 @@ import { internalSymbol } from "./internals.ts"; import { customInspect } from "./web/console.ts"; -/** Special Deno related symbols. */ export const symbols = { - /** Symbol to access exposed internal Deno API */ internal: internalSymbol, - /** 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. - */ customInspect }; diff --git a/cli/js/tls.ts b/cli/js/tls.ts index d7d12ac35d..3ed70727da 100644 --- a/cli/js/tls.ts +++ b/cli/js/tls.ts @@ -11,9 +11,6 @@ interface ConnectTLSOptions { certFile?: string; } -/** - * Establishes a secure connection over TLS (transport layer security). - */ export async function connectTLS({ port, hostname = "127.0.0.1", @@ -44,19 +41,6 @@ export interface ListenTLSOptions { keyFile: string; } -/** Listen announces on the local transport address over TLS (transport layer security). - * - * @param options - * @param options.port The port to connect to. (Required.) - * @param options.hostname A literal IP address or host name that can be - * resolved to an IP address. If not specified, defaults to 0.0.0.0 - * @param options.certFile Server certificate file - * @param options.keyFile Server public key file - * - * Examples: - * - * Deno.listenTLS({ port: 443, certFile: "./my_server.crt", keyFile: "./my_server.key" }) - */ export function listenTLS({ port, certFile, diff --git a/cli/js/util.ts b/cli/js/util.ts index 3c67fa7f1b..ec39d6f35e 100644 --- a/cli/js/util.ts +++ b/cli/js/util.ts @@ -11,10 +11,6 @@ export function setLogDebug(debug: boolean, source?: string): void { } } -/** Debug logging for deno. - * Enable with the `--log-debug` or `-D` command line flag. - * @internal - */ export function log(...args: unknown[]): void { if (logDebug) { // if we destructure `console` off `globalThis` too early, we don't bind to @@ -30,25 +26,6 @@ export function assert(cond: unknown, msg = "assert"): asserts cond { } } -/** A `Resolvable` is a Promise with the `reject` and `resolve` functions - * placed as methods on the promise object itself. It allows you to do: - * - * const p = createResolvable(); - * // ... - * p.resolve(42); - * - * It'd be prettier to make `Resolvable` a class that inherits from `Promise`, - * rather than an interface. This is possible in ES2016, however typescript - * produces broken code when targeting ES5 code. - * - * At the time of writing, the GitHub issue is closed in favour of a proposed - * solution that is awaiting feedback. - * - * @see https://github.com/Microsoft/TypeScript/issues/15202 - * @see https://github.com/Microsoft/TypeScript/issues/15397 - * @internal - */ - export type ResolveFunction = (value?: T | PromiseLike) => void; // eslint-disable-next-line @typescript-eslint/no-explicit-any export type RejectFunction = (reason?: any) => void; diff --git a/cli/js/version.ts b/cli/js/version.ts index e1adb7e790..8f7851589e 100644 --- a/cli/js/version.ts +++ b/cli/js/version.ts @@ -11,10 +11,6 @@ export const version: Version = { typescript: "" }; -/** - * Sets the deno, v8, and typescript versions and freezes the version object. - * @internal - */ export function setVersions( denoVersion: string, v8Version: string, diff --git a/cli/js/web/blob.ts b/cli/js/web/blob.ts index 1309ddff0a..31674a62d5 100644 --- a/cli/js/web/blob.ts +++ b/cli/js/web/blob.ts @@ -133,7 +133,6 @@ export class DenoBlob implements domTypes.Blob { readonly size: number = 0; readonly type: string = ""; - /** A blob object represents a file-like object of immutable, raw data. */ constructor( blobParts?: domTypes.BlobPart[], options?: domTypes.BlobPropertyBag diff --git a/cli/js/web/console.ts b/cli/js/web/console.ts index 8a34d62a1e..7f79dd255d 100644 --- a/cli/js/web/console.ts +++ b/cli/js/web/console.ts @@ -363,7 +363,6 @@ function createObjectString( } } -/** @internal */ export function stringifyArgs( args: unknown[], { depth = DEFAULT_MAX_DEPTH, indentLevel = 0 }: ConsoleOptions = {} @@ -480,7 +479,6 @@ export class Console { indentLevel: number; [isConsoleInstance] = false; - /** @internal */ constructor(private printFunc: PrintFunc) { this.indentLevel = 0; this[isConsoleInstance] = true; @@ -494,7 +492,6 @@ export class Console { return console; } - /** Writes the arguments to stdout */ log = (...args: unknown[]): void => { this.printFunc( stringifyArgs(args, { @@ -504,29 +501,15 @@ export class Console { ); }; - /** Writes the arguments to stdout */ debug = this.log; - /** Writes the arguments to stdout */ info = this.log; - /** Writes the properties of the supplied `obj` to stdout */ dir = (obj: unknown, options: ConsoleOptions = {}): void => { this.printFunc(stringifyArgs([obj], options) + "\n", false); }; - /** From MDN: - * Displays an interactive tree of the descendant elements of - * the specified XML/HTML element. If it is not possible to display - * as an element the JavaScript Object view is shown instead. - * The output is presented as a hierarchical listing of expandable - * nodes that let you see the contents of child nodes. - * - * Since we write to stdout, we can't display anything interactive - * we just fall back to `console.dir`. - */ dirxml = this.dir; - /** Writes the arguments to stdout */ warn = (...args: unknown[]): void => { this.printFunc( stringifyArgs(args, { @@ -536,14 +519,8 @@ export class Console { ); }; - /** Writes the arguments to stdout */ error = this.warn; - /** Writes an error message to stdout if the assertion is `false`. If the - * assertion is `true`, nothing happens. - * - * ref: https://console.spec.whatwg.org/#assert - */ assert = (condition = false, ...args: unknown[]): void => { if (condition) { return; @@ -750,15 +727,8 @@ export class Console { } } -/** 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. - */ export const customInspect = Symbol.for("Deno.customInspect"); -/** - * `inspect()` converts input into string that has the same format - * as printed by `console.log(...)`; - */ export function inspect( value: unknown, { depth = DEFAULT_MAX_DEPTH }: ConsoleOptions = {} diff --git a/cli/js/web/custom_event.ts b/cli/js/web/custom_event.ts index 2d94df56de..24a263baf8 100644 --- a/cli/js/web/custom_event.ts +++ b/cli/js/web/custom_event.ts @@ -42,7 +42,4 @@ export class CustomEvent extends event.Event implements domTypes.CustomEvent { } } -/** Built-in objects providing `get` methods for our - * interceptable JavaScript operations. - */ Reflect.defineProperty(CustomEvent.prototype, "detail", { enumerable: true }); diff --git a/cli/js/web/dom_iterable.ts b/cli/js/web/dom_iterable.ts index f365d555f1..e9be9009fb 100644 --- a/cli/js/web/dom_iterable.ts +++ b/cli/js/web/dom_iterable.ts @@ -7,10 +7,6 @@ import { exposeForTest } from "../internals.ts"; // eslint-disable-next-line @typescript-eslint/no-explicit-any type Constructor = new (...args: any[]) => T; -/** Mixes in a DOM iterable methods into a base class, assumes that there is - * a private data iterable that is part of the base class, located at - * `[dataSymbol]`. - */ export function DomIterableMixin( Base: TBase, dataSymbol: symbol diff --git a/cli/js/web/dom_types.ts b/cli/js/web/dom_types.ts index 23347ce66d..bcc6be4684 100644 --- a/cli/js/web/dom_types.ts +++ b/cli/js/web/dom_types.ts @@ -125,46 +125,14 @@ export interface ProgressEventInit extends EventInit { } export interface URLSearchParams extends DomIterable { - /** - * Appends a specified key/value pair as a new search parameter. - */ append(name: string, value: string): void; - /** - * Deletes the given search parameter, and its associated value, - * from the list of all search parameters. - */ delete(name: string): void; - /** - * Returns the first value associated to the given search parameter. - */ get(name: string): string | null; - /** - * Returns all the values association with a given search parameter. - */ getAll(name: string): string[]; - /** - * Returns a Boolean indicating if such a search parameter exists. - */ has(name: string): boolean; - /** - * Sets the value associated to a given search parameter to the given value. - * If there were several values, delete the others. - */ set(name: string, value: string): void; - /** - * Sort all key/value pairs contained in this object in place - * and return undefined. The sort order is according to Unicode - * code points of the keys. - */ sort(): void; - /** - * Returns a query string suitable for use in a URL. - */ toString(): string; - /** - * Iterates over each name-value pair in the query - * and invokes the given function. - */ forEach( callbackfn: (value: string, key: string, parent: this) => void, thisArg?: any @@ -305,46 +273,19 @@ export interface FormDataConstructor { prototype: FormData; } -/** A blob object represents a file-like object of immutable, raw data. */ export interface Blob { - /** The size, in bytes, of the data contained in the `Blob` object. */ readonly size: number; - /** A string indicating the media type of the data contained in the `Blob`. - * If the type is unknown, this string is empty. - */ readonly type: string; - /** Returns a new `Blob` object containing the data in the specified range of - * bytes of the source `Blob`. - */ slice(start?: number, end?: number, contentType?: string): Blob; } export interface Body { - /** A simple getter used to expose a `ReadableStream` of the body contents. */ readonly body: ReadableStream | null; - /** Stores a `Boolean` that declares whether the body has been used in a - * response yet. - */ readonly bodyUsed: boolean; - /** Takes a `Response` stream and reads it to completion. It returns a promise - * that resolves with an `ArrayBuffer`. - */ arrayBuffer(): Promise; - /** Takes a `Response` stream and reads it to completion. It returns a promise - * that resolves with a `Blob`. - */ blob(): Promise; - /** Takes a `Response` stream and reads it to completion. It returns a promise - * that resolves with a `FormData` object. - */ formData(): Promise; - /** Takes a `Response` stream and reads it to completion. It returns a promise - * that resolves with the result of parsing the body text as JSON. - */ json(): Promise; - /** Takes a `Response` stream and reads it to completion. It returns a promise - * that resolves with a `USVString` (text). - */ text(): Promise; } @@ -474,44 +415,18 @@ export interface QueuingStrategySizeCallback { } export interface Headers extends DomIterable { - /** Appends a new value onto an existing header inside a `Headers` object, or - * adds the header if it does not already exist. - */ append(name: string, value: string): void; - /** Deletes a header from a `Headers` object. */ delete(name: string): void; - /** Returns an iterator allowing to go through all key/value pairs - * contained in this Headers object. The both the key and value of each pairs - * are ByteString objects. - */ entries(): IterableIterator<[string, string]>; - /** Returns a `ByteString` sequence of all the values of a header within a - * `Headers` object with a given name. - */ get(name: string): string | null; - /** Returns a boolean stating whether a `Headers` object contains a certain - * header. - */ has(name: string): boolean; - /** Returns an iterator allowing to go through all keys contained in - * this Headers object. The keys are ByteString objects. - */ keys(): IterableIterator; - /** Sets a new value for an existing header inside a Headers object, or adds - * the header if it does not already exist. - */ set(name: string, value: string): void; - /** Returns an iterator allowing to go through all values contained in - * this Headers object. The values are ByteString objects. - */ values(): IterableIterator; forEach( callbackfn: (value: string, key: string, parent: this) => void, thisArg?: any ): void; - /** The Symbol.iterator well-known symbol specifies the default - * iterator for this Headers object - */ [Symbol.iterator](): IterableIterator<[string, string]>; } @@ -585,171 +500,49 @@ export interface RequestConstructor { } export interface Request extends Body { - /** Returns the cache mode associated with request, which is a string - * indicating how the the request will interact with the browser's cache when - * fetching. - */ readonly cache?: RequestCache; - /** Returns the credentials mode associated with request, which is a string - * indicating whether credentials will be sent with the request always, never, - * or only when sent to a same-origin URL. - */ readonly credentials?: RequestCredentials; - /** Returns the kind of resource requested by request, (e.g., `document` or - * `script`). - */ readonly destination?: RequestDestination; - /** Returns a Headers object consisting of the headers associated with - * request. - * - * Note that headers added in the network layer by the user agent - * will not be accounted for in this object, (e.g., the `Host` header). - */ readonly headers: Headers; - /** Returns request's subresource integrity metadata, which is a cryptographic - * hash of the resource being fetched. Its value consists of multiple hashes - * separated by whitespace. [SRI] - */ readonly integrity?: string; - /** Returns a boolean indicating whether or not request is for a history - * navigation (a.k.a. back-forward navigation). - */ readonly isHistoryNavigation?: boolean; - /** Returns a boolean indicating whether or not request is for a reload - * navigation. - */ readonly isReloadNavigation?: boolean; - /** Returns a boolean indicating whether or not request can outlive the global - * in which it was created. - */ readonly keepalive?: boolean; - /** Returns request's HTTP method, which is `GET` by default. */ readonly method: string; - /** Returns the mode associated with request, which is a string indicating - * whether the request will use CORS, or will be restricted to same-origin - * URLs. - */ readonly mode?: RequestMode; - /** Returns the redirect mode associated with request, which is a string - * indicating how redirects for the request will be handled during fetching. - * - * A request will follow redirects by default. - */ readonly redirect?: RequestRedirect; - /** Returns the referrer of request. Its value can be a same-origin URL if - * explicitly set in init, the empty string to indicate no referrer, and - * `about:client` when defaulting to the global's default. - * - * This is used during fetching to determine the value of the `Referer` - * header of the request being made. - */ readonly referrer?: string; - /** Returns the referrer policy associated with request. This is used during - * fetching to compute the value of the request's referrer. - */ readonly referrerPolicy?: ReferrerPolicy; - /** Returns the signal associated with request, which is an AbortSignal object - * indicating whether or not request has been aborted, and its abort event - * handler. - */ readonly signal?: AbortSignal; - /** Returns the URL of request as a string. */ readonly url: string; clone(): Request; } export interface Response extends Body { - /** Contains the `Headers` object associated with the response. */ readonly headers: Headers; - /** Contains a boolean stating whether the response was successful (status in - * the range 200-299) or not. - */ readonly ok: boolean; - /** Indicates whether or not the response is the result of a redirect; that - * is, its URL list has more than one entry. - */ readonly redirected: boolean; - /** Contains the status code of the response (e.g., `200` for a success). */ readonly status: number; - /** Contains the status message corresponding to the status code (e.g., `OK` - * for `200`). - */ readonly statusText: string; readonly trailer: Promise; - /** Contains the type of the response (e.g., `basic`, `cors`). */ readonly type: ResponseType; - /** Contains the URL of the response. */ readonly url: string; - /** Creates a clone of a `Response` object. */ clone(): Response; } export interface Location { - /** - * Returns a DOMStringList object listing the origins of the ancestor browsing - * contexts, from the parent browsing context to the top-level browsing - * context. - */ readonly ancestorOrigins: string[]; - /** - * Returns the Location object's URL's fragment (includes leading "#" if - * non-empty). - * Can be set, to navigate to the same URL with a changed fragment (ignores - * leading "#"). - */ hash: string; - /** - * Returns the Location object's URL's host and port (if different from the - * default port for the scheme). Can be set, to navigate to the same URL with - * a changed host and port. - */ host: string; - /** - * Returns the Location object's URL's host. Can be set, to navigate to the - * same URL with a changed host. - */ hostname: string; - /** - * Returns the Location object's URL. Can be set, to navigate to the given - * URL. - */ href: string; - /** Returns the Location object's URL's origin. */ readonly origin: string; - /** - * Returns the Location object's URL's path. - * Can be set, to navigate to the same URL with a changed path. - */ pathname: string; - /** - * Returns the Location object's URL's port. - * Can be set, to navigate to the same URL with a changed port. - */ port: string; - /** - * Returns the Location object's URL's scheme. - * Can be set, to navigate to the same URL with a changed scheme. - */ protocol: string; - /** - * Returns the Location object's URL's query (includes leading "?" if - * non-empty). Can be set, to navigate to the same URL with a changed query - * (ignores leading "?"). - */ search: string; - /** - * Navigates to the given URL. - */ assign(url: string): void; - /** - * Reloads the current page. - */ reload(): void; - /** @deprecated */ reload(forcedReload: boolean): void; - /** - * Removes the current page from the session history and navigates to the - * given URL. - */ replace(url: string): void; } diff --git a/cli/js/web/event.ts b/cli/js/web/event.ts index a30e334470..ef5c4d1755 100644 --- a/cli/js/web/event.ts +++ b/cli/js/web/event.ts @@ -187,12 +187,6 @@ export class Event implements domTypes.Event { return getPrivateValue(this, eventAttributes, "type"); } - /** Returns the event’s path (objects on which listeners will be - * invoked). This does not include nodes in shadow trees if the - * shadow root was created with its ShadowRoot.mode closed. - * - * event.composedPath(); - */ composedPath(): domTypes.EventPath[] { if (this._path.length === 0) { return []; @@ -299,41 +293,22 @@ export class Event implements domTypes.Event { return composedPath; } - /** Cancels the event (if it is cancelable). - * See https://dom.spec.whatwg.org/#set-the-canceled-flag - * - * event.preventDefault(); - */ preventDefault(): void { if (this.cancelable && !this._inPassiveListenerFlag) { this._canceledFlag = true; } } - /** Stops the propagation of events further along in the DOM. - * - * event.stopPropagation(); - */ stopPropagation(): void { this._stopPropagationFlag = true; } - /** For this particular event, no other listener will be called. - * Neither those attached on the same element, nor those attached - * on elements which will be traversed later (in capture phase, - * for instance). - * - * event.stopImmediatePropagation(); - */ stopImmediatePropagation(): void { this._stopPropagationFlag = true; this._stopImmediatePropagationFlag = true; } } -/** Built-in objects providing `get` methods for our - * interceptable JavaScript operations. - */ Reflect.defineProperty(Event.prototype, "bubbles", { enumerable: true }); Reflect.defineProperty(Event.prototype, "cancelable", { enumerable: true }); Reflect.defineProperty(Event.prototype, "composed", { enumerable: true }); diff --git a/cli/js/web/event_target.ts b/cli/js/web/event_target.ts index 03557526a3..7fe26441d0 100644 --- a/cli/js/web/event_target.ts +++ b/cli/js/web/event_target.ts @@ -486,9 +486,6 @@ const eventTargetHelpers = { } }; -/** Built-in objects providing `get` methods for our - * interceptable JavaScript operations. - */ Reflect.defineProperty(EventTarget.prototype, "addEventListener", { enumerable: true }); diff --git a/cli/js/web/fetch.ts b/cli/js/web/fetch.ts index daa926e516..3972da4f29 100644 --- a/cli/js/web/fetch.ts +++ b/cli/js/web/fetch.ts @@ -456,7 +456,6 @@ async function sendFetchReq( return await opFetch(args, body); } -/** Fetch a resource from the network. */ export async function fetch( input: domTypes.Request | URL | string, init?: domTypes.RequestInit diff --git a/cli/js/web/form_data.ts b/cli/js/web/form_data.ts index 461210b9d4..2c70d416f3 100644 --- a/cli/js/web/form_data.ts +++ b/cli/js/web/form_data.ts @@ -10,12 +10,6 @@ const dataSymbol = Symbol("data"); class FormDataBase { private [dataSymbol]: Array<[string, domTypes.FormDataEntryValue]> = []; - /** Appends a new value onto an existing key inside a `FormData` - * object, or adds the key if it does not already exist. - * - * formData.append('name', 'first'); - * formData.append('name', 'second'); - */ append(name: string, value: string): void; append(name: string, value: blob.DenoBlob, filename?: string): void; append(name: string, value: string | blob.DenoBlob, filename?: string): void { @@ -29,10 +23,6 @@ class FormDataBase { } } - /** Deletes a key/value pair from a `FormData` object. - * - * formData.delete('name'); - */ delete(name: string): void { requiredArguments("FormData.delete", arguments.length, 1); name = String(name); @@ -46,11 +36,6 @@ class FormDataBase { } } - /** Returns an array of all the values associated with a given key - * from within a `FormData`. - * - * formData.getAll('name'); - */ getAll(name: string): domTypes.FormDataEntryValue[] { requiredArguments("FormData.getAll", arguments.length, 1); name = String(name); @@ -64,11 +49,6 @@ class FormDataBase { return values; } - /** Returns the first value associated with a given key from within a - * `FormData` object. - * - * formData.get('name'); - */ get(name: string): domTypes.FormDataEntryValue | null { requiredArguments("FormData.get", arguments.length, 1); name = String(name); @@ -81,23 +61,12 @@ class FormDataBase { return null; } - /** Returns a boolean stating whether a `FormData` object contains a - * certain key/value pair. - * - * formData.has('name'); - */ has(name: string): boolean { requiredArguments("FormData.has", arguments.length, 1); name = String(name); return this[dataSymbol].some((entry): boolean => entry[0] === name); } - /** Sets a new value for an existing key inside a `FormData` object, or - * adds the key/value if it does not already exist. - * ref: https://xhr.spec.whatwg.org/#dom-formdata-set - * - * formData.set('name', 'value'); - */ set(name: string, value: string): void; set(name: string, value: blob.DenoBlob, filename?: string): void; set(name: string, value: string | blob.DenoBlob, filename?: string): void { diff --git a/cli/js/web/performance.ts b/cli/js/web/performance.ts index cb4daa8463..7077b1edb1 100644 --- a/cli/js/web/performance.ts +++ b/cli/js/web/performance.ts @@ -2,13 +2,6 @@ import { now as opNow } from "../ops/timers.ts"; export class Performance { - /** Returns a current time from Deno's start in milliseconds. - * - * Use the flag --allow-hrtime return a precise value. - * - * const t = performance.now(); - * console.log(`${t} ms since start!`); - */ now(): number { const res = opNow(); return res.seconds * 1e3 + res.subsecNanos / 1e6; diff --git a/cli/js/web/request.ts b/cli/js/web/request.ts index 1416a95d61..8afc35e7a2 100644 --- a/cli/js/web/request.ts +++ b/cli/js/web/request.ts @@ -28,11 +28,6 @@ function normalizeMethod(m: string): string { return m; } -/** - * An HTTP request - * @param {Blob|String} [body] - * @param {Object} [init] - */ export class Request extends body.Body implements domTypes.Request { public method: string; public url: string; @@ -83,20 +78,9 @@ export class Request extends body.Body implements domTypes.Request { this.headers = headers; // readonly attribute ByteString method; - /** - * The HTTP request method - * @readonly - * @default GET - * @type {string} - */ this.method = "GET"; // readonly attribute USVString url; - /** - * The request URL - * @readonly - * @type {string} - */ this.url = ""; // readonly attribute RequestCredentials credentials; diff --git a/cli/js/web/streams/mod.ts b/cli/js/web/streams/mod.ts index 5389aaf6d9..a6b55ed5aa 100644 --- a/cli/js/web/streams/mod.ts +++ b/cli/js/web/streams/mod.ts @@ -1,13 +1,6 @@ // Forked from https://github.com/stardazed/sd-streams/tree/8928cf04b035fd02fb1340b7eb541c76be37e546 // Copyright (c) 2018-Present by Arthur Langereis - @zenmumbler MIT -/** - * @stardazed/streams - implementation of the web streams standard - * Part of Stardazed - * (c) 2018-Present by Arthur Langereis - @zenmumbler - * https://github.com/stardazed/sd-streams - */ - export { SDReadableStream as ReadableStream } from "./readable-stream.ts"; /* TODO The following are currently unused so not exported for clarity. export { WritableStream } from "./writable-stream.ts"; diff --git a/cli/js/web/streams/queue-mixin.ts b/cli/js/web/streams/queue-mixin.ts index 23c57d75ff..a7ed149747 100644 --- a/cli/js/web/streams/queue-mixin.ts +++ b/cli/js/web/streams/queue-mixin.ts @@ -1,13 +1,6 @@ // Forked from https://github.com/stardazed/sd-streams/tree/8928cf04b035fd02fb1340b7eb541c76be37e546 // Copyright (c) 2018-Present by Arthur Langereis - @zenmumbler MIT -/** - * streams/queue-mixin - internal queue operations for stream controllers - * Part of Stardazed - * (c) 2018-Present by Arthur Langereis - @zenmumbler - * https://github.com/stardazed/sd-streams - */ - /* eslint-disable @typescript-eslint/no-explicit-any */ // TODO reenable this lint here diff --git a/cli/js/web/streams/queue.ts b/cli/js/web/streams/queue.ts index 264851baf4..16e3eafe4b 100644 --- a/cli/js/web/streams/queue.ts +++ b/cli/js/web/streams/queue.ts @@ -1,13 +1,6 @@ // Forked from https://github.com/stardazed/sd-streams/tree/8928cf04b035fd02fb1340b7eb541c76be37e546 // Copyright (c) 2018-Present by Arthur Langereis - @zenmumbler MIT -/** - * streams/queue - simple queue type with chunked array backing - * Part of Stardazed - * (c) 2018-Present by Arthur Langereis - @zenmumbler - * https://github.com/stardazed/sd-streams - */ - const CHUNK_SIZE = 16384; export interface Queue { diff --git a/cli/js/web/streams/readable-byte-stream-controller.ts b/cli/js/web/streams/readable-byte-stream-controller.ts index 86efd416c2..8067b5d35e 100644 --- a/cli/js/web/streams/readable-byte-stream-controller.ts +++ b/cli/js/web/streams/readable-byte-stream-controller.ts @@ -1,13 +1,6 @@ // Forked from https://github.com/stardazed/sd-streams/tree/8928cf04b035fd02fb1340b7eb541c76be37e546 // Copyright (c) 2018-Present by Arthur Langereis - @zenmumbler MIT -/** - * streams/readable-byte-stream-controller - ReadableByteStreamController class implementation - * Part of Stardazed - * (c) 2018-Present by Arthur Langereis - @zenmumbler - * https://github.com/stardazed/sd-streams - */ - /* eslint-disable @typescript-eslint/no-explicit-any */ // TODO reenable this lint here diff --git a/cli/js/web/streams/readable-internals.ts b/cli/js/web/streams/readable-internals.ts index 67f5a69b1d..b96262ef75 100644 --- a/cli/js/web/streams/readable-internals.ts +++ b/cli/js/web/streams/readable-internals.ts @@ -1,13 +1,6 @@ // Forked from https://github.com/stardazed/sd-streams/tree/8928cf04b035fd02fb1340b7eb541c76be37e546 // Copyright (c) 2018-Present by Arthur Langereis - @zenmumbler MIT -/** - * streams/readable-internals - internal types and functions for readable streams - * Part of Stardazed - * (c) 2018-Present by Arthur Langereis - @zenmumbler - * https://github.com/stardazed/sd-streams - */ - /* eslint-disable @typescript-eslint/no-explicit-any */ // TODO reenable this lint here diff --git a/cli/js/web/streams/readable-stream-byob-reader.ts b/cli/js/web/streams/readable-stream-byob-reader.ts index 0f9bfb0378..8527f8db94 100644 --- a/cli/js/web/streams/readable-stream-byob-reader.ts +++ b/cli/js/web/streams/readable-stream-byob-reader.ts @@ -1,13 +1,6 @@ // Forked from https://github.com/stardazed/sd-streams/tree/8928cf04b035fd02fb1340b7eb541c76be37e546 // Copyright (c) 2018-Present by Arthur Langereis - @zenmumbler MIT -/** - * streams/readable-stream-byob-reader - ReadableStreamBYOBReader class implementation - * Part of Stardazed - * (c) 2018-Present by Arthur Langereis - @zenmumbler - * https://github.com/stardazed/sd-streams - */ - import * as rs from "./readable-internals.ts"; import * as shared from "./shared-internals.ts"; diff --git a/cli/js/web/streams/readable-stream-byob-request.ts b/cli/js/web/streams/readable-stream-byob-request.ts index 25b937f108..75ca1ddfe2 100644 --- a/cli/js/web/streams/readable-stream-byob-request.ts +++ b/cli/js/web/streams/readable-stream-byob-request.ts @@ -1,13 +1,6 @@ // Forked from https://github.com/stardazed/sd-streams/tree/8928cf04b035fd02fb1340b7eb541c76be37e546 // Copyright (c) 2018-Present by Arthur Langereis - @zenmumbler MIT -/** - * streams/readable-stream-byob-request - ReadableStreamBYOBRequest class implementation - * Part of Stardazed - * (c) 2018-Present by Arthur Langereis - @zenmumbler - * https://github.com/stardazed/sd-streams - */ - import * as rs from "./readable-internals.ts"; export class ReadableStreamBYOBRequest { diff --git a/cli/js/web/streams/readable-stream-default-controller.ts b/cli/js/web/streams/readable-stream-default-controller.ts index e9ddce1bcb..d33226a9bd 100644 --- a/cli/js/web/streams/readable-stream-default-controller.ts +++ b/cli/js/web/streams/readable-stream-default-controller.ts @@ -1,13 +1,6 @@ // Forked from https://github.com/stardazed/sd-streams/tree/8928cf04b035fd02fb1340b7eb541c76be37e546 // Copyright (c) 2018-Present by Arthur Langereis - @zenmumbler MIT -/** - * streams/readable-stream-default-controller - ReadableStreamDefaultController class implementation - * Part of Stardazed - * (c) 2018-Present by Arthur Langereis - @zenmumbler - * https://github.com/stardazed/sd-streams - */ - /* eslint-disable @typescript-eslint/no-explicit-any */ // TODO reenable this lint here diff --git a/cli/js/web/streams/readable-stream-default-reader.ts b/cli/js/web/streams/readable-stream-default-reader.ts index eb1910a9d5..3fbf22c8cd 100644 --- a/cli/js/web/streams/readable-stream-default-reader.ts +++ b/cli/js/web/streams/readable-stream-default-reader.ts @@ -1,13 +1,6 @@ // Forked from https://github.com/stardazed/sd-streams/tree/8928cf04b035fd02fb1340b7eb541c76be37e546 // Copyright (c) 2018-Present by Arthur Langereis - @zenmumbler MIT -/** - * streams/readable-stream-default-reader - ReadableStreamDefaultReader class implementation - * Part of Stardazed - * (c) 2018-Present by Arthur Langereis - @zenmumbler - * https://github.com/stardazed/sd-streams - */ - import * as rs from "./readable-internals.ts"; import * as shared from "./shared-internals.ts"; diff --git a/cli/js/web/streams/readable-stream.ts b/cli/js/web/streams/readable-stream.ts index 4d9d858897..e062c278e2 100644 --- a/cli/js/web/streams/readable-stream.ts +++ b/cli/js/web/streams/readable-stream.ts @@ -1,13 +1,6 @@ // Forked from https://github.com/stardazed/sd-streams/tree/8928cf04b035fd02fb1340b7eb541c76be37e546 // Copyright (c) 2018-Present by Arthur Langereis - @zenmumbler MIT -/** - * streams/readable-stream - ReadableStream class implementation - * Part of Stardazed - * (c) 2018-Present by Arthur Langereis - @zenmumbler - * https://github.com/stardazed/sd-streams - */ - /* eslint prefer-const: "off" */ // TODO remove this, surpressed because of // 284:7 error 'branch1' is never reassigned. Use 'const' instead prefer-const diff --git a/cli/js/web/streams/shared-internals.ts b/cli/js/web/streams/shared-internals.ts index 93155fecc0..3d802b083f 100644 --- a/cli/js/web/streams/shared-internals.ts +++ b/cli/js/web/streams/shared-internals.ts @@ -1,13 +1,6 @@ // Forked from https://github.com/stardazed/sd-streams/tree/8928cf04b035fd02fb1340b7eb541c76be37e546 // Copyright (c) 2018-Present by Arthur Langereis - @zenmumbler MIT -/** - * streams/shared-internals - common types and methods for streams - * Part of Stardazed - * (c) 2018-Present by Arthur Langereis - @zenmumbler - * https://github.com/stardazed/sd-streams - */ - /* eslint-disable @typescript-eslint/no-explicit-any */ // TODO don't disable this warning @@ -20,7 +13,6 @@ export const storedError_ = Symbol("storedError_"); // --------- -/** An error reason / result can be anything */ export type ErrorResult = any; // --------- @@ -122,11 +114,6 @@ function supportsSharedArrayBuffer(): boolean { return sharedArrayBufferSupported_; } -/** - * Implement a method of value cloning that is reasonably close to performing `StructuredSerialize(StructuredDeserialize(value))` - * from the HTML standard. Used by the internal `readableStreamTee` method to clone values for connected implementations. - * @see https://html.spec.whatwg.org/multipage/structured-data.html#structuredserializeinternal - */ export function cloneValue(value: any): any { const valueType = typeof value; switch (valueType) { diff --git a/cli/js/web/streams/strategies.ts b/cli/js/web/streams/strategies.ts index 5f7ffc6324..98fe0f91a4 100644 --- a/cli/js/web/streams/strategies.ts +++ b/cli/js/web/streams/strategies.ts @@ -1,13 +1,6 @@ // Forked from https://github.com/stardazed/sd-streams/tree/8928cf04b035fd02fb1340b7eb541c76be37e546 // Copyright (c) 2018-Present by Arthur Langereis - @zenmumbler MIT -/** - * streams/strategies - implementation of the built-in stream strategies - * Part of Stardazed - * (c) 2018-Present by Arthur Langereis - @zenmumbler - * https://github.com/stardazed/sd-streams - */ - /* eslint-disable @typescript-eslint/no-explicit-any */ // TODO reenable this lint here diff --git a/cli/js/web/text_encoding.ts b/cli/js/web/text_encoding.ts index 928cbe7e1e..2da53d9349 100644 --- a/cli/js/web/text_encoding.ts +++ b/cli/js/web/text_encoding.ts @@ -92,7 +92,6 @@ class UTF8Encoder implements Encoder { } } -/** Decodes a string of data which has been encoded using base-64. */ export function atob(s: string): string { s = String(s); s = s.replace(/[\t\n\f\r ]/g, ""); @@ -120,7 +119,6 @@ export function atob(s: string): string { return result; } -/** Creates a base-64 ASCII string from the input string. */ export function btoa(s: string): string { const byteArray = []; for (let i = 0; i < s.length; i++) { @@ -303,13 +301,10 @@ function isEitherArrayBuffer(x: any): x is EitherArrayBuffer { export class TextDecoder { private _encoding: string; - /** Returns encoding's name, lowercased. */ get encoding(): string { return this._encoding; } - /** Returns `true` if error mode is "fatal", and `false` otherwise. */ readonly fatal: boolean = false; - /** Returns `true` if ignore BOM flag is set, and `false` otherwise. */ readonly ignoreBOM: boolean = false; constructor(label = "utf-8", options: TextDecoderOptions = { fatal: false }) { @@ -334,7 +329,6 @@ export class TextDecoder { this._encoding = encoding; } - /** Returns the result of running encoding's decoder. */ decode( input?: domTypes.BufferSource, options: TextDecodeOptions = { stream: false } @@ -400,9 +394,7 @@ interface TextEncoderEncodeIntoResult { } export class TextEncoder { - /** Returns "utf-8". */ readonly encoding = "utf-8"; - /** Returns the result of running UTF-8's encoder. */ encode(input = ""): Uint8Array { // For performance reasons we utilise a highly optimised decoder instead of // the general decoder. diff --git a/cli/js/web/timers.ts b/cli/js/web/timers.ts index 806b7c1605..520a2722aa 100644 --- a/cli/js/web/timers.ts +++ b/cli/js/web/timers.ts @@ -261,7 +261,6 @@ function setTimer( return timer.id; } -/** Sets a timer which executes a function once after the timer expires. */ export function setTimeout( cb: (...args: Args) => void, delay = 0, @@ -273,7 +272,6 @@ export function setTimeout( return setTimer(cb, delay, args, false); } -/** Repeatedly calls a function, with a fixed time delay between each call. */ export function setInterval( cb: (...args: Args) => void, delay = 0, @@ -285,7 +283,6 @@ export function setInterval( return setTimer(cb, delay, args, true); } -/** Clears a previously set timer by id. AKA clearTimeout and clearInterval. */ function clearTimer(id: number): void { id = Number(id); const timer = idMap.get(id); diff --git a/cli/js/web/url_search_params.ts b/cli/js/web/url_search_params.ts index ed93045da6..8f60f29188 100644 --- a/cli/js/web/url_search_params.ts +++ b/cli/js/web/url_search_params.ts @@ -60,22 +60,12 @@ export class URLSearchParams { (this.url as any)._parts.query = query; } - /** Appends a specified key/value pair as a new search parameter. - * - * searchParams.append('name', 'first'); - * searchParams.append('name', 'second'); - */ append(name: string, value: string): void { requiredArguments("URLSearchParams.append", arguments.length, 2); this.params.push([String(name), String(value)]); this.updateSteps(); } - /** Deletes the given search parameter and its associated value, - * from the list of all search parameters. - * - * searchParams.delete('name'); - */ delete(name: string): void { requiredArguments("URLSearchParams.delete", arguments.length, 1); name = String(name); @@ -90,11 +80,6 @@ export class URLSearchParams { this.updateSteps(); } - /** Returns all the values associated with a given search parameter - * as an array. - * - * searchParams.getAll('name'); - */ getAll(name: string): string[] { requiredArguments("URLSearchParams.getAll", arguments.length, 1); name = String(name); @@ -108,10 +93,6 @@ export class URLSearchParams { return values; } - /** Returns the first value associated to the given search parameter. - * - * searchParams.get('name'); - */ get(name: string): string | null { requiredArguments("URLSearchParams.get", arguments.length, 1); name = String(name); @@ -124,24 +105,12 @@ export class URLSearchParams { return null; } - /** Returns a Boolean that indicates whether a parameter with the - * specified name exists. - * - * searchParams.has('name'); - */ has(name: string): boolean { requiredArguments("URLSearchParams.has", arguments.length, 1); name = String(name); return this.params.some((entry): boolean => entry[0] === name); } - /** Sets the value associated with a given search parameter to the - * given value. If there were several matching values, this method - * deletes the others. If the search parameter doesn't exist, this - * method creates it. - * - * searchParams.set('name', 'value'); - */ set(name: string, value: string): void { requiredArguments("URLSearchParams.set", arguments.length, 2); @@ -175,12 +144,6 @@ export class URLSearchParams { this.updateSteps(); } - /** Sort all key/value pairs contained in this object in place and - * return undefined. The sort order is according to Unicode code - * points of the keys. - * - * searchParams.sort(); - */ sort(): void { this.params = this.params.sort((a, b): number => a[0] === b[0] ? 0 : a[0] > b[0] ? 1 : -1 @@ -188,15 +151,6 @@ export class URLSearchParams { this.updateSteps(); } - /** Calls a function for each element contained in this object in - * place and return undefined. Optionally accepts an object to use - * as this when executing callback as second argument. - * - * searchParams.forEach((value, key, parent) => { - * console.log(value, key, parent); - * }); - * - */ forEach( callbackfn: (value: string, key: string, parent: this) => void, // eslint-disable-next-line @typescript-eslint/no-explicit-any @@ -213,58 +167,26 @@ export class URLSearchParams { } } - /** Returns an iterator allowing to go through all keys contained - * in this object. - * - * for (const key of searchParams.keys()) { - * console.log(key); - * } - */ *keys(): IterableIterator { for (const entry of this.params) { yield entry[0]; } } - /** Returns an iterator allowing to go through all values contained - * in this object. - * - * for (const value of searchParams.values()) { - * console.log(value); - * } - */ *values(): IterableIterator { for (const entry of this.params) { yield entry[1]; } } - /** Returns an iterator allowing to go through all key/value - * pairs contained in this object. - * - * for (const [key, value] of searchParams.entries()) { - * console.log(key, value); - * } - */ *entries(): IterableIterator<[string, string]> { yield* this.params; } - /** Returns an iterator allowing to go through all key/value - * pairs contained in this object. - * - * for (const [key, value] of searchParams[Symbol.iterator]()) { - * console.log(key, value); - * } - */ *[Symbol.iterator](): IterableIterator<[string, string]> { yield* this.params; } - /** Returns a query string suitable for use in a URL. - * - * searchParams.toString(); - */ toString(): string { return this.params .map( diff --git a/cli/js/web/util.ts b/cli/js/web/util.ts index b0a0509731..8d248ce1ff 100644 --- a/cli/js/web/util.ts +++ b/cli/js/web/util.ts @@ -47,29 +47,6 @@ export function getPrivateValue< throw new TypeError("Illegal invocation"); } -/** - * Determines whether an object has a property with the specified name. - * Avoid calling prototype builtin `hasOwnProperty` for two reasons: - * - * 1. `hasOwnProperty` is defined on the object as something else: - * - * const options = { - * ending: 'utf8', - * hasOwnProperty: 'foo' - * }; - * options.hasOwnProperty('ending') // throws a TypeError - * - * 2. The object doesn't inherit from `Object.prototype`: - * - * const options = Object.create(null); - * options.ending = 'utf8'; - * options.hasOwnProperty('ending'); // throws a TypeError - * - * @param obj A Object. - * @param v A property name. - * @see https://eslint.org/docs/rules/no-prototype-builtins - * @internal - */ export function hasOwnProperty(obj: T, v: PropertyKey): boolean { if (obj == null) { return false; diff --git a/cli/js/write_file.ts b/cli/js/write_file.ts index 995335f574..5227bfecec 100644 --- a/cli/js/write_file.ts +++ b/cli/js/write_file.ts @@ -4,27 +4,12 @@ import { open, openSync } from "./files.ts"; import { chmod, chmodSync } from "./ops/fs/chmod.ts"; import { writeAll, writeAllSync } from "./buffer.ts"; -/** Options for writing to a file. */ export interface WriteFileOptions { - /** Defaults to `false`. If set to `true`, will append to a file instead of - * overwriting previous contents. */ append?: boolean; - /** Sets the option to allow creating a new file, if one doesn't already - * exist at the specified path (defaults to `true`). */ create?: boolean; - /** Permissions always applied to file. */ mode?: number; } -/** Synchronously write data to the given path, by default creating a new - * file if needed, else overwriting. - * - * const encoder = new TextEncoder(); - * const data = encoder.encode("Hello world\n"); - * Deno.writeFileSync("hello.txt", data); - * - * Requires `allow-write` permission, and `allow-read` if create is `false`. - */ export function writeFileSync( path: string, data: Uint8Array, @@ -49,15 +34,6 @@ export function writeFileSync( file.close(); } -/** Write data to the given path, by default creating a new file if needed, - * else overwriting. - * - * const encoder = new TextEncoder(); - * const data = encoder.encode("Hello world\n"); - * await Deno.writeFile("hello.txt", data); - * - * Requires `allow-write` permission, and `allow-read` if create is `false`. - */ export async function writeFile( path: string, data: Uint8Array,