foster/denoland-deno
1
0
Fork 0
mirror of https://github.com/denoland/deno.git synced 2024-12-22 23:34:47 -05:00
Code Issues Packages 1 Wiki Activity

Align JSDoc to style guide.

Browse source
This commit is contained in:
Kitson Kelly 2018-10-15 07:29:50 +11:00 committed by Ryan Dahl
parent 1840a19713
commit 10a97679ac
31 changed files with 437 additions and 423 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

1
js/blob.ts
View file

@ -9,6 +9,7 @@ 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

83
js/compiler.ts
View file

@ -27,38 +27,29 @@ type AMDRequire = (
errback: AmdErrback
) => void;
/**
* The location that a module is being loaded from. This could be a directory,
/** The location that a module is being loaded from. This could be a directory,
* like `.`, or it could be a module specifier like
* `http://gist.github.com/somefile.ts`
*/
type ContainingFile = string;
/**
* The internal local filename of a compiled module. It will often be something
/** The internal local filename of a compiled module. It will often be something
* like `/home/ry/.deno/gen/f7b4605dfbc4d3bb356e98fda6ceb1481e4a8df5.js`
*/
type ModuleFileName = string;
/**
* The original resolved resource name.
/** The original resolved resource name.
* Path to cached module file or URL from which dependency was retrieved
*/
type ModuleId = string;
/**
* The external name of a module - could be a URL or could be a relative path.
/** The external name of a module - could be a URL or could be a relative path.
* Examples `http://gist.github.com/somefile.ts` or `./somefile.ts`
*/
type ModuleSpecifier = string;
/**
* The compiled source code which is cached in `.deno/gen/`
*/
/** The compiled source code which is cached in `.deno/gen/` */
type OutputCode = string;
/**
* The original source code
*/
/** The original source code */
type SourceCode = string;
/**
* Abstraction of the APIs required from the `os` module so they can be
/** Abstraction of the APIs required from the `os` module so they can be
* easily mocked.
* @internal
*/
@ -68,8 +59,7 @@ export interface Os {
exit: typeof os.exit;
}
/**
* Abstraction of the APIs required from the `typescript` module so they can
/** Abstraction of the APIs required from the `typescript` module so they can
* be easily mocked.
* @internal
*/
@ -79,8 +69,7 @@ export interface Ts {
formatDiagnosticsWithColorAndContext: typeof ts.formatDiagnosticsWithColorAndContext;
}
/**
* A simple object structure for caching resolved modules and their contents.
/** A simple object structure for caching resolved modules and their contents.
*
* Named `ModuleMetaData` to clarify it is just a representation of meta data of
* the module, not the actual module instance.
@ -118,8 +107,7 @@ export class ModuleMetaData implements ts.IScriptSnapshot {
}
}
/**
* A singleton class that combines the TypeScript Language Service host API
/** A singleton class that combines the TypeScript Language Service host API
* with Deno specific APIs to provide an interface for compiling and running
* TypeScript and JavaScript modules.
*/
@ -173,8 +161,7 @@ export class DenoCompiler
// Flags forcing recompilation of TS code
public recompile = false;
/**
* Drain the run queue, retrieving the arguments for the module
/** Drain the run queue, retrieving the arguments for the module
* factory and calling the module's factory.
*/
private _drainRunQueue(): void {
@ -195,8 +182,7 @@ export class DenoCompiler
}
}
/**
* Get the dependencies for a given module, but don't run the module,
/** Get the dependencies for a given module, but don't run the module,
* just add the module factory to the run queue.
*/
private _gatherDependencies(moduleMetaData: ModuleMetaData): void {
@ -216,9 +202,7 @@ export class DenoCompiler
this._window.define = undefined;
}
/**
* Retrieve the arguments to pass a module's factory function.
*/
/** Retrieve the arguments to pass a module's factory function. */
// tslint:disable-next-line:no-any
private _getFactoryArguments(moduleMetaData: ModuleMetaData): any[] {
if (!moduleMetaData.deps) {
@ -241,8 +225,7 @@ export class DenoCompiler
});
}
/**
* The TypeScript language service often refers to the resolved fileName of
/** The TypeScript language service often refers to the resolved fileName of
* a module, this is a shortcut to avoid unnecessary module resolution logic
* for modules that may have been initially resolved by a `moduleSpecifier`
* and `containingFile`. Also, `resolveModule()` throws when the module
@ -260,9 +243,7 @@ export class DenoCompiler
: undefined;
}
/**
* Create a localized AMD `define` function and return it.
*/
/** Create a localized AMD `define` function and return it. */
private _makeDefine(moduleMetaData: ModuleMetaData): AmdDefine {
return (deps: ModuleSpecifier[], factory: AmdFactory): void => {
this._log("compiler.localDefine", moduleMetaData.fileName);
@ -295,8 +276,7 @@ export class DenoCompiler
};
}
/**
* Returns a require that specifically handles the resolution of a transpiled
/** Returns a require that specifically handles the resolution of a transpiled
* emit of a dynamic ES `import()` from TypeScript.
*/
private _makeLocalRequire(moduleMetaData: ModuleMetaData): AMDRequire {
@ -323,8 +303,7 @@ export class DenoCompiler
};
}
/**
* Given a `moduleSpecifier` and `containingFile` retrieve the cached
/** Given a `moduleSpecifier` and `containingFile` retrieve the cached
* `fileName` for a given module. If the module has yet to be resolved
* this will return `undefined`.
*/
@ -340,8 +319,8 @@ export class DenoCompiler
return undefined;
}
/**
* Resolve the `fileName` for a given `moduleSpecifier` and `containingFile`
/** Resolve the `fileName` for a given `moduleSpecifier` and
* `containingFile`
*/
private _resolveModuleName(
moduleSpecifier: ModuleSpecifier,
@ -351,8 +330,7 @@ export class DenoCompiler
return moduleMetaData ? moduleMetaData.fileName : undefined;
}
/**
* Caches the resolved `fileName` in relationship to the `moduleSpecifier`
/** Caches the resolved `fileName` in relationship to the `moduleSpecifier`
* and `containingFile` in order to reduce calls to the privileged side
* to retrieve the contents of a module.
*/
@ -370,8 +348,7 @@ export class DenoCompiler
innerMap.set(moduleSpecifier, fileName);
}
/**
* Setup being able to map back source references back to their source
/** Setup being able to map back source references back to their source
*
* TODO is this the best place for this? It is tightly coupled to how the
* compiler works, but it is also tightly coupled to how the whole runtime
@ -413,8 +390,7 @@ export class DenoCompiler
// Deno specific compiler API
/**
* Retrieve the output of the TypeScript compiler for a given module and
/** Retrieve the output of the TypeScript compiler for a given module and
* cache the result. Re-compilation can be forced using '--recompile' flag.
*/
compile(moduleMetaData: ModuleMetaData): OutputCode {
@ -462,9 +438,9 @@ export class DenoCompiler
return moduleMetaData.outputCode;
}
/**
* For a given module specifier and containing file, return a list of absolute
* identifiers for dependent modules that are required by this module.
/** For a given module specifier and containing file, return a list of
* absolute identifiers for dependent modules that are required by this
* module.
*/
getModuleDependencies(
moduleSpecifier: ModuleSpecifier,
@ -490,8 +466,7 @@ export class DenoCompiler
return dependencies;
}
/**
* Given a `moduleSpecifier` and `containingFile`, resolve the module and
/** Given a `moduleSpecifier` and `containingFile`, resolve the module and
* return the `ModuleMetaData`.
*/
resolveModule(
@ -546,8 +521,7 @@ export class DenoCompiler
return moduleMetaData;
}
/**
* Load and run a module and all of its dependencies based on a module
/** Load and run a module and all of its dependencies based on a module
* specifier and a containing file
*/
run(
@ -675,8 +649,7 @@ export class DenoCompiler
// Deno specific static properties and methods
/**
* Built in modules which can be returned to external modules
/** Built in modules which can be returned to external modules
*
* Placed as a private static otherwise we get use before
* declared with the `DenoCompiler`

9
js/console.ts
View file

@ -182,26 +182,35 @@ export class Console {
// @internal
constructor(private printFunc: PrintFunc) {}
/** Writes the arguments to stdout */
// tslint:disable-next-line:no-any
log = (...args: any[]): void => {
this.printFunc(stringifyArgs(args));
};
/** 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 */
// tslint:disable-next-line:no-any
dir = (obj: any, options: ConsoleOptions = {}) => {
this.printFunc(stringifyArgs([obj], options));
};
/** Writes the arguments to stdout */
// tslint:disable-next-line:no-any
warn = (...args: any[]): void => {
this.printFunc(stringifyArgs(args), true);
};
/** 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.
*/
// tslint:disable-next-line:no-any
assert = (condition: boolean, ...args: any[]): void => {
if (!condition) {

17
js/copy_file.ts
View file

@ -3,29 +3,30 @@ import * as msg from "gen/msg_generated";
import { flatbuffers } from "flatbuffers";
import * as dispatch from "./dispatch";
/**
* Copies the contents of a file to another by name synchronously.
/** Copies the contents of a file to another by name synchronously.
* Creates a new file if target does not exists, and if target exists,
* overwrites original content of the target file.
*
* It would also copy the permission of the original file
* to the destination.
*
* import { copyFileSync } from "deno";
* copyFileSync("from.txt", "to.txt");
* import { copyFileSync } from "deno";
* copyFileSync("from.txt", "to.txt");
*/
export function copyFileSync(from: string, to: string): void {
dispatch.sendSync(...req(from, to));
}
/**
* Copies the contents of a file to another by name.
/** Copies the contents of a file to another by name.
*
* Creates a new file if target does not exists, and if target exists,
* overwrites original content of the target file.
*
* It would also copy the permission of the original file
* to the destination.
*
* import { copyFile } from "deno";
* await copyFile("from.txt", "to.txt");
* import { copyFile } from "deno";
* await copyFile("from.txt", "to.txt");
*/
export async function copyFile(from: string, to: string): Promise<void> {
await dispatch.sendAsync(...req(from, to));

131
js/dom_types.ts
View file

@ -245,28 +245,68 @@ export interface FormData {
): void;
}
/** 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;
}
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<ArrayBuffer>;
/** Takes a `Response` stream and reads it to completion. It returns a promise
* that resolves with a `Blob`.
*/
blob(): Promise<Blob>;
/** Takes a `Response` stream and reads it to completion. It returns a promise
* that resolves with a `FormData` object.
*/
formData(): Promise<FormData>;
/** 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.
*/
// tslint:disable-next-line:no-any
json(): Promise<any>;
/** Takes a `Response` stream and reads it to completion. It returns a promise
* that resolves with a `USVString` (text).
*/
text(): Promise<string>;
}
export interface Headers {
/** 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 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;
/** 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;
forEach(
callbackfn: (value: string, key: string, parent: Headers) => void,
@ -336,100 +376,101 @@ export interface ResponseInit {
}
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.
/** 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
/** 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".
/** 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.
/** 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.
* 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]
/** 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
/** Returns a boolean indicating whether or not request is for a history
* navigation (a.k.a. back-foward navigation).
*/
readonly isHistoryNavigation: boolean;
/**
* Returns a boolean indicating whether or not requestis for a
* reload navigation.
/** 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.
/** 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.
*/
/** 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.
/** 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
/** 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
/** 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.
* `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
/** 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.
/** 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.
*/
/** 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<Headers>;
/** 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;
}

12
js/errors.ts
View file

@ -1,6 +1,18 @@
import { Base, ErrorKind } from "gen/msg_generated";
export { ErrorKind } from "gen/msg_generated";
/** A Deno specific error. The `kind` property is set to a specific error code
* which can be used to in application logic.
*
* import { DenoError, ErrorKind } from "deno";
* try {
* somethingThatMightThrow();
* } catch (e) {
* if (e instanceof DenoError && e.kind === DenoError.Overflow) {
* console.error("Overflow error!");
* }
* }
*/
export class DenoError<T extends ErrorKind> extends Error {
constructor(readonly kind: T, msg: string) {
super(msg);

1
js/fetch.ts
View file

@ -178,6 +178,7 @@ class FetchResponse implements domTypes.Response {
}
}
/** Fetch a resource from the network. */
export async function fetch(
input?: domTypes.Request | string,
init?: domTypes.RequestInit

30
js/file_info.ts
View file

@ -1,8 +1,7 @@
// Copyright 2018 the Deno authors. All rights reserved. MIT license.
import * as msg from "gen/msg_generated";
/**
* A FileInfo describes a file and is returned by `stat`, `lstat`,
/** A FileInfo describes a file and is returned by `stat`, `lstat`,
* `statSync`, `lstatSync`.
*/
export interface FileInfo {
@ -10,52 +9,43 @@ export interface FileInfo {
readonly _isSymlink: boolean;
/** The size of the file, in bytes. */
len: number;
/**
* The last modification time of the file. This corresponds to the `mtime`
/** The last modification time of the file. This corresponds to the `mtime`
* field from `stat` on Unix 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`
/** 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`
/** The last access time of the file. This corresponds to the `birthtime`
* field from `stat` on Unix and `ftCreationTime` on Windows. This may not
* be available on all platforms.
*/
created: number | null;
/**
* The underlying raw st_mode bits that contain the standard Unix permissions
/** The underlying raw st_mode bits that contain the standard Unix permissions
* for this file/directory. TODO Match behavior with Go on windows for mode.
*/
mode: number | null;
/**
* Returns the file or directory name.
*/
/** Returns the file or directory name. */
name: string | null;
/** Returns the file or directory path. */
/** Returns the file or directory path. */
path: string | null;
/**
* Returns whether this is info for a regular file. This result is mutually
/** 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
/** 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
/** Returns whether this is info for a symlink. This result is
* mutually exclusive to `FileInfo.isFile` and `FileInfo.isDirectory`.
*/
isSymlink(): boolean;

23
js/files.ts
View file

@ -6,6 +6,7 @@ import * as msg from "gen/msg_generated";
import { assert } from "./util";
import { flatbuffers } from "flatbuffers";
/** The Deno abstraction for reading and writing files. */
export class File implements Reader, Writer, Closer {
constructor(readonly rid: number) {}
@ -22,17 +23,30 @@ export class File implements Reader, Writer, Closer {
}
}
/** An instance of `File` for stdin. */
export const stdin = new File(0);
/** An instance of `File` for stdout. */
export const stdout = new File(1);
/** An instance of `File` for stderr. */
export const stderr = new File(2);
// TODO This is just a placeholder - not final API.
export type OpenMode = "r" | "w" | "w+" | "x";
/** A factory function for creating instances of `File` associated with the
* supplied file name.
*/
export function create(filename: string): Promise<File> {
return open(filename, "x");
}
/** Open a file and return an instance of the `File` object.
*
* import * as deno from "deno";
* (async () => {
* const file = await deno.open("/foo/bar.txt");
* })();
*/
export async function open(
filename: string,
mode: OpenMode = "r"
@ -51,6 +65,10 @@ export async function open(
return new File(rid);
}
/** Read from a file ID into an array buffer.
*
* Resolves with the `ReadResult` for the operation.
*/
export async function read(
rid: number,
p: ArrayBufferView
@ -67,6 +85,10 @@ export async function read(
return { nread: res.nread(), eof: res.eof() };
}
/** Write to the file ID the contents of the array buffer.
*
* Resolves with the number of bytes written.
*/
export async function write(rid: number, p: ArrayBufferView): Promise<number> {
const builder = new flatbuffers.Builder();
msg.Write.startWrite(builder);
@ -80,6 +102,7 @@ export async function write(rid: number, p: ArrayBufferView): Promise<number> {
return res.nbyte();
}
/** Close the file ID. */
export function close(rid: number): void {
const builder = new flatbuffers.Builder();
msg.Close.startClose(builder);

3
js/global_eval.ts
View file

@ -1,5 +1,4 @@
/**
* If you use the eval function indirectly, by invoking it via a reference
/** If you use the eval function indirectly, by invoking it via a reference
* other than eval, as of ECMAScript 5 it works in the global scope rather than
* the local scope. This means, for instance, that function declarations create
* global functions, and that the code being evaluated doesn't have access to

101
js/io.ts
View file

@ -11,44 +11,46 @@ export interface ReadResult {
// Reader is the interface that wraps the basic read() method.
// https://golang.org/pkg/io/#Reader
export interface Reader {
// read() reads up to p.byteLength bytes into p. It returns the number of
// bytes read (0 <= n <= p.byteLength) and 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 read() encounters an error or end-of-file condition after successfully
// reading n > 0 bytes, it returns the number of bytes read. It may return the
// (non-nil) error from the same call or return the error (and n == 0) from a
// subsequent call. An instance of this general case is that a Reader
// returning a non-zero number of bytes at the end of the input stream may
// return either err == EOF or err == nil. The next read() should return 0,
// EOF.
//
// 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 of read() are discouraged from returning a zero byte count
// with a nil error, except when p.byteLength == 0. Callers should treat a
// return of 0 and nil as indicating that nothing happened; in particular it
// does not indicate EOF.
//
// Implementations must not retain p.
/** Reads up to p.byteLength bytes into `p`. It resolves to the number
* of bytes read (`0` <= `n` <= `p.byteLength`) and 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 `read()` encounters an error or end-of-file condition after
* successfully reading `n` > `0` bytes, it returns the number of bytes read.
* It may return the (non-nil) error from the same call or return the error
* (and `n` == `0`) from a subsequent call. An instance of this general case
* is that a `Reader` returning a non-zero number of bytes at the end of the
* input stream may return either `err` == `EOF` or `err` == `null`. The next
* `read()` should return `0`, `EOF`.
*
* 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 of `read()` are discouraged from returning a zero byte
* count with a `null` error, except when `p.byteLength` == `0`. Callers
* should treat a return of `0` and `null` as indicating that nothing
* happened; in particular it does not indicate `EOF`.
*
* Implementations must not retain `p`.
*/
read(p: ArrayBufferView): Promise<ReadResult>;
}
// Writer is the interface that wraps the basic write() method.
// https://golang.org/pkg/io/#Writer
export interface Writer {
// write() 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. write() must return
// a non-nil error if it returns n < p.byteLength. write() must not modify the
// slice data, even temporarily.
//
// Implementations must not retain p.
/** 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`) and any error encountered that caused the write to stop
* early. `write()` must return a non-null error if it returns `n` <
* `p.byteLength`. write() must not modify the slice data, even temporarily.
*
* Implementations must not retain `p`.
*/
write(p: ArrayBufferView): Promise<number>;
}
@ -61,15 +63,16 @@ 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: SeekStart means relative to the start of the file,
// SeekCurrent means relative to the current offset, and SeekEnd means
// relative to the end. Seek returns the new offset relative to the start of
// the file and an error, if any.
//
// 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.
/** Seek sets the offset for the next `read()` or `write()` to offset,
* interpreted according to `whence`: `SeekStart` means relative to the start
* of the file, `SeekCurrent` means relative to the current offset, and
* `SeekEnd` means relative to the end. Seek returns the new offset relative
* to the start of the file and an error, if any.
*
* 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.
*/
seek(offset: number, whence: number): Promise<void>;
}
@ -91,17 +94,17 @@ export interface ReadWriteCloser extends Reader, Writer, Closer {}
// https://golang.org/pkg/io/#ReadWriteSeeker
export interface ReadWriteSeeker extends Reader, Writer, Seeker {}
// copy() copies from src to dst until either EOF is reached on src or an error
// occurs. It returns the number of bytes copied and the first error encountered
// while copying, if any.
//
// Because copy() is defined to read from src until EOF, it does not treat an
// EOF from read() as an error to be reported.
//
/** Copies from `src` to `dst` until either `EOF` is reached on `src`
* or an error occurs. It returns the number of bytes copied and the first
* error encountered while copying, if any.
*
* 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<number> {
let n = 0;
const b = new Uint8Array(32*1024);
const b = new Uint8Array(32 * 1024);
let gotEOF = false;
while (gotEOF === false) {
const result = await src.read(b);

18
js/make_temp_dir.ts
View file

@ -10,19 +10,17 @@ export interface MakeTempDirOptions {
suffix?: string;
}
/**
* makeTempDirSync is the synchronous version of `makeTempDir`.
/** makeTempDirSync is the synchronous version of `makeTempDir`.
*
* import { makeTempDirSync } from "deno";
* const tempDirName0 = makeTempDirSync();
* const tempDirName1 = makeTempDirSync({ prefix: 'my_temp' });
* import { makeTempDirSync } from "deno";
* const tempDirName0 = makeTempDirSync();
* const tempDirName1 = makeTempDirSync({ prefix: 'my_temp' });
*/
export function makeTempDirSync(options: MakeTempDirOptions = {}): string {
return res(dispatch.sendSync(...req(options)));
}
/**
* makeTempDir creates a new temporary directory in the directory `dir`, its
/** makeTempDir 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, tempDir uses the default directory for temporary
@ -30,9 +28,9 @@ export function makeTempDirSync(options: MakeTempDirOptions = {}): string {
* same directory. It is the caller's responsibility to remove the directory
* when no longer needed.
*
* import { makeTempDir } from "deno";
* const tempDirName0 = await makeTempDir();
* const tempDirName1 = await makeTempDir({ prefix: 'my_temp' });
* import { makeTempDir } from "deno";
* const tempDirName0 = await makeTempDir();
* const tempDirName1 = await makeTempDir({ prefix: 'my_temp' });
*/
export async function makeTempDir(
options: MakeTempDirOptions = {}

1
js/metrics.ts
View file

@ -12,6 +12,7 @@ interface Metrics {
bytesReceived: number;
}
/** Receive metrics from the privileged side of Deno. */
export function metrics(): Metrics {
return res(dispatch.sendSync(...req()));
}

15
js/mkdir.ts
View file

@ -3,21 +3,20 @@ import * as msg from "gen/msg_generated";
import { flatbuffers } from "flatbuffers";
import * as dispatch from "./dispatch";
/**
* Creates a new directory with the specified path and permission synchronously.
/** Creates a new directory with the specified path and permission
* synchronously.
*
* import { mkdirSync } from "deno";
* mkdirSync("new_dir");
* import { mkdirSync } from "deno";
* mkdirSync("new_dir");
*/
export function mkdirSync(path: string, mode = 0o777): void {
dispatch.sendSync(...req(path, mode));
}
/**
* Creates a new directory with the specified path and permission.
/** Creates a new directory with the specified path and permission.
*
* import { mkdir } from "deno";
* await mkdir("new_dir");
* import { mkdir } from "deno";
* await mkdir("new_dir");
*/
export async function mkdir(path: string, mode = 0o777): Promise<void> {
await dispatch.sendAsync(...req(path, mode));

60
js/net.ts
View file

@ -16,14 +16,15 @@ export type Addr = string;
/** A Listener is a generic network listener for stream-oriented protocols. */
export interface Listener {
/** accept() waits for and returns the next connection to the Listener. */
/** Waits for and resolves to the next connection to the `Listener`. */
accept(): Promise<Conn>;
/** Close closes the listener.
* Any pending accept promises will be rejected with errors.
/** Close closes the listener. Any pending accept promises will be rejected
* with errors.
*/
close(): void;
/** Return the address of the `Listener`. */
addr(): Addr;
}
@ -53,9 +54,17 @@ class ListenerImpl implements Listener {
}
export interface Conn extends Reader, Writer, Closer {
/** The local address of the connection. */
localAddr: string;
/** The remote address of the connection. */
remoteAddr: string;
/** 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;
}
@ -113,18 +122,18 @@ function shutdown(rid: number, how: ShutdownMode) {
/** Listen announces on the local network address.
*
* The network must be "tcp", "tcp4", "tcp6", "unix" or "unixpacket".
* The network must be `tcp`, `tcp4`, `tcp6`, `unix` or `unixpacket`.
*
* For TCP networks, if the host in the address parameter is empty or a literal
* unspecified IP address, Listen listens on all available unicast and anycast
* IP addresses of the local system. To only use IPv4, use network "tcp4". The
* address can use a host name, but this is not recommended, because it will
* create a listener for at most one of the host's IP addresses. If the port in
* the address parameter is empty or "0", as in "127.0.0.1:" or "[::1]:0", a
* port number is automatically chosen. The Addr method of Listener can be used
* to discover the chosen port.
* unspecified IP address, `listen()` listens on all available unicast and
* anycast IP addresses of the local system. To only use IPv4, use network
* `tcp4`. The address can use a host name, but this is not recommended,
* because it will create a listener for at most one of the host's IP
* addresses. If the port in the address parameter is empty or `0`, as in
* `127.0.0.1:` or `[::1]:0`, a port number is automatically chosen. The
* `addr()` method of `Listener` can be used to discover the chosen port.
*
* See dial() for a description of the network and address parameters.
* See `dial()` for a description of the network and address parameters.
*/
export function listen(network: Network, address: string): Listener {
const builder = new flatbuffers.Builder();
@ -144,16 +153,17 @@ export function listen(network: Network, address: string): Listener {
/** Dial connects to the address on the named network.
*
* Supported networks are only "tcp" currently.
* TODO: "tcp4" (IPv4-only), "tcp6" (IPv6-only), "udp", "udp4"
* (IPv4-only), "udp6" (IPv6-only), "ip", "ip4" (IPv4-only), "ip6" (IPv6-only),
* "unix", "unixgram" and "unixpacket".
* Supported networks are only `tcp` currently.
*
* For TCP and UDP networks, the address has the form "host:port". The host must
* TODO: `tcp4` (IPv4-only), `tcp6` (IPv6-only), `udp`, `udp4` (IPv4-only),
* `udp6` (IPv6-only), `ip`, `ip4` (IPv4-only), `ip6` (IPv6-only), `unix`,
* `unixgram` and `unixpacket`.
*
* For TCP and UDP networks, the address has the form `host:port`. The host must
* be a literal IP address, or a host name that can be resolved to IP addresses.
* The port must be a literal port number or a service name. If the host is a
* literal IPv6 address it must be enclosed in square brackets, as in
* "[2001:db8::1]:80" or "[fe80::1%zone]:80". The zone specifies the scope of
* `[2001:db8::1]:80` or `[fe80::1%zone]:80`. The zone specifies the scope of
* the literal IPv6 address as defined in RFC 4007. The functions JoinHostPort
* and SplitHostPort manipulate a pair of host and port in this form. When using
* TCP, and the host resolves to multiple IP addresses, Dial will try each IP
@ -161,12 +171,12 @@ export function listen(network: Network, address: string): Listener {
*
* Examples:
*
* dial("tcp", "golang.org:http")
* dial("tcp", "192.0.2.1:http")
* dial("tcp", "198.51.100.1:80")
* dial("udp", "[2001:db8::1]:domain")
* dial("udp", "[fe80::1%lo0]:53")
* dial("tcp", ":80")
* dial("tcp", "golang.org:http")
* dial("tcp", "192.0.2.1:http")
* dial("tcp", "198.51.100.1:80")
* dial("udp", "[2001:db8::1]:domain")
* dial("udp", "[fe80::1%lo0]:53")
* dial("tcp", ":80")
*/
export async function dial(network: Network, address: string): Promise<Conn> {
const builder = new flatbuffers.Builder();
@ -184,7 +194,7 @@ export async function dial(network: Network, address: string): Promise<Conn> {
return new ConnImpl(res.rid(), res.remoteAddr()!, res.localAddr()!);
}
// Unused but reserved op.
/** **RESERVED** */
export async function connect(
network: Network,
address: string

17
js/os.ts
View file

@ -6,6 +6,7 @@ import * as util from "./util";
import { flatbuffers } from "flatbuffers";
import { sendSync } from "./dispatch";
/** Exit the Deno process with optional exit code. */
export function exit(exitCode = 0): never {
const builder = new flatbuffers.Builder();
msg.Exit.startExit(builder);
@ -93,18 +94,18 @@ function setEnv(key: string, value: string): void {
sendSync(builder, msg.Any.SetEnv, inner);
}
/**
* Returns a snapshot of the environment variables at invocation. Mutating a
/** 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 or `number`s
* as values.
* import { env } from "deno";
*
* const myEnv = env();
* console.log(myEnv.SHELL);
* myEnv.TEST_VAR = "HELLO";
* const newEnv = env();
* console.log(myEnv.TEST_VAR == newEnv.TEST_VAR);
* import { env } from "deno";
*
* const myEnv = env();
* console.log(myEnv.SHELL);
* myEnv.TEST_VAR = "HELLO";
* const newEnv = env();
* console.log(myEnv.TEST_VAR == newEnv.TEST_VAR);
*/
export function env(): { [index: string]: string } {
/* Ideally we could write

8
js/platform.ts
View file

@ -1,13 +1,9 @@
// Do not add unsupported platforms.
export interface Platform {
/**
* The operating system CPU architecture
*/
/** The operating system CPU architecture. */
arch: "x64";
/**
* The operating system platform
*/
/** The operating system platform. */
os: "mac" | "win" | "linux";
}

17
js/read_dir.ts
View file

@ -5,23 +5,20 @@ import * as dispatch from "./dispatch";
import { FileInfo, FileInfoImpl } from "./file_info";
import { assert } from "./util";
/**
* Reads the directory given by path and returns
* a list of file info synchronously.
/** Reads the directory given by path and returns a list of file info
* synchronously.
*
* import { readDirSync } from "deno";
* const files = readDirSync("/");
* import { readDirSync } from "deno";
* const files = readDirSync("/");
*/
export function readDirSync(path: string): FileInfo[] {
return res(dispatch.sendSync(...req(path)));
}
/**
* Reads the directory given by path and returns a list of file info.
*
* import { readDir } from "deno";
* const files = await readDir("/");
/** Reads the directory given by path and returns a list of file info.
*
* import { readDir } from "deno";
* const files = await readDir("/");
*/
export async function readDir(path: string): Promise<FileInfo[]> {
return res(await dispatch.sendAsync(...req(path)));

22
js/read_file.ts
View file

@ -4,25 +4,23 @@ import { flatbuffers } from "flatbuffers";
import { assert } from "./util";
import * as dispatch from "./dispatch";
/**
* Read the entire contents of a file synchronously.
/** Read the entire contents of a file synchronously.
*
* import { readFileSync } from "deno";
* const decoder = new TextDecoder("utf-8");
* const data = readFileSync("hello.txt");
* console.log(decoder.decode(data));
* import { readFileSync } from "deno";
* const decoder = new TextDecoder("utf-8");
* const data = readFileSync("hello.txt");
* console.log(decoder.decode(data));
*/
export function readFileSync(filename: string): Uint8Array {
return res(dispatch.sendSync(...req(filename)));
}
/**
* Read the entire contents of a file.
/** Read the entire contents of a file.
*
* import { readFile } from "deno";
* const decoder = new TextDecoder("utf-8");
* const data = await readFile("hello.txt");
* console.log(decoder.decode(data));
* import { readFile } from "deno";
* const decoder = new TextDecoder("utf-8");
* const data = await readFile("hello.txt");
* console.log(decoder.decode(data));
*/
export async function readFile(filename: string): Promise<Uint8Array> {
return res(await dispatch.sendAsync(...req(filename)));

14
js/read_link.ts
View file

@ -4,21 +4,19 @@ import { flatbuffers } from "flatbuffers";
import { assert } from "./util";
import * as dispatch from "./dispatch";
/**
* Returns the destination of the named symbolic link synchronously.
/** Returns the destination of the named symbolic link synchronously.
*
* import { readlinkSync } from "deno";
* const targetPath = readlinkSync("symlink/path");
* import { readlinkSync } from "deno";
* const targetPath = readlinkSync("symlink/path");
*/
export function readlinkSync(name: string): string {
return res(dispatch.sendSync(...req(name)));
}
/**
* Returns the destination of the named symbolic link.
/** Returns the destination of the named symbolic link.
*
* import { readlink } from "deno";
* const targetPath = await readlink("symlink/path");
* import { readlink } from "deno";
* const targetPath = await readlink("symlink/path");
*/
export async function readlink(name: string): Promise<string> {
return res(await dispatch.sendAsync(...req(name)));

38
js/remove.ts
View file

@ -3,47 +3,41 @@ import * as msg from "gen/msg_generated";
import { flatbuffers } from "flatbuffers";
import * as dispatch from "./dispatch";
/**
* Removes the named file or (empty) directory synchronously.
* Would throw error if permission denied, not found, or
* directory not empty.
/** Removes the named file or (empty) directory synchronously. Would throw
* error if permission denied, not found, or directory not empty.
*
* import { removeSync } from "deno";
* removeSync("/path/to/empty_dir/or/file");
* import { removeSync } from "deno";
* removeSync("/path/to/empty_dir/or/file");
*/
export function removeSync(path: string): void {
dispatch.sendSync(...req(path, false));
}
/**
* Removes the named file or (empty) directory.
* Would throw error if permission denied, not found, or
* directory not empty.
/** Removes the named file or (empty) directory. Would throw error if
* permission denied, not found, or directory not empty.
*
* import { remove } from "deno";
* await remove("/path/to/empty_dir/or/file");
* import { remove } from "deno";
* await remove("/path/to/empty_dir/or/file");
*/
export async function remove(path: string): Promise<void> {
await dispatch.sendAsync(...req(path, false));
}
/**
* Recursively removes the named file or directory synchronously.
* Would throw error if permission denied or not found
/** Recursively removes the named file or directory synchronously. Would throw
* error if permission denied or not found.
*
* import { removeAllSync } from "deno";
* removeAllSync("/path/to/dir/or/file");
* import { removeAllSync } from "deno";
* removeAllSync("/path/to/dir/or/file");
*/
export function removeAllSync(path: string): void {
dispatch.sendSync(...req(path, true));
}
/**
* Recursively removes the named file or directory.
* Would throw error if permission denied or not found
/** Recursively removes the named file or directory. Would throw error if
* permission denied or not found.
*
* import { removeAll } from "deno";
* await removeAll("/path/to/dir/or/file");
* import { removeAll } from "deno";
* await removeAll("/path/to/dir/or/file");
*/
export async function removeAll(path: string): Promise<void> {
await dispatch.sendAsync(...req(path, true));

23
js/rename.ts
View file

@ -3,25 +3,24 @@ import * as msg from "gen/msg_generated";
import { flatbuffers } from "flatbuffers";
import * as dispatch from "./dispatch";
/**
* Synchronously 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.
/** 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.
*
* import { renameSync } from "deno";
* renameSync("old/path", "new/path");
* import { renameSync } from "deno";
* renameSync("old/path", "new/path");
*/
export function renameSync(oldpath: string, newpath: string): void {
dispatch.sendSync(...req(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.
/** 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.
*
* import { rename } from "deno";
* await rename("old/path", "new/path");
* import { rename } from "deno";
* await rename("old/path", "new/path");
*/
export async function rename(oldpath: string, newpath: string): Promise<void> {
await dispatch.sendAsync(...req(oldpath, newpath));

45
js/stat.ts
View file

@ -5,51 +5,46 @@ import * as dispatch from "./dispatch";
import { assert } from "./util";
import { FileInfo, FileInfoImpl } from "./file_info";
/**
* Queries the file system for information on the path provided.
* If the given path is a symlink information about the symlink will
* be returned.
/** Queries the file system for information on the path provided. If the given
* path is a symlink information about the symlink will be returned.
*
* import { lstat } from "deno";
* const fileInfo = await lstat("hello.txt");
* assert(fileInfo.isFile());
* import { lstat } from "deno";
* const fileInfo = await lstat("hello.txt");
* assert(fileInfo.isFile());
*/
export async function lstat(filename: string): Promise<FileInfo> {
return res(await dispatch.sendAsync(...req(filename, true)));
}
/**
* Queries the file system for information on the path provided synchronously.
* If the given path is a symlink information about the symlink will
* be returned.
/** Queries the file system for information on the path provided synchronously.
* If the given path is a symlink information about the symlink will be
* returned.
*
* import { lstatSync } from "deno";
* const fileInfo = lstatSync("hello.txt");
* assert(fileInfo.isFile());
* import { lstatSync } from "deno";
* const fileInfo = lstatSync("hello.txt");
* assert(fileInfo.isFile());
*/
export function lstatSync(filename: string): FileInfo {
return res(dispatch.sendSync(...req(filename, true)));
}
/**
* Queries the file system for information on the path provided.
* `stat` Will always follow symlinks.
/** Queries the file system for information on the path provided. `stat` Will
* always follow symlinks.
*
* import { stat } from "deno";
* const fileInfo = await stat("hello.txt");
* assert(fileInfo.isFile());
* import { stat } from "deno";
* const fileInfo = await stat("hello.txt");
* assert(fileInfo.isFile());
*/
export async function stat(filename: string): Promise<FileInfo> {
return res(await dispatch.sendAsync(...req(filename, false)));
}
/**
* Queries the file system for information on the path provided synchronously.
/** Queries the file system for information on the path provided synchronously.
* `statSync` Will always follow symlinks.
*
* import { statSync } from "deno";
* const fileInfo = statSync("hello.txt");
* assert(fileInfo.isFile());
* import { statSync } from "deno";
* const fileInfo = statSync("hello.txt");
* assert(fileInfo.isFile());
*/
export function statSync(filename: string): FileInfo {
return res(dispatch.sendSync(...req(filename, false)));

22
js/symlink.ts
View file

@ -4,13 +4,12 @@ import { flatbuffers } from "flatbuffers";
import * as dispatch from "./dispatch";
import * as util from "./util";
/**
* Synchronously creates newname as a symbolic link to oldname.
* The type argument can be set to 'dir' or 'file' and is only
* available on Windows (ignored on other platforms).
/** Synchronously creates `newname` as a symbolic link to `oldname`. The type
* argument can be set to `dir` or `file` and is only available on Windows
* (ignored on other platforms).
*
* import { symlinkSync } from "deno";
* symlinkSync("old/name", "new/name");
* import { symlinkSync } from "deno";
* symlinkSync("old/name", "new/name");
*/
export function symlinkSync(
oldname: string,
@ -20,13 +19,12 @@ export function symlinkSync(
dispatch.sendSync(...req(oldname, newname, type));
}
/**
* Creates newname as a symbolic link to oldname.
* The type argument can be set to 'dir' or 'file' and is only
* available on Windows (ignored on other platforms).
/** Creates `newname` as a symbolic link to `oldname`. The type argument can be
* set to `dir` or `file` and is only available on Windows (ignored on other
* platforms).
*
* import { symlink } from "deno";
* await symlink("old/name", "new/name");
* import { symlink } from "deno";
* await symlink("old/name", "new/name");
*/
export async function symlink(
oldname: string,

2
js/text_encoding.ts
View file

@ -2,6 +2,7 @@
import * as base64 from "base64-js";
import { DenoError, ErrorKind } from "./errors";
/** Decodes a string of data which has been encoded using base-64. */
export function atob(s: string): string {
const rem = s.length % 4;
// base64-js requires length exactly times of 4
@ -24,6 +25,7 @@ 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++) {

3
js/timers.ts
View file

@ -197,6 +197,7 @@ function setTimer<Args extends Array<unknown>>(
return timer.id;
}
/** Sets a timer which executes a function once after the timer expires. */
export function setTimeout<Args extends Array<unknown>>(
cb: (...args: Args) => void,
delay: number,
@ -205,6 +206,7 @@ export function setTimeout<Args extends Array<unknown>>(
return setTimer(cb, delay, args, false);
}
/** Repeatedly calls a function , with a fixed time delay between each call. */
export function setInterval<Args extends Array<unknown>>(
cb: (...args: Args) => void,
delay: number,
@ -213,6 +215,7 @@ export function setInterval<Args extends Array<unknown>>(
return setTimer(cb, delay, args, true);
}
/** Clears a previously set timer by id. */
export function clearTimer(id: number): void {
const timer = idMap.get(id);
if (timer === undefined) {

15
js/trace.ts
View file

@ -55,17 +55,16 @@ export function maybePushTrace(op: msg.Any, sync: boolean): void {
);
}
/**
* Trace operations executed inside a given function or promise.
* Notice: To capture every operation in asynchronous deno.* calls,
/** Trace privileged operations executed inside a given function or promise.
*
* _Notice:_ To capture every operation in asynchronous `deno.*` calls,
* you might want to put them in functions instead of directly invoking.
*
* import { trace, mkdir } from "deno";
* import { trace, mkdir } from "deno";
*
* const ops = await trace(async () => {
* await mkdir("my_dir");
* });
* // ops becomes [{ sync: false, name: "Mkdir" }]
* const ops = await trace(async () => {
* await mkdir("my_dir");
* });
*/
export async function trace(
// tslint:disable-next-line:no-any

17
js/truncate.ts
View file

@ -3,25 +3,24 @@ import * as msg from "gen/msg_generated";
import { flatbuffers } from "flatbuffers";
import * as dispatch from "./dispatch";
/**
* Truncates or extends the specified file synchronously,
* updating the size of this file to become size.
/** Truncates or extends the specified file synchronously, updating the size of
* this file to become size.
*
* import { truncateSync } from "deno";
* import { truncateSync } from "deno";
*
* truncateSync("hello.txt", 10);
* truncateSync("hello.txt", 10);
*/
export function truncateSync(name: string, len?: number): void {
dispatch.sendSync(...req(name, len));
}
/**
* Truncates or extends the specified file,
* updating the size of this file to become size.
* Truncates or extends the specified file, updating the size of this file to
* become size.
*
* import { truncate } from "deno";
* import { truncate } from "deno";
*
* await truncate("hello.txt", 10);
* await truncate("hello.txt", 10);
*/
export async function truncate(name: string, len?: number): Promise<void> {
await dispatch.sendAsync(...req(name, len));

62
js/types.ts
View file

@ -41,82 +41,60 @@ export interface ModuleInfo {
// tslint:enable:max-line-length
export interface CallSite {
/**
* Value of "this"
*/
/** Value of `this` */
// tslint:disable-next-line:no-any
getThis(): any;
/**
* Type of "this" as a string.
/** Type of `this` as a string.
*
* This is the name of the function stored in the constructor field of
* "this", if available. Otherwise the object's [[Class]] internal
* `this`, if available. Otherwise the object's `[[Class]]` internal
* property.
*/
getTypeName(): string | null;
/**
* Current function
*/
/** Current function. */
getFunction(): Function | undefined;
/**
* Name of the current function, typically its name property.
/** Name of the current function, typically its name property.
*
* If a name property is not available an attempt will be made to try
* to infer a name from the function's context.
*/
getFunctionName(): string | null;
/**
* Name of the property [of "this" or one of its prototypes] that holds
* the current function
/** Name of the property (of `this` or one of its prototypes) that holds
* the current function.
*/
getMethodName(): string | null;
/**
* Name of the script [if this function was defined in a script]
*/
/** Name of the script (if this function was defined in a script). */
getFileName(): string | null;
/**
* Get the script name or source URL for the source map
*/
/** Get the script name or source URL for the source map. */
getScriptNameOrSourceURL(): string;
/**
* Current line number [if this function was defined in a script]
*/
/** Current line number (if this function was defined in a script). */
getLineNumber(): number | null;
/**
* Current column number [if this function was defined in a script]
*/
/** Current column number (if this function was defined in a script). */
getColumnNumber(): number | null;
/**
* A call site object representing the location where eval was called
* [if this function was created using a call to eval]
/** A call site object representing the location where eval was called (if
* this function was created using a call to `eval`)
*/
getEvalOrigin(): string | undefined;
/**
* Is this a toplevel invocation, that is, is "this" the global object?
*/
/** Is this a top level invocation, that is, is `this` the global object? */
isToplevel(): boolean;
/**
* Does this call take place in code defined by a call to eval?
*/
/** Does this call take place in code defined by a call to `eval`? */
isEval(): boolean;
/**
* Is this call in native V8 code?
*/
/** Is this call in native V8 code? */
isNative(): boolean;
/**
* Is this a constructor call?
*/
/** Is this a constructor call? */
isConstructor(): boolean;
}
@ -136,7 +114,7 @@ export interface RawSourceMap extends StartOfSourceMap {
declare global {
// Declare "static" methods in Error
interface ErrorConstructor {
/** Create .stack property on a target object */
/** Create `.stack` property on a target object */
captureStackTrace(targetObject: object, constructorOpt?: Function): void;
// tslint:disable:max-line-length

28
js/util.ts
View file

@ -8,8 +8,7 @@ export function setLogDebug(debug: boolean): void {
logDebug = debug;
}
/**
* Debug logging for deno.
/** Debug logging for deno.
* Enable with the `--log-debug` or `-D` command line flag.
* @internal
*/
@ -38,20 +37,22 @@ export function arrayToStr(ui8: Uint8Array): string {
return String.fromCharCode(...ui8);
}
/**
* A `Resolvable` is a Promise with the `reject` and `resolve` functions
/** 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<number>();
* ...
* p.resolve(42);
* const p = createResolvable<number>();
* // ...
* p.resolve(42);
*
* It'd be prettier to make Resolvable a class that inherits from Promise,
* 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.
* See https://github.com/Microsoft/TypeScript/issues/15202
* At the time of writing, the github issue is closed but the problem remains.
*
* 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
*/
@ -109,11 +110,8 @@ export interface Deferred {
reject: Function;
}
/**
* Create a wrapper around a promise that could be
* resolved externally.
* @internal
*/
/** Create a wrapper around a promise that could be resolved externally. */
// @internal
export function deferred(): Deferred {
let resolve: Function | undefined;
let reject: Function | undefined;

22
js/write_file.ts
View file

@ -3,14 +3,13 @@ import * as msg from "gen/msg_generated";
import { flatbuffers } from "flatbuffers";
import * as dispatch from "./dispatch";
/**
* Write a new file, with given filename and data synchronously.
/** Write a new file, with given filename and data synchronously.
*
* import { writeFileSync } from "deno";
* import { writeFileSync } from "deno";
*
* const encoder = new TextEncoder("utf-8");
* const data = encoder.encode("Hello world\n");
* writeFileSync("hello.txt", data);
* const encoder = new TextEncoder("utf-8");
* const data = encoder.encode("Hello world\n");
* writeFileSync("hello.txt", data);
*/
export function writeFileSync(
filename: string,
@ -20,14 +19,13 @@ export function writeFileSync(
dispatch.sendSync(...req(filename, data, perm));
}
/**
* Write a new file, with given filename and data.
/** Write a new file, with given filename and data.
*
* import { writeFile } from "deno";
* import { writeFile } from "deno";
*
* const encoder = new TextEncoder("utf-8");
* const data = encoder.encode("Hello world\n");
* await writeFile("hello.txt", data);
* const encoder = new TextEncoder("utf-8");
* const data = encoder.encode("Hello world\n");
* await writeFile("hello.txt", data);
*/
export async function writeFile(
filename: string,