diff options
Diffstat (limited to 'cli/dts/lib.deno.unstable.d.ts')
| -rw-r--r-- | cli/dts/lib.deno.unstable.d.ts | 852 |
1 files changed, 638 insertions, 214 deletions
diff --git a/cli/dts/lib.deno.unstable.d.ts b/cli/dts/lib.deno.unstable.d.ts index ba6d03c7e..cde76d4d8 100644 --- a/cli/dts/lib.deno.unstable.d.ts +++ b/cli/dts/lib.deno.unstable.d.ts @@ -8,28 +8,38 @@ declare namespace Deno { /** **UNSTABLE**: New API, yet to be vetted. * + * The interface for defining a benchmark test using {@linkcode Deno.bench}. + * * @category Testing */ export interface BenchDefinition { + /** The test function which will be benchmarked. */ fn: () => void | Promise<void>; + /** The name of the test, which will be used in displaying the results. */ name: string; + /** If truthy, the benchmark test will be ignored/skipped. */ ignore?: boolean; /** Group name for the benchmark. - * Grouped benchmarks produce a time summary */ + * + * Grouped benchmarks produce a group time summary, where the difference + * in performance between each test of the group is compared. */ group?: string; - /** Benchmark should be used as the baseline for other benchmarks - * If there are multiple baselines in a group, the first one is used as the baseline */ + /** Benchmark should be used as the baseline for other benchmarks. + * + * If there are multiple baselines in a group, the first one is used as the + * baseline. */ baseline?: boolean; /** If at least one bench has `only` set to true, only run benches that have - * `only` set to true and fail the bench suite. */ + * `only` set to `true` and fail the bench suite. */ only?: boolean; /** Ensure the bench case does not prematurely cause the process to exit, - * for example via a call to `Deno.exit`. Defaults to true. */ + * for example via a call to {@linkcode Deno.exit}. Defaults to `true`. */ sanitizeExit?: boolean; - /** Specifies the permissions that should be used to run the bench. - * Set this to "inherit" to keep the calling thread's permissions. - * Set this to "none" to revoke all permissions. + * + * Set this to `"inherit"` to keep the calling thread's permissions. + * + * Set this to `"none"` to revoke all permissions. * * Defaults to "inherit". */ @@ -38,15 +48,18 @@ declare namespace Deno { /** **UNSTABLE**: New API, yet to be vetted. * - * Register a bench which will be run when `deno bench` is used on the command - * line and the containing module looks like a bench module. - * `fn` can be async if required. + * Register a benchmark test which will be run when `deno bench` is used on + * the command line and the containing module looks like a bench module. + * + * If the test function (`fn`) returns a promise or is async, the test runner + * will await resolution to consider the test complete. + * * ```ts - * import {assert, fail, assertEquals} from "https://deno.land/std/testing/asserts.ts"; + * import { assertEquals } from "https://deno.land/std/testing/asserts.ts"; * * Deno.bench({ * name: "example test", - * fn(): void { + * fn() { * assertEquals("world", "world"); * }, * }); @@ -54,7 +67,7 @@ declare namespace Deno { * Deno.bench({ * name: "example ignored test", * ignore: Deno.build.os === "windows", - * fn(): void { + * fn() { * // This test is ignored only on Windows machines * }, * }); @@ -75,18 +88,20 @@ declare namespace Deno { /** **UNSTABLE**: New API, yet to be vetted. * - * Register a bench which will be run when `deno bench` is used on the command - * line and the containing module looks like a bench module. - * `fn` can be async if required. + * Register a benchmark test which will be run when `deno bench` is used on + * the command line and the containing module looks like a bench module. + * + * If the test function (`fn`) returns a promise or is async, the test runner + * will await resolution to consider the test complete. * * ```ts - * import {assert, fail, assertEquals} from "https://deno.land/std/testing/asserts.ts"; + * import { assertEquals } from "https://deno.land/std/testing/asserts.ts"; * - * Deno.bench("My test description", (): void => { + * Deno.bench("My test description", () => { * assertEquals("hello", "hello"); * }); * - * Deno.bench("My async test description", async (): Promise<void> => { + * Deno.bench("My async test description", async () => { * const decoder = new TextDecoder("utf-8"); * const data = await Deno.readFile("hello_world.txt"); * assertEquals(decoder.decode(data), "Hello world"); @@ -102,18 +117,20 @@ declare namespace Deno { /** **UNSTABLE**: New API, yet to be vetted. * - * Register a bench which will be run when `deno bench` is used on the command - * line and the containing module looks like a bench module. - * `fn` can be async if required. Declared function must have a name. + * Register a benchmark test which will be run when `deno bench` is used on + * the command line and the containing module looks like a bench module. + * + * If the test function (`fn`) returns a promise or is async, the test runner + * will await resolution to consider the test complete. * * ```ts - * import {assert, fail, assertEquals} from "https://deno.land/std/testing/asserts.ts"; + * import { assertEquals } from "https://deno.land/std/testing/asserts.ts"; * - * Deno.bench(function myTestName(): void { + * Deno.bench(function myTestName() { * assertEquals("hello", "hello"); * }); * - * Deno.bench(async function myOtherTestName(): Promise<void> { + * Deno.bench(async function myOtherTestName() { * const decoder = new TextDecoder("utf-8"); * const data = await Deno.readFile("hello_world.txt"); * assertEquals(decoder.decode(data), "Hello world"); @@ -126,22 +143,32 @@ declare namespace Deno { /** **UNSTABLE**: New API, yet to be vetted. * - * Register a bench which will be run when `deno bench` is used on the command - * line and the containing module looks like a bench module. - * `fn` can be async if required. + * Register a benchmark test which will be run when `deno bench` is used on + * the command line and the containing module looks like a bench module. + * + * If the test function (`fn`) returns a promise or is async, the test runner + * will await resolution to consider the test complete. * * ```ts - * import {assert, fail, assertEquals} from "https://deno.land/std/testing/asserts.ts"; + * import { assertEquals } from "https://deno.land/std/testing/asserts.ts"; * - * Deno.bench("My test description", { permissions: { read: true } }, (): void => { - * assertEquals("hello", "hello"); - * }); + * Deno.bench( + * "My test description", + * { permissions: { read: true } }, + * () => { + * assertEquals("hello", "hello"); + * } + * ); * - * Deno.bench("My async test description", { permissions: { read: false } }, async (): Promise<void> => { - * const decoder = new TextDecoder("utf-8"); - * const data = await Deno.readFile("hello_world.txt"); - * assertEquals(decoder.decode(data), "Hello world"); - * }); + * Deno.bench( + * "My async test description", + * { permissions: { read: false } }, + * async () => { + * const decoder = new TextDecoder("utf-8"); + * const data = await Deno.readFile("hello_world.txt"); + * assertEquals(decoder.decode(data), "Hello world"); + * } + * ); * ``` * * @category Testing @@ -154,22 +181,30 @@ declare namespace Deno { /** **UNSTABLE**: New API, yet to be vetted. * - * Register a bench which will be run when `deno bench` is used on the command - * line and the containing module looks like a bench module. - * `fn` can be async if required. + * Register a benchmark test which will be run when `deno bench` is used on + * the command line and the containing module looks like a bench module. + * + * If the test function (`fn`) returns a promise or is async, the test runner + * will await resolution to consider the test complete. * * ```ts - * import {assert, fail, assertEquals} from "https://deno.land/std/testing/asserts.ts"; + * import { assertEquals } from "https://deno.land/std/testing/asserts.ts"; * - * Deno.bench({ name: "My test description", permissions: { read: true } }, (): void => { - * assertEquals("hello", "hello"); - * }); + * Deno.bench( + * { name: "My test description", permissions: { read: true } }, + * () => { + * assertEquals("hello", "hello"); + * } + * ); * - * Deno.bench({ name: "My async test description", permissions: { read: false } }, async (): Promise<void> => { - * const decoder = new TextDecoder("utf-8"); - * const data = await Deno.readFile("hello_world.txt"); - * assertEquals(decoder.decode(data), "Hello world"); - * }); + * Deno.bench( + * { name: "My async test description", permissions: { read: false } }, + * async () => { + * const decoder = new TextDecoder("utf-8"); + * const data = await Deno.readFile("hello_world.txt"); + * assertEquals(decoder.decode(data), "Hello world"); + * } + * ); * ``` * * @category Testing @@ -181,22 +216,30 @@ declare namespace Deno { /** **UNSTABLE**: New API, yet to be vetted. * - * Register a bench which will be run when `deno bench` is used on the command - * line and the containing module looks like a bench module. - * `fn` can be async if required. Declared function must have a name. + * Register a benchmark test which will be run when `deno bench` is used on + * the command line and the containing module looks like a bench module. + * + * If the test function (`fn`) returns a promise or is async, the test runner + * will await resolution to consider the test complete. * * ```ts - * import {assert, fail, assertEquals} from "https://deno.land/std/testing/asserts.ts"; + * import { assertEquals } from "https://deno.land/std/testing/asserts.ts"; * - * Deno.bench({ permissions: { read: true } }, function myTestName(): void { - * assertEquals("hello", "hello"); - * }); + * Deno.bench( + * { permissions: { read: true } }, + * function myTestName() { + * assertEquals("hello", "hello"); + * } + * ); * - * Deno.bench({ permissions: { read: false } }, async function myOtherTestName(): Promise<void> { - * const decoder = new TextDecoder("utf-8"); - * const data = await Deno.readFile("hello_world.txt"); - * assertEquals(decoder.decode(data), "Hello world"); - * }); + * Deno.bench( + * { permissions: { read: false } }, + * async function myOtherTestName() { + * const decoder = new TextDecoder("utf-8"); + * const data = await Deno.readFile("hello_world.txt"); + * assertEquals(decoder.decode(data), "Hello world"); + * } + * ); * ``` * * @category Testing @@ -220,7 +263,7 @@ declare namespace Deno { * This API is under consideration to determine if permissions are required to * call it. * - * NOTE: This API is not implemented on Windows + * *Note*: This API is not implemented on Windows * * @category File System */ @@ -246,49 +289,52 @@ declare namespace Deno { /** **UNSTABLE**: New API, yet to be vetted. * + * Information returned from a call to {@linkcode Deno.systemMemoryInfo}. + * * @category Runtime Environment */ export interface SystemMemoryInfo { - /** Total installed memory */ + /** Total installed memory in bytes. */ total: number; - /** Unused memory */ + /** Unused memory in bytes. */ free: number; - /** Estimation of how much memory is available for starting new - * applications, without swapping. Unlike the data provided by the cache or + /** Estimation of how much memory, in bytes, is available for starting new + * applications, without swapping. Unlike the data provided by the cache or * free fields, this field takes into account page cache and also that not - * all reclaimable memory slabs will be reclaimed due to items being in use + * all reclaimable memory will be reclaimed due to items being in use. */ available: number; - /** Memory used by kernel buffers */ + /** Memory used by kernel buffers. */ buffers: number; - /** Memory used by the page cache and slabs */ + /** Memory used by the page cache and slabs. */ cached: number; - /** Total swap memory */ + /** Total swap memory. */ swapTotal: number; - /** Unused swap memory */ + /** Unused swap memory. */ swapFree: number; } /** **UNSTABLE**: New API, yet to be vetted. * - * The information of the network interface. + * The information for a network interface returned from a call to + * {@linkcode Deno.networkInterfaces}. * * @category Network */ export interface NetworkInterfaceInfo { - /** The network interface name */ + /** The network interface name. */ name: string; - /** The IP protocol version */ + /** The IP protocol version. */ family: "IPv4" | "IPv6"; - /** The IP address */ + /** The IP address bound to the interface. */ address: string; - /** The netmask */ + /** The netmask applied to the interface. */ netmask: string; - /** The IPv6 scope id or null */ + /** The IPv6 scope id or `null`. */ scopeid: number | null; - /** The CIDR range */ + /** The CIDR range. */ cidr: string; - /** The MAC address */ + /** The MAC address. */ mac: string; } @@ -309,7 +355,8 @@ declare namespace Deno { /** **UNSTABLE**: New API, yet to be vetted. * - * Returns the user id of the process on POSIX platforms. Returns null on Windows. + * Returns the user id of the Deno process on POSIX platforms. Returns `null` + * on Windows. * * ```ts * console.log(Deno.getUid()); @@ -324,7 +371,8 @@ declare namespace Deno { /** **UNSTABLE**: New API, yet to be vetted. * - * Returns the group id of the process on POSIX platforms. Returns null on windows. + * Returns the group id of the process on POSIX platforms. Returns `null` on + * Windows. * * ```ts * console.log(Deno.getGid()); @@ -367,37 +415,47 @@ declare namespace Deno { /** **UNSTABLE**: New API, yet to be vetted. * + * The native boolean type for interfacing to foreign functions. + * * @category FFI */ type NativeBooleanType = "bool"; /** **UNSTABLE**: New API, yet to be vetted. * + * The native pointer type for interfacing to foreign functions. + * * @category FFI */ type NativePointerType = "pointer"; /** **UNSTABLE**: New API, yet to be vetted. * + * The native buffer type for interfacing to foreign functions. + * * @category FFI */ type NativeBufferType = "buffer"; /** **UNSTABLE**: New API, yet to be vetted. * + * The native function type for interfacing with foreign functions. + * * @category FFI */ type NativeFunctionType = "function"; /** **UNSTABLE**: New API, yet to be vetted. * + * The native void type for interfacing with foreign functions. + * * @category FFI */ type NativeVoidType = "void"; /** **UNSTABLE**: New API, yet to be vetted. * - * All possible types for interfacing with foreign functions. + * All supported types for interfacing with foreign functions. * * @category FFI */ @@ -417,6 +475,9 @@ declare namespace Deno { /** **UNSTABLE**: New API, yet to be vetted. * + * A utility type conversion for foreign symbol parameters and unsafe callback + * return types. + * * @category FFI */ type ToNativeTypeMap = @@ -438,6 +499,8 @@ declare namespace Deno { /** **UNSTABLE**: New API, yet to be vetted. * + * A utility type for conversion for unsafe callback return types. + * * @category FFI */ type ToNativeResultTypeMap = ToNativeTypeMap & Record<NativeVoidType, void>; @@ -453,6 +516,8 @@ declare namespace Deno { /** **UNSTABLE**: New API, yet to be vetted. * + * A utility type for conversion of parameter types of foreign functions. + * * @category FFI */ type ToNativeParameterTypes<T extends readonly NativeType[]> = @@ -467,6 +532,9 @@ declare namespace Deno { /** **UNSTABLE**: New API, yet to be vetted. * + * A utility type for conversion of foreign symbol return types and unsafe + * callback parameters. + * * @category FFI */ type FromNativeTypeMap = @@ -488,6 +556,8 @@ declare namespace Deno { /** **UNSTABLE**: New API, yet to be vetted. * + * A utility type for conversion for foreign symbol return types. + * * @category FFI */ type FromNativeResultTypeMap = @@ -521,7 +591,8 @@ declare namespace Deno { /** **UNSTABLE**: New API, yet to be vetted. * - * A foreign function as defined by its parameter and result types. + * The interface for a foreign function as defined by its parameter and result + * types. * * @category FFI */ @@ -530,13 +601,21 @@ declare namespace Deno { Result extends NativeResultType = NativeResultType, NonBlocking extends boolean = boolean, > { - /** Name of the symbol, defaults to the key name in symbols object. */ + /** Name of the symbol. + * + * Defaults to the key name in symbols object. */ name?: string; + /** The parameters of the foreign function. */ parameters: Parameters; + /** The result (return value) of the foreign function. */ result: Result; - /** When true, function calls will run on a dedicated blocking thread and will return a Promise resolving to the `result`. */ + /** When `true`, function calls will run on a dedicated blocking thread and + * will return a `Promise` resolving to the `result`. */ nonblocking?: NonBlocking; - /** When true, function calls can safely callback into JS or trigger a GC event. Default is `false`. */ + /** When `true`, function calls can safely callback into JavaScript or + * trigger a garbage collection event. + * + * Default is `false`. */ callback?: boolean; } @@ -547,6 +626,7 @@ declare namespace Deno { export interface ForeignStatic<Type extends NativeType = NativeType> { /** Name of the symbol, defaults to the key name in symbols object. */ name?: string; + /** The type of the foreign static value. */ type: Type; } @@ -562,7 +642,7 @@ declare namespace Deno { /** **UNSTABLE**: New API, yet to be vetted. * - * Infers a foreign symbol. + * A utility type that infers a foreign symbol. * * @category FFI */ @@ -597,7 +677,7 @@ declare namespace Deno { /** **UNSTABLE**: New API, yet to be vetted. * - * Infers a foreign library interface. + * A utility type that infers a foreign library interface. * * @category FFI */ @@ -609,9 +689,9 @@ declare namespace Deno { * * Pointer type depends on the architecture and actual pointer value. * - * On a 32 bit system all pointer values are plain numbers. On a 64 bit - * system pointer values are represented as numbers if the value is below - * `Number.MAX_SAFE_INTEGER`. + * On a 32 bit host system all pointer values are plain numbers. On a 64 bit + * host system pointer values are represented as numbers if the value is below + * `Number.MAX_SAFE_INTEGER`, otherwise they are provided as bigints. * * @category FFI */ @@ -625,18 +705,16 @@ declare namespace Deno { * @category FFI */ export class UnsafePointer { - /** - * Return the direct memory pointer to the typed array in memory - */ + /** Return the direct memory pointer to the typed array in memory. */ static of(value: Deno.UnsafeCallback | BufferSource): PointerValue; } /** **UNSTABLE**: New API, yet to be vetted. * * An unsafe pointer view to a memory location as specified by the `pointer` - * value. The `UnsafePointerView` API mimics the standard built in interface - * `DataView` for accessing the underlying types at an memory location - * (numbers, strings and raw bytes). + * value. The `UnsafePointerView` API follows the standard built in interface + * {@linkcode DataView} for accessing the underlying types at an memory + * location (numbers, strings and raw bytes). * * @category FFI */ @@ -647,41 +725,63 @@ declare namespace Deno { /** Gets a boolean at the specified byte offset from the pointer. */ getBool(offset?: number): boolean; - /** Gets an unsigned 8-bit integer at the specified byte offset from the pointer. */ + /** Gets an unsigned 8-bit integer at the specified byte offset from the + * pointer. */ getUint8(offset?: number): number; - /** Gets a signed 8-bit integer at the specified byte offset from the pointer. */ + /** Gets a signed 8-bit integer at the specified byte offset from the + * pointer. */ getInt8(offset?: number): number; - /** Gets an unsigned 16-bit integer at the specified byte offset from the pointer. */ + /** Gets an unsigned 16-bit integer at the specified byte offset from the + * pointer. */ getUint16(offset?: number): number; - /** Gets a signed 16-bit integer at the specified byte offset from the pointer. */ + /** Gets a signed 16-bit integer at the specified byte offset from the + * pointer. */ getInt16(offset?: number): number; - /** Gets an unsigned 32-bit integer at the specified byte offset from the pointer. */ + /** Gets an unsigned 32-bit integer at the specified byte offset from the + * pointer. */ getUint32(offset?: number): number; - /** Gets a signed 32-bit integer at the specified byte offset from the pointer. */ + /** Gets a signed 32-bit integer at the specified byte offset from the + * pointer. */ getInt32(offset?: number): number; - /** Gets an unsigned 64-bit integer at the specified byte offset from the pointer. */ + /** Gets an unsigned 64-bit integer at the specified byte offset from the + * pointer. */ getBigUint64(offset?: number): PointerValue; - /** Gets a signed 64-bit integer at the specified byte offset from the pointer. */ + /** Gets a signed 64-bit integer at the specified byte offset from the + * pointer. */ getBigInt64(offset?: number): PointerValue; - /** Gets a signed 32-bit float at the specified byte offset from the pointer. */ + /** Gets a signed 32-bit float at the specified byte offset from the + * pointer. */ getFloat32(offset?: number): number; - /** Gets a signed 64-bit float at the specified byte offset from the pointer. */ + /** Gets a signed 64-bit float at the specified byte offset from the + * pointer. */ getFloat64(offset?: number): number; - /** Gets a C string (null terminated string) at the specified byte offset from the pointer. */ + /** Gets a C string (`null` terminated string) at the specified byte offset + * from the pointer. */ getCString(offset?: number): string; - /** Gets a C string (null terminated string) at the specified byte offset from the specified pointer. */ + /** Gets a C string (`null` terminated string) at the specified byte offset + * from the specified pointer. */ static getCString(pointer: PointerValue, offset?: number): string; - /** Gets an ArrayBuffer of length `byteLength` at the specified byte offset from the pointer. */ + /** Gets an `ArrayBuffer` of length `byteLength` at the specified byte + * offset from the pointer. */ getArrayBuffer(byteLength: number, offset?: number): ArrayBuffer; - /** Gets an ArrayBuffer of length `byteLength` at the specified byte offset from the specified pointer. */ + /** Gets an `ArrayBuffer` of length `byteLength` at the specified byte + * offset from the specified pointer. */ static getArrayBuffer( pointer: PointerValue, byteLength: number, offset?: number, ): ArrayBuffer; - /** Copies the memory of the pointer into a typed array. Length is determined from the typed array's `byteLength`. Also takes optional byte offset from the pointer. */ + /** Copies the memory of the pointer into a typed array. + * + * Length is determined from the typed array's `byteLength`. + * + * Also takes optional byte offset from the pointer. */ copyInto(destination: BufferSource, offset?: number): void; - /** Copies the memory of the specified pointer into a typed array. Length is determined from the typed array's `byteLength`. Also takes optional byte offset from the pointer. */ + /** Copies the memory of the specified pointer into a typed array. + * + * Length is determined from the typed array's `byteLength`. + * + * Also takes optional byte offset from the pointer. */ static copyInto( pointer: PointerValue, destination: BufferSource, @@ -691,34 +791,43 @@ declare namespace Deno { /** **UNSTABLE**: New API, yet to be vetted. * - * An unsafe pointer to a function, for calling functions that are not - * present as symbols. + * An unsafe pointer to a function, for calling functions that are not present + * as symbols. * * @category FFI */ export class UnsafeFnPointer<Fn extends ForeignFunction> { + /** The pointer to the function. */ pointer: PointerValue; + /** The definition of the function. */ definition: Fn; constructor(pointer: PointerValue, definition: Fn); + /** Call the foreign function. */ call: FromForeignFunction<Fn>; } /** **UNSTABLE**: New API, yet to be vetted. * + * Definition of a unsafe callback function. + * * @category FFI */ export interface UnsafeCallbackDefinition< Parameters extends readonly NativeType[] = readonly NativeType[], Result extends NativeResultType = NativeResultType, > { + /** The parameters of the callbacks. */ parameters: Parameters; + /** The current result of the callback. */ result: Result; } /** **UNSTABLE**: New API, yet to be vetted. * + * An unsafe callback function. + * * @category FFI */ type UnsafeCallbackFunction< @@ -730,13 +839,13 @@ declare namespace Deno { /** **UNSTABLE**: New API, yet to be vetted. * - * An unsafe function pointer for passing JavaScript functions - * as C function pointers to ffi calls. + * An unsafe function pointer for passing JavaScript functions as C function + * pointers to foreign function calls. * * The function pointer remains valid until the `close()` method is called. * - * The callback can be explicitly ref'ed and deref'ed to stop Deno's - * process from exiting. + * The callback can be explicitly referenced via `ref()` and dereferenced via + * `deref()` to stop Deno's process from exiting. * * @category FFI */ @@ -751,35 +860,39 @@ declare namespace Deno { >, ); + /** The pointer to the unsafe callback. */ pointer: PointerValue; + /** The definition of the unsafe callback. */ definition: Definition; + /** The callback function. */ callback: UnsafeCallbackFunction< Definition["parameters"], Definition["result"] >; /** - * Adds one to this callback's reference counting and returns the - * new reference count. + * Adds one to this callback's reference counting and returns the new + * reference count. * - * If the callback's reference count becomes non-zero, it will keep - * Deno's process from exiting. + * If the callback's reference count is non-zero, it will keep Deno's + * process from exiting. */ ref(): number; /** - * Removes one from this callback's reference counting and returns - * the new reference count. + * Removes one from this callback's reference counting and returns the new + * reference count. * - * If the callback's reference counter becomes zero, it will no longer - * keep Deno's process from exiting. + * If the callback's reference counter is zero, it will no longer keep + * Deno's process from exiting. */ unref(): number; /** - * Removes the C function pointer associated with the UnsafeCallback. - * Continuing to use the instance after calling this object will lead to errors - * and crashes. + * Removes the C function pointer associated with this instance. + * + * Continuing to use the instance after calling this object will lead to + * errors and crashes. * * Calling this method will also immediately set the callback's reference * counting to zero and it will no longer keep Deno's process from exiting. @@ -789,20 +902,70 @@ declare namespace Deno { /** **UNSTABLE**: New API, yet to be vetted. * - * A dynamic library resource + * A dynamic library resource. Use {@linkcode Deno.dlopen} to load a dynamic + * library and return this interface. * * @category FFI */ export interface DynamicLibrary<S extends ForeignLibraryInterface> { - /** All of the registered library along with functions for calling them */ + /** All of the registered library along with functions for calling them. */ symbols: StaticForeignLibraryInterface<S>; + /** Removes the pointers associated with the library symbols. + * + * Continuing to use symbols that are part of the library will lead to + * errors and crashes. + * + * Calling this method will also immediately set any references to zero and + * will no longer keep Deno's process from exiting. + */ close(): void; } /** **UNSTABLE**: New API, yet to be vetted. * - * Opens a dynamic library and registers symbols + * Opens an external dynamic library and registers symbols, making foreign + * functions available to be called. + * + * Requires `allow-ffi` permission. Loading foreign dynamic libraries can in + * theory bypass all of the sandbox permissions. While it is a separate + * permission users should acknowledge in practice that is effectively the + * same as running with the `allow-all` permission. * + * An example, given a C library which exports a foreign function named + * `add()`: + * + * ```ts + * // Determine library extension based on + * // your OS. + * let libSuffix = ""; + * switch (Deno.build.os) { + * case "windows": + * libSuffix = "dll"; + * break; + * case "darwin": + * libSuffix = "dylib"; + * break; + * default: + * libSuffix = "so"; + * break; + * } + * + * const libName = `./libadd.${libSuffix}`; + * // Open library and define exported symbols + * const dylib = Deno.dlopen( + * libName, + * { + * "add": { parameters: ["isize", "isize"], result: "isize" }, + * } as const, + * ); + * + * // Call the symbol `add` + * const result = dylib.symbols.add(35, 34); // 69 + * + * console.log(`Result from external addition of 35 and 34: ${result}`); + * ``` + * + * @tags allow-ffi * @category FFI */ export function dlopen<S extends ForeignLibraryInterface>( @@ -812,23 +975,76 @@ declare namespace Deno { /** **UNSTABLE**: New API, yet to be vetted. * + * These are unstable options which can be used with {@linkcode Deno.run}. + */ + interface UnstableRunOptions extends RunOptions { + /** If `true`, clears the environment variables before executing the + * sub-process. Defaults to `false`. */ + clearEnv?: boolean; + /** For POSIX systems, sets the group ID for the sub process. */ + gid?: number; + /** For POSIX systems, sets the user ID for the sub process. */ + uid?: number; + } + + /** **UNSTABLE**: New API, yet to be vetted. + * + * Spawns new subprocess. RunOptions must contain at a minimum the `opt.cmd`, + * an array of program arguments, the first of which is the binary. + * + * ```ts + * const p = Deno.run({ + * cmd: ["curl", "https://example.com"], + * }); + * const status = await p.status(); + * ``` + * + * Subprocess uses same working directory as parent process unless `opt.cwd` + * is specified. + * + * Environmental variables from parent process can be cleared using `opt.clearEnv`. + * Doesn't guarantee that only `opt.env` variables are present, + * as the OS may set environmental variables for processes. + * + * Environmental variables for subprocess can be specified using `opt.env` + * mapping. + * + * `opt.uid` sets the child process’s user ID. This translates to a setuid call + * in the child process. Failure in the setuid call will cause the spawn to fail. + * + * `opt.gid` is similar to `opt.uid`, but sets the group ID of the child process. + * This has the same semantics as the uid field. + * + * By default subprocess inherits stdio of parent process. To change + * this this, `opt.stdin`, `opt.stdout`, and `opt.stderr` can be set + * independently to a resource ID (_rid_) of an open file, `"inherit"`, + * `"piped"`, or `"null"`: + * + * - _number_: the resource ID of an open file/resource. This allows you to + * read or write to a file. + * - `"inherit"`: The default if unspecified. The subprocess inherits from the + * parent. + * - `"piped"`: A new pipe should be arranged to connect the parent and child + * sub-process. + * - `"null"`: This stream will be ignored. This is the equivalent of attaching + * the stream to `/dev/null`. + * + * Details of the spawned process are returned as an instance of + * {@linkcode Deno.Process}. + * + * Requires `allow-run` permission. + * + * @tags allow-run * @category Sub Process */ - export function run< - T extends RunOptions & { - clearEnv?: boolean; - gid?: number; - uid?: number; - } = RunOptions & { - clearEnv?: boolean; - gid?: number; - uid?: number; - }, - >(opt: T): Process<T>; + export function run<T extends UnstableRunOptions = UnstableRunOptions>( + opt: T, + ): Process<T>; /** **UNSTABLE**: New API, yet to be vetted. * - * A custom HttpClient for use with `fetch`. + * A custom `HttpClient` for use with {@linkcode fetch} function. This is + * designed to allow custom certificates or proxies to be used with `fetch()`. * * ```ts * const caCert = await Deno.readTextFile("./ca.pem"); @@ -838,14 +1054,16 @@ declare namespace Deno { * * @category Fetch API */ - export class HttpClient { + export interface HttpClient { + /** The resource ID associated with the client. */ rid: number; + /** Close the HTTP client. */ close(): void; } /** **UNSTABLE**: New API, yet to be vetted. * - * The options used when creating a [HttpClient]. + * The options used when creating a {@linkcode Deno.HttpClient}. * * @category Fetch API */ @@ -865,25 +1083,37 @@ declare namespace Deno { /** **UNSTABLE**: New API, yet to be vetted. * + * The definition of a proxy when specifying + * {@linkcode Deno.CreateHttpClientOptions}. + * * @category Fetch API */ export interface Proxy { + /** The string URL of the proxy server to use. */ url: string; + /** The basic auth credentials to be used against the proxy server. */ basicAuth?: BasicAuth; } /** **UNSTABLE**: New API, yet to be vetted. * + * Basic authentication credentials to be used with a {@linkcode Deno.Proxy} + * server when specifying {@linkcode Deno.CreateHttpClientOptions}. + * * @category Fetch API */ export interface BasicAuth { + /** The username to be used against the proxy server. */ username: string; + /** The password to be used against the proxy server. */ password: string; } /** **UNSTABLE**: New API, yet to be vetted. * - * Create a custom HttpClient for to use with `fetch`. + * Create a custom HttpClient for to use with {@linkcode fetch}. This is an + * extension of the web platform Fetch API which allows Deno to use custom + * TLS certificates and connect via a proxy while using `fetch()`. * * ```ts * const caCert = await Deno.readTextFile("./ca.pem"); @@ -892,7 +1122,9 @@ declare namespace Deno { * ``` * * ```ts - * const client = Deno.createHttpClient({ proxy: { url: "http://myproxy.com:8080" } }); + * const client = Deno.createHttpClient({ + * proxy: { url: "http://myproxy.com:8080" } + * }); * const response = await fetch("https://myserver.com", { client }); * ``` * @@ -909,35 +1141,48 @@ declare namespace Deno { * @category Network */ export interface DatagramConn extends AsyncIterable<[Uint8Array, Addr]> { - /** Waits for and resolves to the next message to the `UDPConn`. */ + /** Waits for and resolves to the next message to the instance. + * + * Messages are received in the format of a tuple containing the data array + * and the address information. + */ receive(p?: Uint8Array): Promise<[Uint8Array, Addr]>; - /** Sends a message to the target. */ + /** Sends a message to the target via the connection. The method resolves + * with the number of bytes sent. */ send(p: Uint8Array, addr: Addr): Promise<number>; /** Close closes the socket. Any pending message promises will be rejected * with errors. */ close(): void; - /** Return the address of the `UDPConn`. */ + /** Return the address of the instance. */ readonly addr: Addr; [Symbol.asyncIterator](): AsyncIterableIterator<[Uint8Array, Addr]>; } /** **UNSTABLE**: New API, yet to be vetted. * + * Unstable options which can be set when opening a Unix listener via + * {@linkcode Deno.listen} or {@linkcode Deno.listenDatagram}. + * * @category Network */ export interface UnixListenOptions { - /** A Path to the Unix Socket. */ + /** A path to the Unix Socket. */ path: string; } /** **UNSTABLE**: New API, yet to be vetted. * + * Unstable options which can be set when opening a datagram listener via + * {@linkcode Deno.listenDatagram}. + * * @category Network */ export interface UdpListenOptions extends ListenOptions { /** When `true` the specified address will be reused, even if another * process has already bound a socket on it. This effectively steals the - * socket from the listener. Defaults to `false`. */ + * socket from the listener. + * + * Defaults to `false`. */ reuseAddress?: boolean; } @@ -1030,12 +1275,26 @@ declare namespace Deno { * @tags allow-net, allow-read * @category Network */ - export function connect( - options: ConnectOptions, - ): Promise<TcpConn>; - export function connect( - options: UnixConnectOptions, - ): Promise<UnixConn>; + export function connect(options: ConnectOptions): Promise<TcpConn>; + /** **UNSTABLE**: New API, yet to be vetted. + * + * Connects to the hostname (default is "127.0.0.1") and port on the named + * transport (default is "tcp"), and resolves to the connection (`Conn`). + * + * ```ts + * const conn1 = await Deno.connect({ port: 80 }); + * const conn2 = await Deno.connect({ hostname: "192.0.2.1", port: 80 }); + * const conn3 = await Deno.connect({ hostname: "[2001:db8::1]", port: 80 }); + * const conn4 = await Deno.connect({ hostname: "golang.org", port: 80, transport: "tcp" }); + * const conn5 = await Deno.connect({ path: "/foo/bar.sock", transport: "unix" }); + * ``` + * + * Requires `allow-net` permission for "tcp" and `allow-read` for "unix". + * + * @tags allow-net, allow-read + * @category Network + */ + export function connect(options: UnixConnectOptions): Promise<UnixConn>; /** **UNSTABLE**: New API, yet to be vetted. * @@ -1164,8 +1423,8 @@ declare namespace Deno { /** **UNSTABLE**: New API, yet to be vetted. * - * Acquire an advisory file-system lock for the provided file. `exclusive` - * defaults to `false`. + * Acquire an advisory file-system lock synchronously for the provided file. + * `exclusive` defaults to `false`. * * @category File System */ @@ -1181,7 +1440,7 @@ declare namespace Deno { /** **UNSTABLE**: New API, yet to be vetted. * - * Release an advisory file-system lock for the provided file. + * Release an advisory file-system lock for the provided file synchronously. * * @category File System */ @@ -1201,24 +1460,28 @@ declare namespace Deno { /** **UNSTABLE**: New API, yet to be vetted. * + * Options which can be set when calling {@linkcode Deno.serve}. + * * @category HTTP Server */ export interface ServeOptions extends Partial<Deno.ListenOptions> { - /** An AbortSignal to close the server and all connections. */ + /** An {@linkcode AbortSignal} to close the server and all connections. */ signal?: AbortSignal; - /** Sets SO_REUSEPORT on Linux. */ + /** Sets `SO_REUSEPORT` on POSIX systems. */ reusePort?: boolean; /** The handler to invoke when route handlers throw an error. */ onError?: (error: unknown) => Response | Promise<Response>; - /** The callback which is called when the server started listening */ + /** The callback which is called when the server starts listening. */ onListen?: (params: { hostname: string; port: number }) => void; } /** **UNSTABLE**: New API, yet to be vetted. * + * Additional options which are used when opening a TLS (HTTPS) server. + * * @category HTTP Server */ export interface ServeTlsOptions extends ServeOptions { @@ -1243,25 +1506,25 @@ declare namespace Deno { * Serves HTTP requests with the given handler. * * You can specify an object with a port and hostname option, which is the - * address to listen on. The default is port 9000 on hostname "127.0.0.1". + * address to listen on. The default is port `9000` on hostname `"127.0.0.1"`. * - * The below example serves with the port 9000. + * The below example serves with the port `9000`. * * ```ts * Deno.serve((_req) => new Response("Hello, world")); * ``` * * You can change the address to listen on using the `hostname` and `port` - * options. The below example serves on port 3000. + * options. The below example serves on port `3000`. * * ```ts * Deno.serve({ port: 3000 }, (_req) => new Response("Hello, world")); * ``` * - * You can stop the server with an AbortSignal. The abort signal needs to be - * passed as the `signal` option in the options bag. The server aborts when - * the abort signal is aborted. To wait for the server to close, await the - * promise returned from the `Deno.serve` API. + * You can stop the server with an {@linkcode AbortSignal}. The abort signal + * needs to be passed as the `signal` option in the options bag. The server + * aborts when the abort signal is aborted. To wait for the server to close, + * await the promise returned from the `Deno.serve` API. * * ```ts * const ac = new AbortController(); @@ -1273,9 +1536,9 @@ declare namespace Deno { * ac.abort(); * ``` * - * By default `Deno.serve` prints the message `Listening on http://<hostname>:<port>/` - * on start up. If you like to change this behaviour, you can specify a custom - * `onListen` callback. + * By default `Deno.serve` prints the message + * `Listening on http://<hostname>:<port>/` on listening. If you like to + * change this behavior, you can specify a custom `onListen` callback. * * ```ts * Deno.serve({ @@ -1301,19 +1564,137 @@ declare namespace Deno { handler: ServeHandler, options?: ServeOptions | ServeTlsOptions, ): Promise<void>; + /** **UNSTABLE**: New API, yet to be vetted. + * + * Serves HTTP requests with the given handler. + * + * You can specify an object with a port and hostname option, which is the + * address to listen on. The default is port `9000` on hostname `"127.0.0.1"`. + * + * The below example serves with the port `9000`. + * + * ```ts + * Deno.serve((_req) => new Response("Hello, world")); + * ``` + * + * You can change the address to listen on using the `hostname` and `port` + * options. The below example serves on port `3000`. + * + * ```ts + * Deno.serve({ port: 3000 }, (_req) => new Response("Hello, world")); + * ``` + * + * You can stop the server with an {@linkcode AbortSignal}. The abort signal + * needs to be passed as the `signal` option in the options bag. The server + * aborts when the abort signal is aborted. To wait for the server to close, + * await the promise returned from the `Deno.serve` API. + * + * ```ts + * const ac = new AbortController(); + * + * Deno.serve({ signal: ac.signal }, (_req) => new Response("Hello, world")) + * .then(() => console.log("Server closed")); + * + * console.log("Closing server..."); + * ac.abort(); + * ``` + * + * By default `Deno.serve` prints the message + * `Listening on http://<hostname>:<port>/` on listening. If you like to + * change this behavior, you can specify a custom `onListen` callback. + * + * ```ts + * Deno.serve({ + * onListen({ port, hostname }) { + * console.log(`Server started at http://${hostname}:${port}`); + * // ... more info specific to your server .. + * }, + * handler: (_req) => new Response("Hello, world"), + * }); + * ``` + * + * To enable TLS you must specify the `key` and `cert` options. + * + * ```ts + * const cert = "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n"; + * const key = "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n"; + * Deno.serve({ cert, key }, (_req) => new Response("Hello, world")); + * ``` + * + * @category HTTP Server + */ export function serve( options: ServeOptions | ServeTlsOptions, handler: ServeHandler, ): Promise<void>; + /** **UNSTABLE**: New API, yet to be vetted. + * + * Serves HTTP requests with the given handler. + * + * You can specify an object with a port and hostname option, which is the + * address to listen on. The default is port `9000` on hostname `"127.0.0.1"`. + * + * The below example serves with the port `9000`. + * + * ```ts + * Deno.serve((_req) => new Response("Hello, world")); + * ``` + * + * You can change the address to listen on using the `hostname` and `port` + * options. The below example serves on port `3000`. + * + * ```ts + * Deno.serve({ port: 3000 }, (_req) => new Response("Hello, world")); + * ``` + * + * You can stop the server with an {@linkcode AbortSignal}. The abort signal + * needs to be passed as the `signal` option in the options bag. The server + * aborts when the abort signal is aborted. To wait for the server to close, + * await the promise returned from the `Deno.serve` API. + * + * ```ts + * const ac = new AbortController(); + * + * Deno.serve({ signal: ac.signal }, (_req) => new Response("Hello, world")) + * .then(() => console.log("Server closed")); + * + * console.log("Closing server..."); + * ac.abort(); + * ``` + * + * By default `Deno.serve` prints the message + * `Listening on http://<hostname>:<port>/` on listening. If you like to + * change this behavior, you can specify a custom `onListen` callback. + * + * ```ts + * Deno.serve({ + * onListen({ port, hostname }) { + * console.log(`Server started at http://${hostname}:${port}`); + * // ... more info specific to your server .. + * }, + * handler: (_req) => new Response("Hello, world"), + * }); + * ``` + * + * To enable TLS you must specify the `key` and `cert` options. + * + * ```ts + * const cert = "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n"; + * const key = "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n"; + * Deno.serve({ cert, key }, (_req) => new Response("Hello, world")); + * ``` + * + * @category HTTP Server + */ export function serve( options: ServeInit & (ServeOptions | ServeTlsOptions), ): Promise<void>; /** **UNSTABLE**: New API, yet to be vetted. * - * Allows "hijacking" the connection that the request is associated with. - * This can be used to implement protocols that build on top of HTTP (eg. - * WebSockets). + * Allows "hijacking" the connection that the request is associated with. This + * can be used to implement protocols that build on top of HTTP (eg. + * {@linkcode WebSocket}). * * The returned promise returns underlying connection and first packet * received. The promise shouldn't be awaited before responding to the @@ -1328,8 +1709,8 @@ declare namespace Deno { * } * ``` * - * This method can only be called on requests originating the `Deno.serveHttp` - * server. + * This method can only be called on requests originating the + * {@linkcode Deno.serveHttp} server. * * @category HTTP Server */ @@ -1341,15 +1722,16 @@ declare namespace Deno { * * Allows "hijacking" the connection that the request is associated with. * This can be used to implement protocols that build on top of HTTP (eg. - * WebSockets). - - * Unlike `Deno.upgradeHttp` this function does not require that you respond - * to the request with a `Response` object. Instead this function returns - * the underlying connection and first packet received immediately, and then - * the caller is responsible for writing the response to the connection. + * {@linkcode WebSocket}). + * + * Unlike {@linkcode Deno.upgradeHttp} this function does not require that you + * respond to the request with a {@linkcode Response} object. Instead this + * function returns the underlying connection and first packet received + * immediately, and then the caller is responsible for writing the response to + * the connection. * - * This method can only be called on requests originating the `Deno.serve` - * server. + * This method can only be called on requests originating the + * {@linkcode Deno.serve} server. * * @category HTTP Server */ @@ -1357,6 +1739,9 @@ declare namespace Deno { /** **UNSTABLE**: New API, yet to be vetted. * + * Options which can be set when calling {@linkcode Deno.spawn}, + * {@linkcode Deno.spawnSync}, and {@linkcode Deno.spawnChild}. + * * @category Sub Process */ export interface SpawnOptions { @@ -1364,40 +1749,50 @@ declare namespace Deno { args?: string[]; /** * The working directory of the process. - * If not specified, the cwd of the parent process is used. + * + * If not specified, the `cwd` of the parent process is used. */ cwd?: string | URL; /** * Clear environmental variables from parent process. - * Doesn't guarantee that only `opt.env` variables are present, - * as the OS may set environmental variables for processes. + * + * Doesn't guarantee that only `env` variables are present, as the OS may + * set environmental variables for processes. */ clearEnv?: boolean; /** Environmental variables to pass to the subprocess. */ env?: Record<string, string>; /** - * Sets the child process’s user ID. This translates to a setuid call - * in the child process. Failure in the setuid call will cause the spawn to fail. + * Sets the child process’s user ID. This translates to a setuid call in the + * child process. Failure in the set uid call will cause the spawn to fail. */ uid?: number; /** Similar to `uid`, but sets the group ID of the child process. */ gid?: number; /** - * An AbortSignal that allows closing the process using the corresponding - * AbortController by sending the process a SIGTERM signal. - * Not supported in spawnSync. + * An {@linkcode AbortSignal} that allows closing the process using the + * corresponding {@linkcode AbortController} by sending the process a + * SIGTERM signal. + * + * Not supported in {@linkcode Deno.spawnSync}. */ signal?: AbortSignal; - /** Defaults to "null". */ + /** How `stdin` of the spawned process should be handled. + * + * Defaults to `"null"`. */ stdin?: "piped" | "inherit" | "null"; - /** Defaults to "piped". */ + /** How `stdout` of the spawned process should be handled. + * + * Defaults to `"piped"`. */ stdout?: "piped" | "inherit" | "null"; - /** Defaults to "piped". */ + /** How `stderr` of the spawned process should be handled. + * + * Defaults to "piped". */ stderr?: "piped" | "inherit" | "null"; /** Skips quoting and escaping of the arguments on windows. This option - * is ignored on non-windows platforms. Defaults to "false". */ + * is ignored on non-windows platforms. Defaults to `false`. */ windowsRawArguments?: boolean; } @@ -1408,8 +1803,8 @@ declare namespace Deno { * If any stdio options are not set to `"piped"`, accessing the corresponding * field on the `Child` or its `SpawnOutput` will throw a `TypeError`. * - * If stdin is set to `"piped"`, the stdin WritableStream needs to be closed - * manually. + * If `stdin` is set to `"piped"`, the `stdin` {@linkcode WritableStream} + * needs to be closed manually. * * ```ts * const child = Deno.spawnChild(Deno.execPath(), { @@ -1437,6 +1832,9 @@ declare namespace Deno { /** **UNSTABLE**: New API, yet to be vetted. * + * The interface for handling a child process returned from + * {@linkcode Deno.spawnChild}. + * * @category Sub Process */ export class Child { @@ -1447,19 +1845,26 @@ declare namespace Deno { /** Get the status of the child. */ readonly status: Promise<ChildStatus>; - /** Waits for the child to exit completely, returning all its output and status. */ + /** Waits for the child to exit completely, returning all its output and + * status. */ output(): Promise<SpawnOutput>; - /** Kills the process with given Signal. Defaults to SIGTERM. */ + /** Kills the process with given {@linkcode Deno.Signal}. Defaults to + * `"SIGTERM"`. */ kill(signo?: Signal): void; + /** Ensure that the status of the child process prevents the Deno process + * from exiting. */ ref(): void; + /** Ensure that the status of the child process does not block the Deno + * process from exiting. */ unref(): void; } /** **UNSTABLE**: New API, yet to be vetted. * - * Executes a subprocess, waiting for it to finish and - * collecting all of its output. + * Executes a subprocess, waiting for it to finish and collecting all of its + * output. + * * Will throw an error if `stdin: "piped"` is passed. * * If options `stdout` or `stderr` are not set to `"piped"`, accessing the @@ -1488,6 +1893,7 @@ declare namespace Deno { * * Synchronously executes a subprocess, waiting for it to finish and * collecting all of its output. + * * Will throw an error if `stdin: "piped"` is passed. * * If options `stdout` or `stderr` are not set to `"piped"`, accessing the @@ -1517,23 +1923,38 @@ declare namespace Deno { * @category Sub Process */ export interface ChildStatus { + /** If the child process exits with a 0 status code, `success` will be set + * to `true`, otherwise `false`. */ success: boolean; + /** The exit code of the child process. */ code: number; + /** The signal associated with the child process, present if + * {@linkcode Deno.spawn} was called. */ signal: Signal | null; } /** **UNSTABLE**: New API, yet to be vetted. * + * The interface returned from calling {@linkcode Deno.spawn} or + * {@linkcode Deno.spawnSync} which represents the result of spawning the + * child process. + * * @category Sub Process */ export interface SpawnOutput extends ChildStatus { - get stdout(): Uint8Array; - get stderr(): Uint8Array; + /** The buffered output from the child processes `stdout`. */ + readonly stdout: Uint8Array; + /** The buffered output from the child processes `stderr`. */ + readonly stderr: Uint8Array; } } /** **UNSTABLE**: New API, yet to be vetted. * + * The [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) + * which also supports setting a {@linkcode Deno.HttpClient} which provides a + * way to connect via proxies and use custom TLS certificates. + * * @tags allow-net, allow-read * @category Fetch API */ @@ -1552,10 +1973,13 @@ declare interface WorkerOptions { * Configure permissions options to change the level of access the worker will * have. By default it will have no permissions. Note that the permissions * of a worker can't be extended beyond its parent's permissions reach. - * - "inherit" will take the permissions of the thread the worker is created in - * - "none" will use the default behavior and have no permission - * - You can provide a list of routes relative to the file the worker - * is created in to limit the access of the worker (read/write permissions only) + * + * - `"inherit"` will take the permissions of the thread the worker is created + * in. + * - `"none"` will use the default behavior and have no permission + * - A list of routes can be provided that are relative to the file the worker + * is created in to limit the access of the worker (read/write permissions + * only) * * Example: * |