2024-01-01 14:58:21 -05:00
|
|
|
|
// Copyright 2018-2024 the Deno authors. All rights reserved. MIT license.
|
2020-04-30 11:23:40 -04:00
|
|
|
|
|
|
|
|
|
/// <reference no-default-lib="true" />
|
|
|
|
|
/// <reference lib="deno.ns" />
|
2023-05-14 07:27:14 -04:00
|
|
|
|
/// <reference lib="deno.broadcast_channel" />
|
2024-01-21 15:51:45 -05:00
|
|
|
|
/// <reference lib="deno.webgpu" />
|
2024-01-14 19:26:57 -05:00
|
|
|
|
/// <reference lib="esnext" />
|
|
|
|
|
/// <reference lib="es2022.intl" />
|
2020-04-30 11:23:40 -04:00
|
|
|
|
|
|
|
|
|
declare namespace Deno {
|
2022-07-04 01:41:52 -04:00
|
|
|
|
export {}; // stop default export type behavior
|
|
|
|
|
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
2020-04-30 11:23:40 -04:00
|
|
|
|
*
|
|
|
|
|
* Retrieve the process umask. If `mask` is provided, sets the process umask.
|
|
|
|
|
* This call always returns what the umask was before the call.
|
|
|
|
|
*
|
2020-05-16 15:23:48 -04:00
|
|
|
|
* ```ts
|
|
|
|
|
* console.log(Deno.umask()); // e.g. 18 (0o022)
|
|
|
|
|
* const prevUmaskValue = Deno.umask(0o077); // e.g. 18 (0o022)
|
|
|
|
|
* console.log(Deno.umask()); // e.g. 63 (0o077)
|
|
|
|
|
* ```
|
2020-04-30 11:23:40 -04:00
|
|
|
|
*
|
2022-09-15 10:37:35 -04:00
|
|
|
|
* This API is under consideration to determine if permissions are required to
|
|
|
|
|
* call it.
|
|
|
|
|
*
|
2022-10-26 09:53:48 -04:00
|
|
|
|
* *Note*: This API is not implemented on Windows
|
2022-08-16 23:12:24 -04:00
|
|
|
|
*
|
|
|
|
|
* @category File System
|
2020-04-30 11:23:40 -04:00
|
|
|
|
*/
|
|
|
|
|
export function umask(mask?: number): number;
|
|
|
|
|
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
|
|
|
|
*
|
|
|
|
|
* All plain number types for interfacing with foreign functions.
|
2022-08-16 23:12:24 -04:00
|
|
|
|
*
|
|
|
|
|
* @category FFI
|
|
|
|
|
*/
|
2022-06-20 22:50:33 -04:00
|
|
|
|
type NativeNumberType =
|
2021-08-06 17:28:10 -04:00
|
|
|
|
| "u8"
|
|
|
|
|
| "i8"
|
|
|
|
|
| "u16"
|
|
|
|
|
| "i16"
|
|
|
|
|
| "u32"
|
|
|
|
|
| "i32"
|
2022-06-20 22:50:33 -04:00
|
|
|
|
| "f32"
|
|
|
|
|
| "f64";
|
|
|
|
|
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
|
|
|
|
*
|
|
|
|
|
* All BigInt number types for interfacing with foreign functions.
|
2022-08-16 23:12:24 -04:00
|
|
|
|
*
|
|
|
|
|
* @category FFI
|
|
|
|
|
*/
|
2022-06-20 22:50:33 -04:00
|
|
|
|
type NativeBigIntType =
|
2021-08-06 17:28:10 -04:00
|
|
|
|
| "u64"
|
|
|
|
|
| "i64"
|
|
|
|
|
| "usize"
|
2022-06-20 22:50:33 -04:00
|
|
|
|
| "isize";
|
|
|
|
|
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
2022-10-26 09:53:48 -04:00
|
|
|
|
*
|
|
|
|
|
* The native boolean type for interfacing to foreign functions.
|
2022-09-15 10:37:35 -04:00
|
|
|
|
*
|
|
|
|
|
* @category FFI
|
|
|
|
|
*/
|
2022-09-04 23:26:52 -04:00
|
|
|
|
type NativeBooleanType = "bool";
|
|
|
|
|
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
2022-10-26 09:53:48 -04:00
|
|
|
|
*
|
|
|
|
|
* The native pointer type for interfacing to foreign functions.
|
2022-09-15 10:37:35 -04:00
|
|
|
|
*
|
|
|
|
|
* @category FFI
|
|
|
|
|
*/
|
2022-06-20 22:50:33 -04:00
|
|
|
|
type NativePointerType = "pointer";
|
2021-08-06 17:28:10 -04:00
|
|
|
|
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
2022-10-26 09:53:48 -04:00
|
|
|
|
*
|
|
|
|
|
* The native buffer type for interfacing to foreign functions.
|
2022-09-15 10:37:35 -04:00
|
|
|
|
*
|
|
|
|
|
* @category FFI
|
|
|
|
|
*/
|
2022-08-22 23:46:43 -04:00
|
|
|
|
type NativeBufferType = "buffer";
|
|
|
|
|
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
2022-10-26 09:53:48 -04:00
|
|
|
|
*
|
|
|
|
|
* The native function type for interfacing with foreign functions.
|
2022-09-15 10:37:35 -04:00
|
|
|
|
*
|
|
|
|
|
* @category FFI
|
|
|
|
|
*/
|
2022-06-20 22:50:33 -04:00
|
|
|
|
type NativeFunctionType = "function";
|
|
|
|
|
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
2022-10-26 09:53:48 -04:00
|
|
|
|
*
|
|
|
|
|
* The native void type for interfacing with foreign functions.
|
2022-09-15 10:37:35 -04:00
|
|
|
|
*
|
|
|
|
|
* @category FFI
|
|
|
|
|
*/
|
2022-06-20 22:50:33 -04:00
|
|
|
|
type NativeVoidType = "void";
|
|
|
|
|
|
2023-01-07 22:58:10 -05:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
2023-01-24 09:03:46 -05:00
|
|
|
|
*
|
2023-01-07 22:58:10 -05:00
|
|
|
|
* The native struct type for interfacing with foreign functions.
|
2023-04-24 16:24:18 -04:00
|
|
|
|
*
|
|
|
|
|
* @category FFI
|
2023-01-07 22:58:10 -05:00
|
|
|
|
*/
|
|
|
|
|
type NativeStructType = { readonly struct: readonly NativeType[] };
|
|
|
|
|
|
2023-08-21 04:06:26 -04:00
|
|
|
|
/** @category FFI */
|
|
|
|
|
const brand: unique symbol;
|
|
|
|
|
|
|
|
|
|
/** @category FFI */
|
|
|
|
|
export type NativeU8Enum<T extends number> = "u8" & { [brand]: T };
|
|
|
|
|
/** @category FFI */
|
|
|
|
|
export type NativeI8Enum<T extends number> = "i8" & { [brand]: T };
|
|
|
|
|
/** @category FFI */
|
|
|
|
|
export type NativeU16Enum<T extends number> = "u16" & { [brand]: T };
|
|
|
|
|
/** @category FFI */
|
|
|
|
|
export type NativeI16Enum<T extends number> = "i16" & { [brand]: T };
|
|
|
|
|
/** @category FFI */
|
|
|
|
|
export type NativeU32Enum<T extends number> = "u32" & { [brand]: T };
|
|
|
|
|
/** @category FFI */
|
|
|
|
|
export type NativeI32Enum<T extends number> = "i32" & { [brand]: T };
|
|
|
|
|
/** @category FFI */
|
|
|
|
|
export type NativeTypedPointer<T extends PointerObject> = "pointer" & {
|
|
|
|
|
[brand]: T;
|
|
|
|
|
};
|
|
|
|
|
export type NativeTypedFunction<T extends UnsafeCallbackDefinition> =
|
|
|
|
|
& "function"
|
|
|
|
|
& {
|
|
|
|
|
[brand]: T;
|
|
|
|
|
};
|
|
|
|
|
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
|
|
|
|
*
|
2022-10-26 09:53:48 -04:00
|
|
|
|
* All supported types for interfacing with foreign functions.
|
2022-08-16 23:12:24 -04:00
|
|
|
|
*
|
|
|
|
|
* @category FFI
|
|
|
|
|
*/
|
2022-06-20 22:50:33 -04:00
|
|
|
|
export type NativeType =
|
|
|
|
|
| NativeNumberType
|
|
|
|
|
| NativeBigIntType
|
2022-09-04 23:26:52 -04:00
|
|
|
|
| NativeBooleanType
|
2022-06-20 22:50:33 -04:00
|
|
|
|
| NativePointerType
|
2022-08-22 23:46:43 -04:00
|
|
|
|
| NativeBufferType
|
2023-01-07 22:58:10 -05:00
|
|
|
|
| NativeFunctionType
|
|
|
|
|
| NativeStructType;
|
2022-06-20 22:50:33 -04:00
|
|
|
|
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
|
|
|
|
*
|
|
|
|
|
* @category FFI
|
|
|
|
|
*/
|
2022-06-20 22:50:33 -04:00
|
|
|
|
export type NativeResultType = NativeType | NativeVoidType;
|
|
|
|
|
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
|
|
|
|
*
|
|
|
|
|
* Type conversion for foreign symbol parameters and unsafe callback return
|
2022-08-16 23:12:24 -04:00
|
|
|
|
* types.
|
|
|
|
|
*
|
|
|
|
|
* @category FFI
|
|
|
|
|
*/
|
2023-01-07 22:58:10 -05:00
|
|
|
|
type ToNativeType<T extends NativeType = NativeType> = T extends
|
|
|
|
|
NativeStructType ? BufferSource
|
2023-08-21 04:06:26 -04:00
|
|
|
|
: T extends NativeNumberType ? T extends NativeU8Enum<infer U> ? U
|
|
|
|
|
: T extends NativeI8Enum<infer U> ? U
|
|
|
|
|
: T extends NativeU16Enum<infer U> ? U
|
|
|
|
|
: T extends NativeI16Enum<infer U> ? U
|
|
|
|
|
: T extends NativeU32Enum<infer U> ? U
|
|
|
|
|
: T extends NativeI32Enum<infer U> ? U
|
|
|
|
|
: number
|
|
|
|
|
: T extends NativeBigIntType ? number | bigint
|
|
|
|
|
: T extends NativeBooleanType ? boolean
|
|
|
|
|
: T extends NativePointerType
|
|
|
|
|
? T extends NativeTypedPointer<infer U> ? U | null : PointerValue
|
|
|
|
|
: T extends NativeFunctionType
|
|
|
|
|
? T extends NativeTypedFunction<infer U> ? PointerValue<U> | null
|
|
|
|
|
: PointerValue
|
|
|
|
|
: T extends NativeBufferType ? BufferSource | null
|
|
|
|
|
: never;
|
2022-06-20 22:50:33 -04:00
|
|
|
|
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
|
|
|
|
*
|
|
|
|
|
* Type conversion for unsafe callback return types.
|
2022-08-16 23:12:24 -04:00
|
|
|
|
*
|
|
|
|
|
* @category FFI
|
|
|
|
|
*/
|
2022-06-20 22:50:33 -04:00
|
|
|
|
type ToNativeResultType<T extends NativeResultType = NativeResultType> =
|
2023-01-07 22:58:10 -05:00
|
|
|
|
T extends NativeStructType ? BufferSource
|
2023-08-21 04:06:26 -04:00
|
|
|
|
: T extends NativeNumberType ? T extends NativeU8Enum<infer U> ? U
|
|
|
|
|
: T extends NativeI8Enum<infer U> ? U
|
|
|
|
|
: T extends NativeU16Enum<infer U> ? U
|
|
|
|
|
: T extends NativeI16Enum<infer U> ? U
|
|
|
|
|
: T extends NativeU32Enum<infer U> ? U
|
|
|
|
|
: T extends NativeI32Enum<infer U> ? U
|
|
|
|
|
: number
|
|
|
|
|
: T extends NativeBigIntType ? number | bigint
|
|
|
|
|
: T extends NativeBooleanType ? boolean
|
|
|
|
|
: T extends NativePointerType
|
|
|
|
|
? T extends NativeTypedPointer<infer U> ? U | null : PointerValue
|
|
|
|
|
: T extends NativeFunctionType
|
|
|
|
|
? T extends NativeTypedFunction<infer U> ? PointerObject<U> | null
|
|
|
|
|
: PointerValue
|
|
|
|
|
: T extends NativeBufferType ? BufferSource | null
|
|
|
|
|
: T extends NativeVoidType ? void
|
|
|
|
|
: never;
|
2022-06-27 08:41:58 -04:00
|
|
|
|
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
2022-10-26 09:53:48 -04:00
|
|
|
|
*
|
|
|
|
|
* A utility type for conversion of parameter types of foreign functions.
|
2022-09-15 10:37:35 -04:00
|
|
|
|
*
|
|
|
|
|
* @category FFI
|
|
|
|
|
*/
|
2022-06-27 08:41:58 -04:00
|
|
|
|
type ToNativeParameterTypes<T extends readonly NativeType[]> =
|
|
|
|
|
//
|
|
|
|
|
[(T[number])[]] extends [T] ? ToNativeType<T[number]>[]
|
|
|
|
|
: [readonly (T[number])[]] extends [T]
|
|
|
|
|
? readonly ToNativeType<T[number]>[]
|
|
|
|
|
: T extends readonly [...NativeType[]] ? {
|
|
|
|
|
[K in keyof T]: ToNativeType<T[K]>;
|
|
|
|
|
}
|
2022-06-20 22:50:33 -04:00
|
|
|
|
: never;
|
|
|
|
|
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
|
|
|
|
*
|
|
|
|
|
* Type conversion for foreign symbol return types and unsafe callback
|
2022-08-16 23:12:24 -04:00
|
|
|
|
* parameters.
|
|
|
|
|
*
|
|
|
|
|
* @category FFI
|
|
|
|
|
*/
|
2023-01-07 22:58:10 -05:00
|
|
|
|
type FromNativeType<T extends NativeType = NativeType> = T extends
|
|
|
|
|
NativeStructType ? Uint8Array
|
2023-08-21 04:06:26 -04:00
|
|
|
|
: T extends NativeNumberType ? T extends NativeU8Enum<infer U> ? U
|
|
|
|
|
: T extends NativeI8Enum<infer U> ? U
|
|
|
|
|
: T extends NativeU16Enum<infer U> ? U
|
|
|
|
|
: T extends NativeI16Enum<infer U> ? U
|
|
|
|
|
: T extends NativeU32Enum<infer U> ? U
|
|
|
|
|
: T extends NativeI32Enum<infer U> ? U
|
|
|
|
|
: number
|
|
|
|
|
: T extends NativeBigIntType ? number | bigint
|
|
|
|
|
: T extends NativeBooleanType ? boolean
|
|
|
|
|
: T extends NativePointerType
|
|
|
|
|
? T extends NativeTypedPointer<infer U> ? U | null : PointerValue
|
|
|
|
|
: T extends NativeBufferType ? PointerValue
|
|
|
|
|
: T extends NativeFunctionType
|
|
|
|
|
? T extends NativeTypedFunction<infer U> ? PointerObject<U> | null
|
|
|
|
|
: PointerValue
|
|
|
|
|
: never;
|
2022-06-20 22:50:33 -04:00
|
|
|
|
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
|
|
|
|
*
|
|
|
|
|
* Type conversion for foreign symbol return types.
|
2022-08-16 23:12:24 -04:00
|
|
|
|
*
|
|
|
|
|
* @category FFI
|
|
|
|
|
*/
|
2022-06-20 22:50:33 -04:00
|
|
|
|
type FromNativeResultType<T extends NativeResultType = NativeResultType> =
|
2023-01-07 22:58:10 -05:00
|
|
|
|
T extends NativeStructType ? Uint8Array
|
2023-08-21 04:06:26 -04:00
|
|
|
|
: T extends NativeNumberType ? T extends NativeU8Enum<infer U> ? U
|
|
|
|
|
: T extends NativeI8Enum<infer U> ? U
|
|
|
|
|
: T extends NativeU16Enum<infer U> ? U
|
|
|
|
|
: T extends NativeI16Enum<infer U> ? U
|
|
|
|
|
: T extends NativeU32Enum<infer U> ? U
|
|
|
|
|
: T extends NativeI32Enum<infer U> ? U
|
|
|
|
|
: number
|
|
|
|
|
: T extends NativeBigIntType ? number | bigint
|
|
|
|
|
: T extends NativeBooleanType ? boolean
|
|
|
|
|
: T extends NativePointerType
|
|
|
|
|
? T extends NativeTypedPointer<infer U> ? U | null : PointerValue
|
|
|
|
|
: T extends NativeBufferType ? PointerValue
|
|
|
|
|
: T extends NativeFunctionType
|
|
|
|
|
? T extends NativeTypedFunction<infer U> ? PointerObject<U> | null
|
|
|
|
|
: PointerValue
|
|
|
|
|
: T extends NativeVoidType ? void
|
|
|
|
|
: never;
|
2022-06-27 08:41:58 -04:00
|
|
|
|
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
|
|
|
|
*
|
|
|
|
|
* @category FFI
|
|
|
|
|
*/
|
2022-06-27 08:41:58 -04:00
|
|
|
|
type FromNativeParameterTypes<
|
|
|
|
|
T extends readonly NativeType[],
|
|
|
|
|
> =
|
|
|
|
|
//
|
|
|
|
|
[(T[number])[]] extends [T] ? FromNativeType<T[number]>[]
|
|
|
|
|
: [readonly (T[number])[]] extends [T]
|
|
|
|
|
? readonly FromNativeType<T[number]>[]
|
|
|
|
|
: T extends readonly [...NativeType[]] ? {
|
|
|
|
|
[K in keyof T]: FromNativeType<T[K]>;
|
|
|
|
|
}
|
2022-06-20 22:50:33 -04:00
|
|
|
|
: never;
|
|
|
|
|
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
|
|
|
|
*
|
2022-10-26 09:53:48 -04:00
|
|
|
|
* The interface for a foreign function as defined by its parameter and result
|
|
|
|
|
* types.
|
2022-08-16 23:12:24 -04:00
|
|
|
|
*
|
|
|
|
|
* @category FFI
|
|
|
|
|
*/
|
2022-01-10 10:33:25 -05:00
|
|
|
|
export interface ForeignFunction<
|
2022-06-20 22:50:33 -04:00
|
|
|
|
Parameters extends readonly NativeType[] = readonly NativeType[],
|
|
|
|
|
Result extends NativeResultType = NativeResultType,
|
2022-01-10 10:33:25 -05:00
|
|
|
|
NonBlocking extends boolean = boolean,
|
|
|
|
|
> {
|
2022-10-26 09:53:48 -04:00
|
|
|
|
/** Name of the symbol.
|
|
|
|
|
*
|
|
|
|
|
* Defaults to the key name in symbols object. */
|
2022-01-11 01:21:16 -05:00
|
|
|
|
name?: string;
|
2022-10-26 09:53:48 -04:00
|
|
|
|
/** The parameters of the foreign function. */
|
2022-01-10 10:33:25 -05:00
|
|
|
|
parameters: Parameters;
|
2022-10-26 09:53:48 -04:00
|
|
|
|
/** The result (return value) of the foreign function. */
|
2022-01-10 10:33:25 -05:00
|
|
|
|
result: Result;
|
2022-10-26 09:53:48 -04:00
|
|
|
|
/** When `true`, function calls will run on a dedicated blocking thread and
|
|
|
|
|
* will return a `Promise` resolving to the `result`. */
|
2022-01-10 10:33:25 -05:00
|
|
|
|
nonblocking?: NonBlocking;
|
2022-10-26 09:53:48 -04:00
|
|
|
|
/** When `true`, function calls can safely callback into JavaScript or
|
|
|
|
|
* trigger a garbage collection event.
|
|
|
|
|
*
|
2022-12-13 08:14:41 -05:00
|
|
|
|
* @default {false} */
|
2022-07-09 09:11:07 -04:00
|
|
|
|
callback?: boolean;
|
2023-04-03 14:32:21 -04:00
|
|
|
|
/** When `true`, dlopen will not fail if the symbol is not found.
|
|
|
|
|
* Instead, the symbol will be set to `null`.
|
|
|
|
|
*
|
|
|
|
|
* @default {false} */
|
|
|
|
|
optional?: boolean;
|
2021-08-06 17:28:10 -04:00
|
|
|
|
}
|
|
|
|
|
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
|
|
|
|
*
|
|
|
|
|
* @category FFI
|
|
|
|
|
*/
|
2022-02-18 07:21:19 -05:00
|
|
|
|
export interface ForeignStatic<Type extends NativeType = NativeType> {
|
|
|
|
|
/** Name of the symbol, defaults to the key name in symbols object. */
|
|
|
|
|
name?: string;
|
2022-10-26 09:53:48 -04:00
|
|
|
|
/** The type of the foreign static value. */
|
2022-06-20 22:50:33 -04:00
|
|
|
|
type: Type;
|
2023-04-03 14:32:21 -04:00
|
|
|
|
/** When `true`, dlopen will not fail if the symbol is not found.
|
|
|
|
|
* Instead, the symbol will be set to `null`.
|
|
|
|
|
*
|
|
|
|
|
* @default {false} */
|
|
|
|
|
optional?: boolean;
|
2022-02-18 07:21:19 -05:00
|
|
|
|
}
|
|
|
|
|
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
|
|
|
|
*
|
|
|
|
|
* A foreign library interface descriptor.
|
2022-08-16 23:12:24 -04:00
|
|
|
|
*
|
|
|
|
|
* @category FFI
|
|
|
|
|
*/
|
2022-02-18 07:21:19 -05:00
|
|
|
|
export interface ForeignLibraryInterface {
|
|
|
|
|
[name: string]: ForeignFunction | ForeignStatic;
|
2022-01-10 10:33:25 -05:00
|
|
|
|
}
|
|
|
|
|
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
|
|
|
|
*
|
2022-10-26 09:53:48 -04:00
|
|
|
|
* A utility type that infers a foreign symbol.
|
2022-08-16 23:12:24 -04:00
|
|
|
|
*
|
|
|
|
|
* @category FFI
|
|
|
|
|
*/
|
2022-02-18 07:21:19 -05:00
|
|
|
|
type StaticForeignSymbol<T extends ForeignFunction | ForeignStatic> =
|
2022-06-20 22:50:33 -04:00
|
|
|
|
T extends ForeignFunction ? FromForeignFunction<T>
|
|
|
|
|
: T extends ForeignStatic ? FromNativeType<T["type"]>
|
2022-02-18 07:21:19 -05:00
|
|
|
|
: never;
|
2022-01-10 10:33:25 -05:00
|
|
|
|
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
|
|
|
|
*
|
|
|
|
|
* @category FFI
|
|
|
|
|
*/
|
2022-06-20 22:50:33 -04:00
|
|
|
|
type FromForeignFunction<T extends ForeignFunction> = T["parameters"] extends
|
|
|
|
|
readonly [] ? () => StaticForeignSymbolReturnType<T>
|
|
|
|
|
: (
|
|
|
|
|
...args: ToNativeParameterTypes<T["parameters"]>
|
|
|
|
|
) => StaticForeignSymbolReturnType<T>;
|
|
|
|
|
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
|
|
|
|
*
|
|
|
|
|
* @category FFI
|
|
|
|
|
*/
|
2022-06-20 22:50:33 -04:00
|
|
|
|
type StaticForeignSymbolReturnType<T extends ForeignFunction> =
|
|
|
|
|
ConditionalAsync<T["nonblocking"], FromNativeResultType<T["result"]>>;
|
|
|
|
|
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
|
|
|
|
*
|
|
|
|
|
* @category FFI
|
|
|
|
|
*/
|
2022-01-10 10:33:25 -05:00
|
|
|
|
type ConditionalAsync<IsAsync extends boolean | undefined, T> =
|
|
|
|
|
IsAsync extends true ? Promise<T> : T;
|
|
|
|
|
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
|
|
|
|
*
|
2022-10-26 09:53:48 -04:00
|
|
|
|
* A utility type that infers a foreign library interface.
|
2022-08-16 23:12:24 -04:00
|
|
|
|
*
|
|
|
|
|
* @category FFI
|
|
|
|
|
*/
|
2022-02-18 07:21:19 -05:00
|
|
|
|
type StaticForeignLibraryInterface<T extends ForeignLibraryInterface> = {
|
2023-04-03 14:32:21 -04:00
|
|
|
|
[K in keyof T]: T[K]["optional"] extends true
|
|
|
|
|
? StaticForeignSymbol<T[K]> | null
|
|
|
|
|
: StaticForeignSymbol<T[K]>;
|
2022-01-10 10:33:25 -05:00
|
|
|
|
};
|
|
|
|
|
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
|
|
|
|
*
|
2023-08-21 04:06:26 -04:00
|
|
|
|
* A non-null pointer, represented as an object
|
|
|
|
|
* at runtime. The object's prototype is `null`
|
|
|
|
|
* and cannot be changed. The object cannot be
|
|
|
|
|
* assigned to either and is thus entirely read-only.
|
|
|
|
|
*
|
|
|
|
|
* To interact with memory through a pointer use the
|
|
|
|
|
* {@linkcode UnsafePointerView} class. To create a
|
|
|
|
|
* pointer from an address or the get the address of
|
|
|
|
|
* a pointer use the static methods of the
|
|
|
|
|
* {@linkcode UnsafePointer} class.
|
|
|
|
|
*
|
|
|
|
|
* @category FFI
|
|
|
|
|
*/
|
|
|
|
|
export type PointerObject<T = unknown> = { [brand]: T };
|
|
|
|
|
|
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
2022-07-24 06:41:11 -04:00
|
|
|
|
*
|
2023-08-21 04:06:26 -04:00
|
|
|
|
* Pointers are represented either with a {@linkcode PointerObject}
|
|
|
|
|
* object or a `null` if the pointer is null.
|
2022-08-16 23:12:24 -04:00
|
|
|
|
*
|
|
|
|
|
* @category FFI
|
2022-07-24 06:41:11 -04:00
|
|
|
|
*/
|
2023-08-21 04:06:26 -04:00
|
|
|
|
export type PointerValue<T = unknown> = null | PointerObject<T>;
|
2022-07-24 06:41:11 -04:00
|
|
|
|
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
2022-09-15 08:09:23 -04:00
|
|
|
|
*
|
2023-08-21 04:06:26 -04:00
|
|
|
|
* A collection of static functions for interacting with pointer objects.
|
2022-08-16 23:12:24 -04:00
|
|
|
|
*
|
|
|
|
|
* @category FFI
|
2021-12-15 09:41:49 -05:00
|
|
|
|
*/
|
|
|
|
|
export class UnsafePointer {
|
2023-03-18 08:25:06 -04:00
|
|
|
|
/** Create a pointer from a numeric value. This one is <i>really</i> dangerous! */
|
2023-08-21 04:06:26 -04:00
|
|
|
|
static create<T = unknown>(value: number | bigint): PointerValue<T>;
|
2023-02-22 12:32:38 -05:00
|
|
|
|
/** Returns `true` if the two pointers point to the same address. */
|
2023-08-21 04:06:26 -04:00
|
|
|
|
static equals<T = unknown>(a: PointerValue<T>, b: PointerValue<T>): boolean;
|
2022-10-26 09:53:48 -04:00
|
|
|
|
/** Return the direct memory pointer to the typed array in memory. */
|
2023-08-21 04:06:26 -04:00
|
|
|
|
static of<T = unknown>(
|
|
|
|
|
value: Deno.UnsafeCallback | BufferSource,
|
|
|
|
|
): PointerValue<T>;
|
2023-02-22 12:32:38 -05:00
|
|
|
|
/** Return a new pointer offset from the original by `offset` bytes. */
|
2023-08-21 04:06:26 -04:00
|
|
|
|
static offset<T = unknown>(
|
|
|
|
|
value: PointerObject,
|
2023-03-21 17:01:53 -04:00
|
|
|
|
offset: number,
|
2023-08-21 04:06:26 -04:00
|
|
|
|
): PointerValue<T>;
|
2023-02-22 12:32:38 -05:00
|
|
|
|
/** Get the numeric value of a pointer */
|
|
|
|
|
static value(value: PointerValue): number | bigint;
|
2021-12-15 09:41:49 -05:00
|
|
|
|
}
|
|
|
|
|
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
2022-09-15 08:09:23 -04:00
|
|
|
|
*
|
|
|
|
|
* An unsafe pointer view to a memory location as specified by the `pointer`
|
2022-10-26 09:53:48 -04:00
|
|
|
|
* 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).
|
2022-08-16 23:12:24 -04:00
|
|
|
|
*
|
|
|
|
|
* @category FFI
|
2021-12-15 09:41:49 -05:00
|
|
|
|
*/
|
|
|
|
|
export class UnsafePointerView {
|
2023-08-21 04:06:26 -04:00
|
|
|
|
constructor(pointer: PointerObject);
|
2021-12-15 09:41:49 -05:00
|
|
|
|
|
2023-08-21 04:06:26 -04:00
|
|
|
|
pointer: PointerObject;
|
2021-12-15 09:41:49 -05:00
|
|
|
|
|
2022-09-04 23:26:52 -04:00
|
|
|
|
/** Gets a boolean at the specified byte offset from the pointer. */
|
|
|
|
|
getBool(offset?: number): boolean;
|
2022-10-26 09:53:48 -04:00
|
|
|
|
/** Gets an unsigned 8-bit integer at the specified byte offset from the
|
|
|
|
|
* pointer. */
|
2021-12-15 09:41:49 -05:00
|
|
|
|
getUint8(offset?: number): number;
|
2022-10-26 09:53:48 -04:00
|
|
|
|
/** Gets a signed 8-bit integer at the specified byte offset from the
|
|
|
|
|
* pointer. */
|
2021-12-15 09:41:49 -05:00
|
|
|
|
getInt8(offset?: number): number;
|
2022-10-26 09:53:48 -04:00
|
|
|
|
/** Gets an unsigned 16-bit integer at the specified byte offset from the
|
|
|
|
|
* pointer. */
|
2021-12-15 09:41:49 -05:00
|
|
|
|
getUint16(offset?: number): number;
|
2022-10-26 09:53:48 -04:00
|
|
|
|
/** Gets a signed 16-bit integer at the specified byte offset from the
|
|
|
|
|
* pointer. */
|
2021-12-15 09:41:49 -05:00
|
|
|
|
getInt16(offset?: number): number;
|
2022-10-26 09:53:48 -04:00
|
|
|
|
/** Gets an unsigned 32-bit integer at the specified byte offset from the
|
|
|
|
|
* pointer. */
|
2021-12-15 09:41:49 -05:00
|
|
|
|
getUint32(offset?: number): number;
|
2022-10-26 09:53:48 -04:00
|
|
|
|
/** Gets a signed 32-bit integer at the specified byte offset from the
|
|
|
|
|
* pointer. */
|
2021-12-15 09:41:49 -05:00
|
|
|
|
getInt32(offset?: number): number;
|
2022-10-26 09:53:48 -04:00
|
|
|
|
/** Gets an unsigned 64-bit integer at the specified byte offset from the
|
|
|
|
|
* pointer. */
|
2023-02-22 12:32:38 -05:00
|
|
|
|
getBigUint64(offset?: number): number | bigint;
|
2022-10-26 09:53:48 -04:00
|
|
|
|
/** Gets a signed 64-bit integer at the specified byte offset from the
|
|
|
|
|
* pointer. */
|
2023-02-22 12:32:38 -05:00
|
|
|
|
getBigInt64(offset?: number): number | bigint;
|
2022-10-26 09:53:48 -04:00
|
|
|
|
/** Gets a signed 32-bit float at the specified byte offset from the
|
|
|
|
|
* pointer. */
|
2021-12-15 09:41:49 -05:00
|
|
|
|
getFloat32(offset?: number): number;
|
2022-10-26 09:53:48 -04:00
|
|
|
|
/** Gets a signed 64-bit float at the specified byte offset from the
|
|
|
|
|
* pointer. */
|
2021-12-15 09:41:49 -05:00
|
|
|
|
getFloat64(offset?: number): number;
|
2023-02-22 12:32:38 -05:00
|
|
|
|
/** Gets a pointer at the specified byte offset from the pointer */
|
2023-08-21 04:06:26 -04:00
|
|
|
|
getPointer<T = unknown>(offset?: number): PointerValue<T>;
|
2022-10-26 09:53:48 -04:00
|
|
|
|
/** Gets a C string (`null` terminated string) at the specified byte offset
|
|
|
|
|
* from the pointer. */
|
2021-12-15 09:41:49 -05:00
|
|
|
|
getCString(offset?: number): string;
|
2022-10-26 09:53:48 -04:00
|
|
|
|
/** Gets a C string (`null` terminated string) at the specified byte offset
|
|
|
|
|
* from the specified pointer. */
|
2023-03-21 17:01:53 -04:00
|
|
|
|
static getCString(
|
2023-08-21 04:06:26 -04:00
|
|
|
|
pointer: PointerObject,
|
2023-03-21 17:01:53 -04:00
|
|
|
|
offset?: number,
|
|
|
|
|
): string;
|
2022-10-26 09:53:48 -04:00
|
|
|
|
/** Gets an `ArrayBuffer` of length `byteLength` at the specified byte
|
|
|
|
|
* offset from the pointer. */
|
2021-12-15 09:41:49 -05:00
|
|
|
|
getArrayBuffer(byteLength: number, offset?: number): ArrayBuffer;
|
2022-10-26 09:53:48 -04:00
|
|
|
|
/** Gets an `ArrayBuffer` of length `byteLength` at the specified byte
|
|
|
|
|
* offset from the specified pointer. */
|
2022-08-05 12:27:12 -04:00
|
|
|
|
static getArrayBuffer(
|
2023-08-21 04:06:26 -04:00
|
|
|
|
pointer: PointerObject,
|
2022-08-05 12:27:12 -04:00
|
|
|
|
byteLength: number,
|
|
|
|
|
offset?: number,
|
|
|
|
|
): ArrayBuffer;
|
2022-10-26 09:53:48 -04:00
|
|
|
|
/** 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. */
|
2022-10-20 23:46:57 -04:00
|
|
|
|
copyInto(destination: BufferSource, offset?: number): void;
|
2022-10-26 09:53:48 -04:00
|
|
|
|
/** 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. */
|
2022-08-05 12:27:12 -04:00
|
|
|
|
static copyInto(
|
2023-08-21 04:06:26 -04:00
|
|
|
|
pointer: PointerObject,
|
2022-10-20 23:46:57 -04:00
|
|
|
|
destination: BufferSource,
|
2022-08-05 12:27:12 -04:00
|
|
|
|
offset?: number,
|
|
|
|
|
): void;
|
2021-12-15 09:41:49 -05:00
|
|
|
|
}
|
|
|
|
|
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
2022-09-15 08:09:23 -04:00
|
|
|
|
*
|
2022-10-26 09:53:48 -04:00
|
|
|
|
* An unsafe pointer to a function, for calling functions that are not present
|
|
|
|
|
* as symbols.
|
2022-08-16 23:12:24 -04:00
|
|
|
|
*
|
|
|
|
|
* @category FFI
|
2022-01-12 06:38:26 -05:00
|
|
|
|
*/
|
|
|
|
|
export class UnsafeFnPointer<Fn extends ForeignFunction> {
|
2022-10-26 09:53:48 -04:00
|
|
|
|
/** The pointer to the function. */
|
2023-08-21 04:06:26 -04:00
|
|
|
|
pointer: PointerObject<Fn>;
|
2022-10-26 09:53:48 -04:00
|
|
|
|
/** The definition of the function. */
|
2022-01-12 06:38:26 -05:00
|
|
|
|
definition: Fn;
|
|
|
|
|
|
2023-08-21 04:06:26 -04:00
|
|
|
|
constructor(pointer: PointerObject<Fn>, definition: Const<Fn>);
|
|
|
|
|
/** @deprecated Properly type {@linkcode pointer} using {@linkcode NativeTypedFunction} or {@linkcode UnsafeCallbackDefinition} types. */
|
|
|
|
|
constructor(pointer: PointerObject, definition: Const<Fn>);
|
2022-01-12 06:38:26 -05:00
|
|
|
|
|
2022-10-26 09:53:48 -04:00
|
|
|
|
/** Call the foreign function. */
|
2022-06-20 22:50:33 -04:00
|
|
|
|
call: FromForeignFunction<Fn>;
|
2022-01-12 06:38:26 -05:00
|
|
|
|
}
|
|
|
|
|
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
2022-10-26 09:53:48 -04:00
|
|
|
|
*
|
|
|
|
|
* Definition of a unsafe callback function.
|
2022-09-15 10:37:35 -04:00
|
|
|
|
*
|
|
|
|
|
* @category FFI
|
|
|
|
|
*/
|
2022-06-20 07:06:04 -04:00
|
|
|
|
export interface UnsafeCallbackDefinition<
|
|
|
|
|
Parameters extends readonly NativeType[] = readonly NativeType[],
|
2022-06-20 22:50:33 -04:00
|
|
|
|
Result extends NativeResultType = NativeResultType,
|
2022-06-20 07:06:04 -04:00
|
|
|
|
> {
|
2022-10-26 09:53:48 -04:00
|
|
|
|
/** The parameters of the callbacks. */
|
2022-06-20 07:06:04 -04:00
|
|
|
|
parameters: Parameters;
|
2022-10-26 09:53:48 -04:00
|
|
|
|
/** The current result of the callback. */
|
2022-06-20 07:06:04 -04:00
|
|
|
|
result: Result;
|
|
|
|
|
}
|
|
|
|
|
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
2022-10-26 09:53:48 -04:00
|
|
|
|
*
|
|
|
|
|
* An unsafe callback function.
|
2022-09-15 10:37:35 -04:00
|
|
|
|
*
|
|
|
|
|
* @category FFI
|
|
|
|
|
*/
|
2022-06-20 07:06:04 -04:00
|
|
|
|
type UnsafeCallbackFunction<
|
|
|
|
|
Parameters extends readonly NativeType[] = readonly NativeType[],
|
2022-06-20 22:50:33 -04:00
|
|
|
|
Result extends NativeResultType = NativeResultType,
|
|
|
|
|
> = Parameters extends readonly [] ? () => ToNativeResultType<Result> : (
|
|
|
|
|
...args: FromNativeParameterTypes<Parameters>
|
|
|
|
|
) => ToNativeResultType<Result>;
|
2022-06-20 07:06:04 -04:00
|
|
|
|
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
2022-09-15 08:09:23 -04:00
|
|
|
|
*
|
2022-10-26 09:53:48 -04:00
|
|
|
|
* An unsafe function pointer for passing JavaScript functions as C function
|
|
|
|
|
* pointers to foreign function calls.
|
2022-06-20 07:06:04 -04:00
|
|
|
|
*
|
|
|
|
|
* The function pointer remains valid until the `close()` method is called.
|
2022-06-28 05:23:36 -04:00
|
|
|
|
*
|
2023-02-22 14:09:59 -05:00
|
|
|
|
* All `UnsafeCallback` are always thread safe in that they can be called from
|
|
|
|
|
* foreign threads without crashing. However, they do not wake up the Deno event
|
|
|
|
|
* loop by default.
|
2023-02-24 17:36:07 -05:00
|
|
|
|
*
|
2023-02-22 14:09:59 -05:00
|
|
|
|
* If a callback is to be called from foreign threads, use the `threadSafe()`
|
|
|
|
|
* static constructor or explicitly call `ref()` to have the callback wake up
|
|
|
|
|
* the Deno event loop when called from foreign threads. This also stops
|
|
|
|
|
* Deno's process from exiting while the callback still exists and is not
|
|
|
|
|
* unref'ed.
|
|
|
|
|
*
|
|
|
|
|
* Use `deref()` to then allow Deno's process to exit. Calling `deref()` on
|
|
|
|
|
* a ref'ed callback does not stop it from waking up the Deno event loop when
|
|
|
|
|
* called from foreign threads.
|
2022-08-16 23:12:24 -04:00
|
|
|
|
*
|
|
|
|
|
* @category FFI
|
2022-06-20 07:06:04 -04:00
|
|
|
|
*/
|
|
|
|
|
export class UnsafeCallback<
|
2023-03-21 17:01:53 -04:00
|
|
|
|
Definition extends UnsafeCallbackDefinition = UnsafeCallbackDefinition,
|
2022-06-20 07:06:04 -04:00
|
|
|
|
> {
|
|
|
|
|
constructor(
|
2022-12-03 07:15:35 -05:00
|
|
|
|
definition: Const<Definition>,
|
2022-06-20 22:50:33 -04:00
|
|
|
|
callback: UnsafeCallbackFunction<
|
|
|
|
|
Definition["parameters"],
|
|
|
|
|
Definition["result"]
|
2023-03-21 17:01:53 -04:00
|
|
|
|
>,
|
2022-06-20 07:06:04 -04:00
|
|
|
|
);
|
|
|
|
|
|
2022-10-26 09:53:48 -04:00
|
|
|
|
/** The pointer to the unsafe callback. */
|
2023-08-21 04:06:26 -04:00
|
|
|
|
readonly pointer: PointerObject<Definition>;
|
2022-10-26 09:53:48 -04:00
|
|
|
|
/** The definition of the unsafe callback. */
|
2023-02-22 14:09:59 -05:00
|
|
|
|
readonly definition: Definition;
|
2022-10-26 09:53:48 -04:00
|
|
|
|
/** The callback function. */
|
2023-02-22 14:09:59 -05:00
|
|
|
|
readonly callback: UnsafeCallbackFunction<
|
2022-06-20 22:50:33 -04:00
|
|
|
|
Definition["parameters"],
|
|
|
|
|
Definition["result"]
|
|
|
|
|
>;
|
2022-06-20 07:06:04 -04:00
|
|
|
|
|
2022-06-28 05:23:36 -04:00
|
|
|
|
/**
|
2023-02-22 14:09:59 -05:00
|
|
|
|
* Creates an {@linkcode UnsafeCallback} and calls `ref()` once to allow it to
|
|
|
|
|
* wake up the Deno event loop when called from foreign threads.
|
|
|
|
|
*
|
|
|
|
|
* This also stops Deno's process from exiting while the callback still
|
|
|
|
|
* exists and is not unref'ed.
|
|
|
|
|
*/
|
|
|
|
|
static threadSafe<
|
2023-03-21 17:01:53 -04:00
|
|
|
|
Definition extends UnsafeCallbackDefinition = UnsafeCallbackDefinition,
|
2023-02-22 14:09:59 -05:00
|
|
|
|
>(
|
|
|
|
|
definition: Const<Definition>,
|
|
|
|
|
callback: UnsafeCallbackFunction<
|
|
|
|
|
Definition["parameters"],
|
|
|
|
|
Definition["result"]
|
2023-03-21 17:01:53 -04:00
|
|
|
|
>,
|
2023-02-22 14:09:59 -05:00
|
|
|
|
): UnsafeCallback<Definition>;
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* Increments the callback's reference counting and returns the new
|
2022-10-26 09:53:48 -04:00
|
|
|
|
* reference count.
|
2022-06-28 05:23:36 -04:00
|
|
|
|
*
|
2023-02-22 14:09:59 -05:00
|
|
|
|
* After `ref()` has been called, the callback always wakes up the
|
|
|
|
|
* Deno event loop when called from foreign threads.
|
|
|
|
|
*
|
|
|
|
|
* If the callback's reference count is non-zero, it keeps Deno's
|
2022-10-26 09:53:48 -04:00
|
|
|
|
* process from exiting.
|
2022-06-28 05:23:36 -04:00
|
|
|
|
*/
|
2022-10-15 09:49:46 -04:00
|
|
|
|
ref(): number;
|
2022-06-28 05:23:36 -04:00
|
|
|
|
|
|
|
|
|
/**
|
2023-02-22 14:09:59 -05:00
|
|
|
|
* Decrements the callback's reference counting and returns the new
|
2022-10-26 09:53:48 -04:00
|
|
|
|
* reference count.
|
2023-02-24 17:36:07 -05:00
|
|
|
|
*
|
2023-02-22 14:09:59 -05:00
|
|
|
|
* Calling `unref()` does not stop a callback from waking up the Deno
|
|
|
|
|
* event loop when called from foreign threads.
|
2022-06-28 05:23:36 -04:00
|
|
|
|
*
|
2023-02-22 14:09:59 -05:00
|
|
|
|
* If the callback's reference counter is zero, it no longer keeps
|
2022-10-26 09:53:48 -04:00
|
|
|
|
* Deno's process from exiting.
|
2022-06-28 05:23:36 -04:00
|
|
|
|
*/
|
2022-10-15 09:49:46 -04:00
|
|
|
|
unref(): number;
|
2022-06-28 05:23:36 -04:00
|
|
|
|
|
|
|
|
|
/**
|
2022-10-26 09:53:48 -04:00
|
|
|
|
* Removes the C function pointer associated with this instance.
|
|
|
|
|
*
|
2023-02-22 14:09:59 -05:00
|
|
|
|
* Continuing to use the instance or the C function pointer after closing
|
|
|
|
|
* the `UnsafeCallback` will lead to errors and crashes.
|
2022-06-28 05:23:36 -04:00
|
|
|
|
*
|
2023-02-22 14:09:59 -05:00
|
|
|
|
* Calling this method sets the callback's reference counting to zero,
|
|
|
|
|
* stops the callback from waking up the Deno event loop when called from
|
|
|
|
|
* foreign threads and no longer keeps Deno's process from exiting.
|
2022-06-28 05:23:36 -04:00
|
|
|
|
*/
|
2022-06-20 07:06:04 -04:00
|
|
|
|
close(): void;
|
|
|
|
|
}
|
|
|
|
|
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
|
|
|
|
*
|
2022-10-26 09:53:48 -04:00
|
|
|
|
* A dynamic library resource. Use {@linkcode Deno.dlopen} to load a dynamic
|
|
|
|
|
* library and return this interface.
|
2022-09-07 20:47:47 -04:00
|
|
|
|
*
|
|
|
|
|
* @category FFI
|
|
|
|
|
*/
|
2022-02-18 07:21:19 -05:00
|
|
|
|
export interface DynamicLibrary<S extends ForeignLibraryInterface> {
|
2022-10-26 09:53:48 -04:00
|
|
|
|
/** All of the registered library along with functions for calling them. */
|
2022-02-18 07:21:19 -05:00
|
|
|
|
symbols: StaticForeignLibraryInterface<S>;
|
2022-10-26 09:53:48 -04:00
|
|
|
|
/** 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.
|
|
|
|
|
*/
|
2021-08-06 17:28:10 -04:00
|
|
|
|
close(): void;
|
|
|
|
|
}
|
|
|
|
|
|
2022-12-03 07:15:35 -05:00
|
|
|
|
/**
|
|
|
|
|
* This magic code used to implement better type hints for {@linkcode Deno.dlopen}
|
2023-04-24 16:24:18 -04:00
|
|
|
|
*
|
|
|
|
|
* @category FFI
|
2022-12-03 07:15:35 -05:00
|
|
|
|
*/
|
|
|
|
|
type Cast<A, B> = A extends B ? A : B;
|
2023-04-24 16:24:18 -04:00
|
|
|
|
/** @category FFI */
|
2022-12-03 07:15:35 -05:00
|
|
|
|
type Const<T> = Cast<
|
|
|
|
|
T,
|
|
|
|
|
| (T extends string | number | bigint | boolean ? T : never)
|
|
|
|
|
| { [K in keyof T]: Const<T[K]> }
|
|
|
|
|
| []
|
|
|
|
|
>;
|
|
|
|
|
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
2022-09-15 08:09:23 -04:00
|
|
|
|
*
|
2022-10-26 09:53:48 -04:00
|
|
|
|
* 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.
|
2022-08-16 23:12:24 -04:00
|
|
|
|
*
|
2022-12-13 08:14:41 -05:00
|
|
|
|
* @example Given a C library which exports a foreign function named `add()`
|
2022-10-26 09:53:48 -04:00
|
|
|
|
*
|
|
|
|
|
* ```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
|
2022-08-16 23:12:24 -04:00
|
|
|
|
* @category FFI
|
2021-07-11 21:12:26 -04:00
|
|
|
|
*/
|
2022-02-18 07:21:19 -05:00
|
|
|
|
export function dlopen<S extends ForeignLibraryInterface>(
|
2021-08-24 09:09:00 -04:00
|
|
|
|
filename: string | URL,
|
2022-12-03 07:15:35 -05:00
|
|
|
|
symbols: Const<S>,
|
2021-08-06 17:28:10 -04:00
|
|
|
|
): DynamicLibrary<S>;
|
2021-07-11 21:12:26 -04:00
|
|
|
|
|
2024-01-21 15:51:45 -05:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
|
|
|
|
*
|
|
|
|
|
* Creates a presentable WebGPU surface from given window and
|
|
|
|
|
* display handles.
|
|
|
|
|
*
|
|
|
|
|
* The parameters correspond to the table below:
|
|
|
|
|
*
|
|
|
|
|
* | system | winHandle | displayHandle |
|
|
|
|
|
* | ----------------- | ------------- | --------------- |
|
|
|
|
|
* | "cocoa" (macOS) | `NSView*` | - |
|
|
|
|
|
* | "win32" (Windows) | `HWND` | `HINSTANCE` |
|
|
|
|
|
* | "x11" (Linux) | Xlib `Window` | Xlib `Display*` |
|
|
|
|
|
*
|
|
|
|
|
* @category WebGPU
|
|
|
|
|
*/
|
|
|
|
|
export class UnsafeWindowSurface {
|
|
|
|
|
constructor(
|
|
|
|
|
system: "cocoa" | "win32" | "x11",
|
|
|
|
|
windowHandle: UnsafePointerView,
|
|
|
|
|
displayHandle: UnsafePointerView | null,
|
|
|
|
|
);
|
|
|
|
|
getContext(context: "webgpu"): GPUCanvasContext;
|
|
|
|
|
present(): void;
|
|
|
|
|
}
|
|
|
|
|
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
|
|
|
|
*
|
2022-10-26 09:53:48 -04:00
|
|
|
|
* These are unstable options which can be used with {@linkcode Deno.run}.
|
2022-11-13 17:27:47 -05:00
|
|
|
|
*
|
|
|
|
|
* @category Sub Process
|
2022-10-26 09:53:48 -04:00
|
|
|
|
*/
|
|
|
|
|
interface UnstableRunOptions extends RunOptions {
|
|
|
|
|
/** If `true`, clears the environment variables before executing the
|
2022-12-13 08:14:41 -05:00
|
|
|
|
* sub-process.
|
|
|
|
|
*
|
|
|
|
|
* @default {false} */
|
2022-10-26 09:53:48 -04:00
|
|
|
|
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
|
2022-09-15 10:37:35 -04:00
|
|
|
|
* @category Sub Process
|
|
|
|
|
*/
|
2022-10-26 09:53:48 -04:00
|
|
|
|
export function run<T extends UnstableRunOptions = UnstableRunOptions>(
|
|
|
|
|
opt: T,
|
|
|
|
|
): Process<T>;
|
2021-08-04 15:47:43 -04:00
|
|
|
|
|
2022-09-15 08:09:23 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
2022-09-15 10:37:35 -04:00
|
|
|
|
*
|
2022-10-26 09:53:48 -04:00
|
|
|
|
* A custom `HttpClient` for use with {@linkcode fetch} function. This is
|
|
|
|
|
* designed to allow custom certificates or proxies to be used with `fetch()`.
|
2020-08-10 16:41:51 -04:00
|
|
|
|
*
|
2022-12-13 08:14:41 -05:00
|
|
|
|
* @example ```ts
|
2021-09-30 03:26:15 -04:00
|
|
|
|
* const caCert = await Deno.readTextFile("./ca.pem");
|
|
|
|
|
* const client = Deno.createHttpClient({ caCerts: [ caCert ] });
|
2020-08-05 14:44:03 -04:00
|
|
|
|
* const req = await fetch("https://myserver.com", { client });
|
|
|
|
|
* ```
|
2022-08-16 23:12:24 -04:00
|
|
|
|
*
|
|
|
|
|
* @category Fetch API
|
2020-08-05 14:44:03 -04:00
|
|
|
|
*/
|
2023-12-06 02:52:59 -05:00
|
|
|
|
export interface HttpClient extends Disposable {
|
2022-10-26 09:53:48 -04:00
|
|
|
|
/** The resource ID associated with the client. */
|
2020-08-05 14:44:03 -04:00
|
|
|
|
rid: number;
|
2022-10-26 09:53:48 -04:00
|
|
|
|
/** Close the HTTP client. */
|
2020-08-05 14:44:03 -04:00
|
|
|
|
close(): void;
|
|
|
|
|
}
|
|
|
|
|
|
2022-09-15 08:09:23 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
2022-09-15 10:37:35 -04:00
|
|
|
|
*
|
2022-10-26 09:53:48 -04:00
|
|
|
|
* The options used when creating a {@linkcode Deno.HttpClient}.
|
2022-08-16 23:12:24 -04:00
|
|
|
|
*
|
|
|
|
|
* @category Fetch API
|
2020-08-05 14:44:03 -04:00
|
|
|
|
*/
|
2021-04-09 20:41:59 -04:00
|
|
|
|
export interface CreateHttpClientOptions {
|
2021-09-30 03:26:15 -04:00
|
|
|
|
/** A list of root certificates that will be used in addition to the
|
|
|
|
|
* default root certificates to verify the peer's certificate.
|
|
|
|
|
*
|
|
|
|
|
* Must be in PEM format. */
|
|
|
|
|
caCerts?: string[];
|
|
|
|
|
/** A HTTP proxy to use for new connections. */
|
2021-06-21 23:21:57 -04:00
|
|
|
|
proxy?: Proxy;
|
2021-09-30 03:26:15 -04:00
|
|
|
|
/** PEM formatted client certificate chain. */
|
2021-08-25 08:25:12 -04:00
|
|
|
|
certChain?: string;
|
2021-09-30 03:26:15 -04:00
|
|
|
|
/** PEM formatted (RSA or PKCS8) private key of client certificate. */
|
2021-08-25 08:25:12 -04:00
|
|
|
|
privateKey?: string;
|
2023-05-20 21:43:54 -04:00
|
|
|
|
/** Sets the maximum numer of idle connections per host allowed in the pool. */
|
|
|
|
|
poolMaxIdlePerHost?: number;
|
|
|
|
|
/** Set an optional timeout for idle sockets being kept-alive.
|
|
|
|
|
* Set to false to disable the timeout. */
|
|
|
|
|
poolIdleTimeout?: number | false;
|
2023-05-21 15:52:45 -04:00
|
|
|
|
/**
|
|
|
|
|
* Whether HTTP/1.1 is allowed or not.
|
|
|
|
|
*
|
|
|
|
|
* @default {true}
|
|
|
|
|
*/
|
2023-05-20 21:43:54 -04:00
|
|
|
|
http1?: boolean;
|
2023-05-21 15:52:45 -04:00
|
|
|
|
/** Whether HTTP/2 is allowed or not.
|
|
|
|
|
*
|
|
|
|
|
* @default {true}
|
|
|
|
|
*/
|
2023-05-20 21:43:54 -04:00
|
|
|
|
http2?: boolean;
|
2023-07-28 03:01:06 -04:00
|
|
|
|
/** Whether setting the host header is allowed or not.
|
|
|
|
|
*
|
|
|
|
|
* @default {false}
|
|
|
|
|
*/
|
|
|
|
|
allowHost?: boolean;
|
2021-06-21 23:21:57 -04:00
|
|
|
|
}
|
|
|
|
|
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
2022-10-26 09:53:48 -04:00
|
|
|
|
*
|
|
|
|
|
* The definition of a proxy when specifying
|
|
|
|
|
* {@linkcode Deno.CreateHttpClientOptions}.
|
2022-09-15 10:37:35 -04:00
|
|
|
|
*
|
|
|
|
|
* @category Fetch API
|
|
|
|
|
*/
|
2021-06-21 23:21:57 -04:00
|
|
|
|
export interface Proxy {
|
2022-10-26 09:53:48 -04:00
|
|
|
|
/** The string URL of the proxy server to use. */
|
2021-06-21 23:21:57 -04:00
|
|
|
|
url: string;
|
2022-10-26 09:53:48 -04:00
|
|
|
|
/** The basic auth credentials to be used against the proxy server. */
|
2021-06-21 23:21:57 -04:00
|
|
|
|
basicAuth?: BasicAuth;
|
|
|
|
|
}
|
|
|
|
|
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
2022-10-26 09:53:48 -04:00
|
|
|
|
*
|
|
|
|
|
* Basic authentication credentials to be used with a {@linkcode Deno.Proxy}
|
|
|
|
|
* server when specifying {@linkcode Deno.CreateHttpClientOptions}.
|
2022-09-15 10:37:35 -04:00
|
|
|
|
*
|
|
|
|
|
* @category Fetch API
|
|
|
|
|
*/
|
2021-06-21 23:21:57 -04:00
|
|
|
|
export interface BasicAuth {
|
2022-10-26 09:53:48 -04:00
|
|
|
|
/** The username to be used against the proxy server. */
|
2021-06-21 23:21:57 -04:00
|
|
|
|
username: string;
|
2022-10-26 09:53:48 -04:00
|
|
|
|
/** The password to be used against the proxy server. */
|
2021-06-21 23:21:57 -04:00
|
|
|
|
password: string;
|
2020-08-05 14:44:03 -04:00
|
|
|
|
}
|
|
|
|
|
|
2022-09-15 08:09:23 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
2022-09-15 10:37:35 -04:00
|
|
|
|
*
|
2023-11-08 21:34:57 -05:00
|
|
|
|
* Create a custom HttpClient to use with {@linkcode fetch}. This is an
|
2022-10-26 09:53:48 -04:00
|
|
|
|
* extension of the web platform Fetch API which allows Deno to use custom
|
|
|
|
|
* TLS certificates and connect via a proxy while using `fetch()`.
|
2020-08-10 16:41:51 -04:00
|
|
|
|
*
|
2022-12-13 08:14:41 -05:00
|
|
|
|
* @example ```ts
|
2021-09-30 03:26:15 -04:00
|
|
|
|
* const caCert = await Deno.readTextFile("./ca.pem");
|
|
|
|
|
* const client = Deno.createHttpClient({ caCerts: [ caCert ] });
|
2021-06-21 23:21:57 -04:00
|
|
|
|
* const response = await fetch("https://myserver.com", { client });
|
|
|
|
|
* ```
|
|
|
|
|
*
|
2022-12-13 08:14:41 -05:00
|
|
|
|
* @example ```ts
|
2022-10-26 09:53:48 -04:00
|
|
|
|
* const client = Deno.createHttpClient({
|
|
|
|
|
* proxy: { url: "http://myproxy.com:8080" }
|
|
|
|
|
* });
|
2021-06-21 23:21:57 -04:00
|
|
|
|
* const response = await fetch("https://myserver.com", { client });
|
2020-08-05 14:44:03 -04:00
|
|
|
|
* ```
|
2022-08-16 23:12:24 -04:00
|
|
|
|
*
|
|
|
|
|
* @category Fetch API
|
2020-08-05 14:44:03 -04:00
|
|
|
|
*/
|
|
|
|
|
export function createHttpClient(
|
|
|
|
|
options: CreateHttpClientOptions,
|
|
|
|
|
): HttpClient;
|
2020-08-31 14:29:43 -04:00
|
|
|
|
|
2023-03-20 17:27:00 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
|
|
|
|
*
|
|
|
|
|
* Represents membership of a IPv4 multicast group.
|
|
|
|
|
*
|
|
|
|
|
* @category Network
|
|
|
|
|
*/
|
|
|
|
|
interface MulticastV4Membership {
|
|
|
|
|
/** Leaves the multicast group. */
|
|
|
|
|
leave: () => Promise<void>;
|
|
|
|
|
/** Sets the multicast loopback option. If enabled, multicast packets will be looped back to the local socket. */
|
|
|
|
|
setLoopback: (loopback: boolean) => Promise<void>;
|
|
|
|
|
/** Sets the time-to-live of outgoing multicast packets for this socket. */
|
|
|
|
|
setTTL: (ttl: number) => Promise<void>;
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
|
|
|
|
*
|
|
|
|
|
* Represents membership of a IPv6 multicast group.
|
|
|
|
|
*
|
|
|
|
|
* @category Network
|
|
|
|
|
*/
|
|
|
|
|
interface MulticastV6Membership {
|
|
|
|
|
/** Leaves the multicast group. */
|
|
|
|
|
leave: () => Promise<void>;
|
|
|
|
|
/** Sets the multicast loopback option. If enabled, multicast packets will be looped back to the local socket. */
|
|
|
|
|
setLoopback: (loopback: boolean) => Promise<void>;
|
|
|
|
|
}
|
|
|
|
|
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
2022-09-15 08:09:23 -04:00
|
|
|
|
*
|
|
|
|
|
* A generic transport listener for message-oriented protocols.
|
2022-08-16 23:12:24 -04:00
|
|
|
|
*
|
|
|
|
|
* @category Network
|
|
|
|
|
*/
|
2021-08-31 05:25:15 -04:00
|
|
|
|
export interface DatagramConn extends AsyncIterable<[Uint8Array, Addr]> {
|
2023-03-20 17:27:00 -04:00
|
|
|
|
/** Joins an IPv4 multicast group. */
|
|
|
|
|
joinMulticastV4(
|
|
|
|
|
address: string,
|
|
|
|
|
networkInterface: string,
|
|
|
|
|
): Promise<MulticastV4Membership>;
|
|
|
|
|
|
|
|
|
|
/** Joins an IPv6 multicast group. */
|
|
|
|
|
joinMulticastV6(
|
|
|
|
|
address: string,
|
|
|
|
|
networkInterface: number,
|
|
|
|
|
): Promise<MulticastV6Membership>;
|
|
|
|
|
|
2022-10-26 09:53:48 -04:00
|
|
|
|
/** 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.
|
|
|
|
|
*/
|
2021-08-31 05:25:15 -04:00
|
|
|
|
receive(p?: Uint8Array): Promise<[Uint8Array, Addr]>;
|
2022-10-26 09:53:48 -04:00
|
|
|
|
/** Sends a message to the target via the connection. The method resolves
|
|
|
|
|
* with the number of bytes sent. */
|
2021-08-31 05:25:15 -04:00
|
|
|
|
send(p: Uint8Array, addr: Addr): Promise<number>;
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** Close closes the socket. Any pending message promises will be rejected
|
2021-08-31 05:25:15 -04:00
|
|
|
|
* with errors. */
|
|
|
|
|
close(): void;
|
2022-10-26 09:53:48 -04:00
|
|
|
|
/** Return the address of the instance. */
|
2021-08-31 05:25:15 -04:00
|
|
|
|
readonly addr: Addr;
|
|
|
|
|
[Symbol.asyncIterator](): AsyncIterableIterator<[Uint8Array, Addr]>;
|
|
|
|
|
}
|
|
|
|
|
|
2022-10-26 15:04:27 -04:00
|
|
|
|
/**
|
|
|
|
|
* @category Network
|
|
|
|
|
*/
|
|
|
|
|
export interface TcpListenOptions extends ListenOptions {
|
|
|
|
|
/** When `true` the SO_REUSEPORT flag will be set on the listener. This
|
|
|
|
|
* allows multiple processes to listen on the same address and port.
|
|
|
|
|
*
|
|
|
|
|
* On Linux this will cause the kernel to distribute incoming connections
|
|
|
|
|
* across the different processes that are listening on the same address and
|
|
|
|
|
* port.
|
|
|
|
|
*
|
|
|
|
|
* This flag is only supported on Linux. It is silently ignored on other
|
2022-12-13 08:14:41 -05:00
|
|
|
|
* platforms.
|
|
|
|
|
*
|
|
|
|
|
* @default {false} */
|
2022-10-26 15:04:27 -04:00
|
|
|
|
reusePort?: boolean;
|
|
|
|
|
}
|
|
|
|
|
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
2022-10-26 09:53:48 -04:00
|
|
|
|
*
|
|
|
|
|
* Unstable options which can be set when opening a Unix listener via
|
|
|
|
|
* {@linkcode Deno.listen} or {@linkcode Deno.listenDatagram}.
|
2022-09-15 10:37:35 -04:00
|
|
|
|
*
|
|
|
|
|
* @category Network
|
|
|
|
|
*/
|
2021-08-31 05:25:15 -04:00
|
|
|
|
export interface UnixListenOptions {
|
2022-10-26 09:53:48 -04:00
|
|
|
|
/** A path to the Unix Socket. */
|
2021-08-31 05:25:15 -04:00
|
|
|
|
path: string;
|
|
|
|
|
}
|
|
|
|
|
|
2022-10-24 05:05:07 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
2022-10-26 09:53:48 -04:00
|
|
|
|
*
|
|
|
|
|
* Unstable options which can be set when opening a datagram listener via
|
|
|
|
|
* {@linkcode Deno.listenDatagram}.
|
2022-10-24 05:05:07 -04:00
|
|
|
|
*
|
|
|
|
|
* @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
|
2022-10-26 09:53:48 -04:00
|
|
|
|
* socket from the listener.
|
|
|
|
|
*
|
2022-12-13 08:14:41 -05:00
|
|
|
|
* @default {false} */
|
2022-10-24 05:05:07 -04:00
|
|
|
|
reuseAddress?: boolean;
|
2023-03-20 17:27:00 -04:00
|
|
|
|
|
|
|
|
|
/** When `true`, sent multicast packets will be looped back to the local socket.
|
|
|
|
|
*
|
|
|
|
|
* @default {false} */
|
|
|
|
|
loopback?: boolean;
|
2022-10-24 05:05:07 -04:00
|
|
|
|
}
|
|
|
|
|
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
2022-09-15 08:09:23 -04:00
|
|
|
|
*
|
2021-08-31 05:25:15 -04:00
|
|
|
|
* Listen announces on the local transport address.
|
|
|
|
|
*
|
|
|
|
|
* ```ts
|
|
|
|
|
* const listener = Deno.listen({ path: "/foo/bar.sock", transport: "unix" })
|
|
|
|
|
* ```
|
|
|
|
|
*
|
2022-08-16 23:12:24 -04:00
|
|
|
|
* Requires `allow-read` and `allow-write` permission.
|
|
|
|
|
*
|
2022-08-22 20:57:01 -04:00
|
|
|
|
* @tags allow-read, allow-write
|
2022-08-16 23:12:24 -04:00
|
|
|
|
* @category Network
|
|
|
|
|
*/
|
2021-08-31 05:25:15 -04:00
|
|
|
|
export function listen(
|
|
|
|
|
options: UnixListenOptions & { transport: "unix" },
|
|
|
|
|
): Listener;
|
|
|
|
|
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
2022-09-15 08:09:23 -04:00
|
|
|
|
*
|
|
|
|
|
* Listen announces on the local transport address.
|
2021-08-31 05:25:15 -04:00
|
|
|
|
*
|
|
|
|
|
* ```ts
|
|
|
|
|
* const listener1 = Deno.listenDatagram({
|
|
|
|
|
* port: 80,
|
|
|
|
|
* transport: "udp"
|
|
|
|
|
* });
|
|
|
|
|
* const listener2 = Deno.listenDatagram({
|
|
|
|
|
* hostname: "golang.org",
|
|
|
|
|
* port: 80,
|
|
|
|
|
* transport: "udp"
|
|
|
|
|
* });
|
|
|
|
|
* ```
|
|
|
|
|
*
|
2022-08-16 23:12:24 -04:00
|
|
|
|
* Requires `allow-net` permission.
|
|
|
|
|
*
|
2022-08-22 20:57:01 -04:00
|
|
|
|
* @tags allow-net
|
2022-08-16 23:12:24 -04:00
|
|
|
|
* @category Network
|
|
|
|
|
*/
|
2021-08-31 05:25:15 -04:00
|
|
|
|
export function listenDatagram(
|
2022-10-24 05:05:07 -04:00
|
|
|
|
options: UdpListenOptions & { transport: "udp" },
|
2021-08-31 05:25:15 -04:00
|
|
|
|
): DatagramConn;
|
|
|
|
|
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
2022-09-15 08:09:23 -04:00
|
|
|
|
*
|
|
|
|
|
* Listen announces on the local transport address.
|
2021-08-31 05:25:15 -04:00
|
|
|
|
*
|
|
|
|
|
* ```ts
|
|
|
|
|
* const listener = Deno.listenDatagram({
|
|
|
|
|
* path: "/foo/bar.sock",
|
|
|
|
|
* transport: "unixpacket"
|
|
|
|
|
* });
|
|
|
|
|
* ```
|
|
|
|
|
*
|
2022-08-16 23:12:24 -04:00
|
|
|
|
* Requires `allow-read` and `allow-write` permission.
|
|
|
|
|
*
|
2022-08-22 20:57:01 -04:00
|
|
|
|
* @tags allow-read, allow-write
|
2022-08-16 23:12:24 -04:00
|
|
|
|
* @category Network
|
|
|
|
|
*/
|
2021-08-31 05:25:15 -04:00
|
|
|
|
export function listenDatagram(
|
|
|
|
|
options: UnixListenOptions & { transport: "unixpacket" },
|
|
|
|
|
): DatagramConn;
|
|
|
|
|
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
2022-09-15 08:09:23 -04:00
|
|
|
|
*
|
2022-12-13 08:14:41 -05:00
|
|
|
|
* Acquire an advisory file-system lock for the provided file.
|
2022-08-16 23:12:24 -04:00
|
|
|
|
*
|
2022-12-13 08:14:41 -05:00
|
|
|
|
* @param [exclusive=false]
|
2022-08-16 23:12:24 -04:00
|
|
|
|
* @category File System
|
2021-09-19 08:46:54 -04:00
|
|
|
|
*/
|
|
|
|
|
export function flock(rid: number, exclusive?: boolean): Promise<void>;
|
|
|
|
|
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
2022-09-15 08:09:23 -04:00
|
|
|
|
*
|
2022-10-26 09:53:48 -04:00
|
|
|
|
* Acquire an advisory file-system lock synchronously for the provided file.
|
2022-08-16 23:12:24 -04:00
|
|
|
|
*
|
2022-12-13 08:14:41 -05:00
|
|
|
|
* @param [exclusive=false]
|
2022-08-16 23:12:24 -04:00
|
|
|
|
* @category File System
|
2021-09-19 08:46:54 -04:00
|
|
|
|
*/
|
|
|
|
|
export function flockSync(rid: number, exclusive?: boolean): void;
|
|
|
|
|
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
2022-09-15 08:09:23 -04:00
|
|
|
|
*
|
|
|
|
|
* Release an advisory file-system lock for the provided file.
|
2022-08-16 23:12:24 -04:00
|
|
|
|
*
|
|
|
|
|
* @category File System
|
2021-09-19 08:46:54 -04:00
|
|
|
|
*/
|
|
|
|
|
export function funlock(rid: number): Promise<void>;
|
|
|
|
|
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
2022-09-15 08:09:23 -04:00
|
|
|
|
*
|
2022-10-26 09:53:48 -04:00
|
|
|
|
* Release an advisory file-system lock for the provided file synchronously.
|
2022-08-16 23:12:24 -04:00
|
|
|
|
*
|
|
|
|
|
* @category File System
|
2021-09-19 08:46:54 -04:00
|
|
|
|
*/
|
|
|
|
|
export function funlockSync(rid: number): void;
|
2021-12-09 03:00:55 -05:00
|
|
|
|
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
2022-09-15 08:09:23 -04:00
|
|
|
|
*
|
2022-10-26 09:53:48 -04:00
|
|
|
|
* 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}).
|
2022-03-16 09:54:18 -04:00
|
|
|
|
*
|
|
|
|
|
* The returned promise returns underlying connection and first packet
|
|
|
|
|
* received. The promise shouldn't be awaited before responding to the
|
|
|
|
|
* `request`, otherwise event loop might deadlock.
|
2022-08-16 23:12:24 -04:00
|
|
|
|
*
|
2022-08-24 08:10:57 -04:00
|
|
|
|
* ```ts
|
|
|
|
|
* function handler(req: Request): Response {
|
|
|
|
|
* Deno.upgradeHttp(req).then(([conn, firstPacket]) => {
|
|
|
|
|
* // ...
|
|
|
|
|
* });
|
|
|
|
|
* return new Response(null, { status: 101 });
|
|
|
|
|
* }
|
|
|
|
|
* ```
|
|
|
|
|
*
|
2022-10-26 09:53:48 -04:00
|
|
|
|
* This method can only be called on requests originating the
|
|
|
|
|
* {@linkcode Deno.serveHttp} server.
|
2022-08-24 08:10:57 -04:00
|
|
|
|
*
|
2022-08-16 23:12:24 -04:00
|
|
|
|
* @category HTTP Server
|
2022-03-16 09:54:18 -04:00
|
|
|
|
*/
|
|
|
|
|
export function upgradeHttp(
|
|
|
|
|
request: Request,
|
2022-08-24 08:10:57 -04:00
|
|
|
|
): Promise<[Deno.Conn, Uint8Array]>;
|
|
|
|
|
|
2023-03-22 00:13:24 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
|
|
|
|
*
|
|
|
|
|
* Open a new {@linkcode Deno.Kv} connection to persist data.
|
|
|
|
|
*
|
|
|
|
|
* When a path is provided, the database will be persisted to disk at that
|
|
|
|
|
* path. Read and write access to the file is required.
|
|
|
|
|
*
|
|
|
|
|
* When no path is provided, the database will be opened in a default path for
|
|
|
|
|
* the current script. This location is persistent across script runs and is
|
|
|
|
|
* keyed on the origin storage key (the same key that is used to determine
|
|
|
|
|
* `localStorage` persistence). More information about the origin storage key
|
|
|
|
|
* can be found in the Deno Manual.
|
|
|
|
|
*
|
|
|
|
|
* @tags allow-read, allow-write
|
|
|
|
|
* @category KV
|
|
|
|
|
*/
|
2023-03-22 15:23:36 -04:00
|
|
|
|
export function openKv(path?: string): Promise<Deno.Kv>;
|
2023-03-22 00:13:24 -04:00
|
|
|
|
|
2023-11-30 16:51:56 -05:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
|
|
|
|
*
|
|
|
|
|
* CronScheduleExpression is used as the type of `minute`, `hour`,
|
|
|
|
|
* `dayOfMonth`, `month`, and `dayOfWeek` in {@linkcode CronSchedule}.
|
|
|
|
|
* @category Cron
|
|
|
|
|
*/
|
|
|
|
|
type CronScheduleExpression = number | { exact: number | number[] } | {
|
|
|
|
|
start?: number;
|
|
|
|
|
end?: number;
|
|
|
|
|
every?: number;
|
|
|
|
|
};
|
|
|
|
|
|
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
|
|
|
|
*
|
|
|
|
|
* CronSchedule is the interface used for JSON format
|
|
|
|
|
* cron `schedule`.
|
|
|
|
|
* @category Cron
|
|
|
|
|
*/
|
|
|
|
|
export interface CronSchedule {
|
|
|
|
|
minute?: CronScheduleExpression;
|
|
|
|
|
hour?: CronScheduleExpression;
|
|
|
|
|
dayOfMonth?: CronScheduleExpression;
|
|
|
|
|
month?: CronScheduleExpression;
|
|
|
|
|
dayOfWeek?: CronScheduleExpression;
|
|
|
|
|
}
|
|
|
|
|
|
2023-11-01 14:57:55 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
|
|
|
|
*
|
|
|
|
|
* Create a cron job that will periodically execute the provided handler
|
|
|
|
|
* callback based on the specified schedule.
|
|
|
|
|
*
|
|
|
|
|
* ```ts
|
2023-11-04 17:04:13 -04:00
|
|
|
|
* Deno.cron("sample cron", "20 * * * *", () => {
|
2023-11-01 14:57:55 -04:00
|
|
|
|
* console.log("cron job executed");
|
|
|
|
|
* });
|
|
|
|
|
* ```
|
2023-11-30 18:52:48 -05:00
|
|
|
|
*
|
|
|
|
|
* ```ts
|
|
|
|
|
* Deno.cron("sample cron", { hour: { every: 6 } }, () => {
|
|
|
|
|
* console.log("cron job executed");
|
|
|
|
|
* });
|
|
|
|
|
* ```
|
|
|
|
|
*
|
|
|
|
|
* `schedule` can be a string in the Unix cron format or in JSON format
|
|
|
|
|
* as specified by interface {@linkcode CronSchedule}, where time is specified
|
|
|
|
|
* using UTC time zone.
|
2023-11-01 14:57:55 -04:00
|
|
|
|
*
|
|
|
|
|
* @category Cron
|
|
|
|
|
*/
|
|
|
|
|
export function cron(
|
|
|
|
|
name: string,
|
2023-11-30 16:51:56 -05:00
|
|
|
|
schedule: string | CronSchedule,
|
2023-11-01 14:57:55 -04:00
|
|
|
|
handler: () => Promise<void> | void,
|
2023-11-16 17:19:00 -05:00
|
|
|
|
): Promise<void>;
|
|
|
|
|
|
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
|
|
|
|
*
|
|
|
|
|
* Create a cron job that will periodically execute the provided handler
|
|
|
|
|
* callback based on the specified schedule.
|
|
|
|
|
*
|
|
|
|
|
* ```ts
|
2023-11-30 18:52:48 -05:00
|
|
|
|
* Deno.cron("sample cron", "20 * * * *", {
|
|
|
|
|
* backoffSchedule: [10, 20]
|
|
|
|
|
* }, () => {
|
2023-11-16 17:19:00 -05:00
|
|
|
|
* console.log("cron job executed");
|
|
|
|
|
* });
|
|
|
|
|
* ```
|
|
|
|
|
*
|
2023-11-30 16:51:56 -05:00
|
|
|
|
* `schedule` can be a string in the Unix cron format or in JSON format
|
|
|
|
|
* as specified by interface {@linkcode CronSchedule}, where time is specified
|
2023-11-16 17:19:00 -05:00
|
|
|
|
* using UTC time zone.
|
|
|
|
|
*
|
2023-11-30 18:52:48 -05:00
|
|
|
|
* `backoffSchedule` option can be used to specify the retry policy for failed
|
|
|
|
|
* executions. Each element in the array represents the number of milliseconds
|
|
|
|
|
* to wait before retrying the execution. For example, `[1000, 5000, 10000]`
|
|
|
|
|
* means that a failed execution will be retried at most 3 times, with 1
|
|
|
|
|
* second, 5 seconds, and 10 seconds delay between each retry.
|
|
|
|
|
*
|
2023-11-16 17:19:00 -05:00
|
|
|
|
* @category Cron
|
|
|
|
|
*/
|
|
|
|
|
export function cron(
|
|
|
|
|
name: string,
|
2023-11-30 16:51:56 -05:00
|
|
|
|
schedule: string | CronSchedule,
|
2023-11-30 18:52:48 -05:00
|
|
|
|
options: { backoffSchedule?: number[]; signal?: AbortSignal },
|
2023-11-16 17:19:00 -05:00
|
|
|
|
handler: () => Promise<void> | void,
|
|
|
|
|
): Promise<void>;
|
|
|
|
|
|
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
|
|
|
|
*
|
|
|
|
|
* Create a cron job that will periodically execute the provided handler
|
|
|
|
|
* callback based on the specified schedule.
|
|
|
|
|
*
|
2023-11-30 16:51:56 -05:00
|
|
|
|
* `schedule` can be a string in the Unix cron format or in JSON format
|
|
|
|
|
* as specified by interface {@linkcode CronSchedule}, where time is specified
|
2023-11-16 17:19:00 -05:00
|
|
|
|
* using UTC time zone.
|
|
|
|
|
*
|
2023-11-30 18:52:48 -05:00
|
|
|
|
* ```ts
|
|
|
|
|
* Deno.cron("sample cron", "20 * * * *", () => {
|
|
|
|
|
* console.log("cron job executed");
|
|
|
|
|
* });
|
|
|
|
|
* ```
|
2023-11-16 17:19:00 -05:00
|
|
|
|
* `backoffSchedule` option can be used to specify the retry policy for failed
|
|
|
|
|
* executions. Each element in the array represents the number of milliseconds
|
|
|
|
|
* to wait before retrying the execution. For example, `[1000, 5000, 10000]`
|
|
|
|
|
* means that a failed execution will be retried at most 3 times, with 1
|
|
|
|
|
* second, 5 seconds, and 10 seconds delay between each retry.
|
|
|
|
|
*
|
|
|
|
|
* @category Cron
|
2023-11-30 18:52:48 -05:00
|
|
|
|
* @deprecated Use other {@linkcode cron} overloads instead. This overload
|
|
|
|
|
* will be removed in the future.
|
2023-11-16 17:19:00 -05:00
|
|
|
|
*/
|
|
|
|
|
export function cron(
|
|
|
|
|
name: string,
|
2023-11-30 16:51:56 -05:00
|
|
|
|
schedule: string | CronSchedule,
|
2023-11-16 17:19:00 -05:00
|
|
|
|
handler: () => Promise<void> | void,
|
2023-11-30 18:52:48 -05:00
|
|
|
|
options: { backoffSchedule?: number[]; signal?: AbortSignal },
|
2023-11-01 14:57:55 -04:00
|
|
|
|
): Promise<void>;
|
|
|
|
|
|
2023-03-22 00:13:24 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
|
|
|
|
*
|
|
|
|
|
* A key to be persisted in a {@linkcode Deno.Kv}. A key is a sequence
|
|
|
|
|
* of {@linkcode Deno.KvKeyPart}s.
|
|
|
|
|
*
|
|
|
|
|
* Keys are ordered lexicographically by their parts. The first part is the
|
|
|
|
|
* most significant, and the last part is the least significant. The order of
|
|
|
|
|
* the parts is determined by both the type and the value of the part. The
|
|
|
|
|
* relative significance of the types can be found in documentation for the
|
|
|
|
|
* {@linkcode Deno.KvKeyPart} type.
|
|
|
|
|
*
|
2023-04-27 10:59:02 -04:00
|
|
|
|
* Keys have a maximum size of 2048 bytes serialized. If the size of the key
|
|
|
|
|
* exceeds this limit, an error will be thrown on the operation that this key
|
|
|
|
|
* was passed to.
|
|
|
|
|
*
|
2023-03-22 00:13:24 -04:00
|
|
|
|
* @category KV
|
|
|
|
|
*/
|
|
|
|
|
export type KvKey = readonly KvKeyPart[];
|
|
|
|
|
|
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
|
|
|
|
*
|
|
|
|
|
* A single part of a {@linkcode Deno.KvKey}. Parts are ordered
|
|
|
|
|
* lexicographically, first by their type, and within a given type by their
|
|
|
|
|
* value.
|
|
|
|
|
*
|
|
|
|
|
* The ordering of types is as follows:
|
|
|
|
|
*
|
|
|
|
|
* 1. `Uint8Array`
|
|
|
|
|
* 2. `string`
|
|
|
|
|
* 3. `number`
|
|
|
|
|
* 4. `bigint`
|
|
|
|
|
* 5. `boolean`
|
|
|
|
|
*
|
|
|
|
|
* Within a given type, the ordering is as follows:
|
|
|
|
|
*
|
|
|
|
|
* - `Uint8Array` is ordered by the byte ordering of the array
|
|
|
|
|
* - `string` is ordered by the byte ordering of the UTF-8 encoding of the
|
|
|
|
|
* string
|
|
|
|
|
* - `number` is ordered following this pattern: `-NaN`
|
|
|
|
|
* < `-Infinity` < `-100.0` < `-1.0` < -`0.5` < `-0.0` < `0.0` < `0.5`
|
|
|
|
|
* < `1.0` < `100.0` < `Infinity` < `NaN`
|
|
|
|
|
* - `bigint` is ordered by mathematical ordering, with the largest negative
|
|
|
|
|
* number being the least first value, and the largest positive number
|
|
|
|
|
* being the last value
|
|
|
|
|
* - `boolean` is ordered by `false` < `true`
|
|
|
|
|
*
|
|
|
|
|
* This means that the part `1.0` (a number) is ordered before the part `2.0`
|
|
|
|
|
* (also a number), but is greater than the part `0n` (a bigint), because
|
|
|
|
|
* `1.0` is a number and `0n` is a bigint, and type ordering has precedence
|
|
|
|
|
* over the ordering of values within a type.
|
|
|
|
|
*
|
|
|
|
|
* @category KV
|
|
|
|
|
*/
|
2023-12-13 11:58:20 -05:00
|
|
|
|
export type KvKeyPart =
|
|
|
|
|
| Uint8Array
|
|
|
|
|
| string
|
|
|
|
|
| number
|
|
|
|
|
| bigint
|
|
|
|
|
| boolean
|
|
|
|
|
| symbol;
|
2023-03-22 00:13:24 -04:00
|
|
|
|
|
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
|
|
|
|
*
|
|
|
|
|
* Consistency level of a KV operation.
|
|
|
|
|
*
|
|
|
|
|
* - `strong` - This operation must be strongly-consistent.
|
|
|
|
|
* - `eventual` - Eventually-consistent behavior is allowed.
|
|
|
|
|
*
|
|
|
|
|
* @category KV
|
|
|
|
|
*/
|
|
|
|
|
export type KvConsistencyLevel = "strong" | "eventual";
|
|
|
|
|
|
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
|
|
|
|
*
|
|
|
|
|
* A selector that selects the range of data returned by a list operation on a
|
|
|
|
|
* {@linkcode Deno.Kv}.
|
|
|
|
|
*
|
|
|
|
|
* The selector can either be a prefix selector or a range selector. A prefix
|
|
|
|
|
* selector selects all keys that start with the given prefix (optionally
|
|
|
|
|
* starting at a given key). A range selector selects all keys that are
|
|
|
|
|
* lexicographically between the given start and end keys.
|
|
|
|
|
*
|
|
|
|
|
* @category KV
|
|
|
|
|
*/
|
|
|
|
|
export type KvListSelector =
|
|
|
|
|
| { prefix: KvKey }
|
|
|
|
|
| { prefix: KvKey; start: KvKey }
|
|
|
|
|
| { prefix: KvKey; end: KvKey }
|
|
|
|
|
| { start: KvKey; end: KvKey };
|
|
|
|
|
|
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
|
|
|
|
*
|
|
|
|
|
* A mutation to a key in a {@linkcode Deno.Kv}. A mutation is a
|
|
|
|
|
* combination of a key, a value, and a type. The type determines how the
|
|
|
|
|
* mutation is applied to the key.
|
|
|
|
|
*
|
|
|
|
|
* - `set` - Sets the value of the key to the given value, overwriting any
|
2023-08-18 05:34:16 -04:00
|
|
|
|
* existing value. Optionally an `expireIn` option can be specified to
|
|
|
|
|
* set a time-to-live (TTL) for the key. The TTL is specified in
|
|
|
|
|
* milliseconds, and the key will be deleted from the database at earliest
|
|
|
|
|
* after the specified number of milliseconds have elapsed. Once the
|
|
|
|
|
* specified duration has passed, the key may still be visible for some
|
|
|
|
|
* additional time. If the `expireIn` option is not specified, the key will
|
|
|
|
|
* not expire.
|
2023-03-22 00:13:24 -04:00
|
|
|
|
* - `delete` - Deletes the key from the database. The mutation is a no-op if
|
|
|
|
|
* the key does not exist.
|
|
|
|
|
* - `sum` - Adds the given value to the existing value of the key. Both the
|
|
|
|
|
* value specified in the mutation, and any existing value must be of type
|
|
|
|
|
* `Deno.KvU64`. If the key does not exist, the value is set to the given
|
2023-04-26 13:14:01 -04:00
|
|
|
|
* value (summed with 0). If the result of the sum overflows an unsigned
|
|
|
|
|
* 64-bit integer, the result is wrapped around.
|
2023-03-22 00:13:24 -04:00
|
|
|
|
* - `max` - Sets the value of the key to the maximum of the existing value
|
|
|
|
|
* and the given value. Both the value specified in the mutation, and any
|
|
|
|
|
* existing value must be of type `Deno.KvU64`. If the key does not exist,
|
|
|
|
|
* the value is set to the given value.
|
|
|
|
|
* - `min` - Sets the value of the key to the minimum of the existing value
|
|
|
|
|
* and the given value. Both the value specified in the mutation, and any
|
|
|
|
|
* existing value must be of type `Deno.KvU64`. If the key does not exist,
|
|
|
|
|
* the value is set to the given value.
|
|
|
|
|
*
|
|
|
|
|
* @category KV
|
|
|
|
|
*/
|
|
|
|
|
export type KvMutation =
|
|
|
|
|
& { key: KvKey }
|
|
|
|
|
& (
|
2023-08-18 05:34:16 -04:00
|
|
|
|
| { type: "set"; value: unknown; expireIn?: number }
|
2023-03-22 00:13:24 -04:00
|
|
|
|
| { type: "delete" }
|
|
|
|
|
| { type: "sum"; value: KvU64 }
|
|
|
|
|
| { type: "max"; value: KvU64 }
|
|
|
|
|
| { type: "min"; value: KvU64 }
|
|
|
|
|
);
|
|
|
|
|
|
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
|
|
|
|
*
|
|
|
|
|
* An iterator over a range of data entries in a {@linkcode Deno.Kv}.
|
|
|
|
|
*
|
|
|
|
|
* The cursor getter returns the cursor that can be used to resume the
|
|
|
|
|
* iteration from the current position in the future.
|
|
|
|
|
*
|
|
|
|
|
* @category KV
|
|
|
|
|
*/
|
2023-03-30 16:52:31 -04:00
|
|
|
|
export class KvListIterator<T> implements AsyncIterableIterator<KvEntry<T>> {
|
2023-03-22 00:13:24 -04:00
|
|
|
|
/**
|
|
|
|
|
* Returns the cursor of the current position in the iteration. This cursor
|
|
|
|
|
* can be used to resume the iteration from the current position in the
|
|
|
|
|
* future by passing it to the `cursor` option of the `list` method.
|
|
|
|
|
*/
|
|
|
|
|
get cursor(): string;
|
|
|
|
|
|
2023-03-30 16:52:31 -04:00
|
|
|
|
next(): Promise<IteratorResult<KvEntry<T>, undefined>>;
|
|
|
|
|
[Symbol.asyncIterator](): AsyncIterableIterator<KvEntry<T>>;
|
2023-03-22 00:13:24 -04:00
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
|
|
|
|
*
|
|
|
|
|
* A versioned pair of key and value in a {@linkcode Deno.Kv}.
|
|
|
|
|
*
|
|
|
|
|
* The `versionstamp` is a string that represents the current version of the
|
|
|
|
|
* key-value pair. It can be used to perform atomic operations on the KV store
|
|
|
|
|
* by passing it to the `check` method of a {@linkcode Deno.AtomicOperation}.
|
|
|
|
|
*
|
|
|
|
|
* @category KV
|
|
|
|
|
*/
|
2023-03-30 16:52:31 -04:00
|
|
|
|
export type KvEntry<T> = { key: KvKey; value: T; versionstamp: string };
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* **UNSTABLE**: New API, yet to be vetted.
|
|
|
|
|
*
|
|
|
|
|
* An optional versioned pair of key and value in a {@linkcode Deno.Kv}.
|
|
|
|
|
*
|
|
|
|
|
* This is the same as a {@linkcode KvEntry}, but the `value` and `versionstamp`
|
|
|
|
|
* fields may be `null` if no value exists for the given key in the KV store.
|
|
|
|
|
*
|
|
|
|
|
* @category KV
|
|
|
|
|
*/
|
|
|
|
|
export type KvEntryMaybe<T> = KvEntry<T> | {
|
2023-03-22 00:13:24 -04:00
|
|
|
|
key: KvKey;
|
2023-03-30 16:52:31 -04:00
|
|
|
|
value: null;
|
|
|
|
|
versionstamp: null;
|
|
|
|
|
};
|
2023-03-22 00:13:24 -04:00
|
|
|
|
|
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
|
|
|
|
*
|
|
|
|
|
* Options for listing key-value pairs in a {@linkcode Deno.Kv}.
|
|
|
|
|
*
|
|
|
|
|
* @category KV
|
|
|
|
|
*/
|
|
|
|
|
export interface KvListOptions {
|
|
|
|
|
/**
|
|
|
|
|
* The maximum number of key-value pairs to return. If not specified, all
|
|
|
|
|
* matching key-value pairs will be returned.
|
|
|
|
|
*/
|
|
|
|
|
limit?: number;
|
|
|
|
|
/**
|
|
|
|
|
* The cursor to resume the iteration from. If not specified, the iteration
|
|
|
|
|
* will start from the beginning.
|
|
|
|
|
*/
|
|
|
|
|
cursor?: string;
|
|
|
|
|
/**
|
|
|
|
|
* Whether to reverse the order of the returned key-value pairs. If not
|
|
|
|
|
* specified, the order will be ascending from the start of the range as per
|
|
|
|
|
* the lexicographical ordering of the keys. If `true`, the order will be
|
|
|
|
|
* descending from the end of the range.
|
|
|
|
|
*
|
|
|
|
|
* The default value is `false`.
|
|
|
|
|
*/
|
|
|
|
|
reverse?: boolean;
|
|
|
|
|
/**
|
|
|
|
|
* The consistency level of the list operation. The default consistency
|
|
|
|
|
* level is "strong". Some use cases can benefit from using a weaker
|
|
|
|
|
* consistency level. For more information on consistency levels, see the
|
|
|
|
|
* documentation for {@linkcode Deno.KvConsistencyLevel}.
|
|
|
|
|
*
|
|
|
|
|
* List operations are performed in batches (in sizes specified by the
|
|
|
|
|
* `batchSize` option). The consistency level of the list operation is
|
|
|
|
|
* applied to each batch individually. This means that while each batch is
|
|
|
|
|
* guaranteed to be consistent within itself, the entire list operation may
|
|
|
|
|
* not be consistent across batches because a mutation may be applied to a
|
|
|
|
|
* key-value pair between batches, in a batch that has already been returned
|
|
|
|
|
* by the list operation.
|
|
|
|
|
*/
|
|
|
|
|
consistency?: KvConsistencyLevel;
|
|
|
|
|
/**
|
|
|
|
|
* The size of the batches in which the list operation is performed. Larger
|
|
|
|
|
* or smaller batch sizes may positively or negatively affect the
|
|
|
|
|
* performance of a list operation depending on the specific use case and
|
|
|
|
|
* iteration behavior. Slow iterating queries may benefit from using a
|
|
|
|
|
* smaller batch size for increased overall consistency, while fast
|
|
|
|
|
* iterating queries may benefit from using a larger batch size for better
|
|
|
|
|
* performance.
|
|
|
|
|
*
|
|
|
|
|
* The default batch size is equal to the `limit` option, or 100 if this is
|
|
|
|
|
* unset. The maximum value for this option is 500. Larger values will be
|
|
|
|
|
* clamped.
|
|
|
|
|
*/
|
|
|
|
|
batchSize?: number;
|
|
|
|
|
}
|
|
|
|
|
|
2023-04-24 16:24:18 -04:00
|
|
|
|
/** @category KV */
|
2023-03-30 14:57:21 -04:00
|
|
|
|
export interface KvCommitResult {
|
2023-04-27 10:59:02 -04:00
|
|
|
|
ok: true;
|
2023-03-30 14:57:21 -04:00
|
|
|
|
/** The versionstamp of the value committed to KV. */
|
|
|
|
|
versionstamp: string;
|
|
|
|
|
}
|
|
|
|
|
|
2023-04-27 10:59:02 -04:00
|
|
|
|
/** @category KV */
|
|
|
|
|
export interface KvCommitError {
|
|
|
|
|
ok: false;
|
|
|
|
|
}
|
|
|
|
|
|
2023-03-22 00:13:24 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
|
|
|
|
*
|
|
|
|
|
* A check to perform as part of a {@linkcode Deno.AtomicOperation}. The check
|
|
|
|
|
* will fail if the versionstamp for the key-value pair in the KV store does
|
|
|
|
|
* not match the given versionstamp. A check with a `null` versionstamp checks
|
|
|
|
|
* that the key-value pair does not currently exist in the KV store.
|
|
|
|
|
*
|
|
|
|
|
* @category KV
|
|
|
|
|
*/
|
|
|
|
|
export interface AtomicCheck {
|
|
|
|
|
key: KvKey;
|
|
|
|
|
versionstamp: string | null;
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
|
|
|
|
*
|
|
|
|
|
* An operation on a {@linkcode Deno.Kv} that can be performed
|
|
|
|
|
* atomically. Atomic operations do not auto-commit, and must be committed
|
|
|
|
|
* explicitly by calling the `commit` method.
|
|
|
|
|
*
|
|
|
|
|
* Atomic operations can be used to perform multiple mutations on the KV store
|
|
|
|
|
* in a single atomic transaction. They can also be used to perform
|
|
|
|
|
* conditional mutations by specifying one or more
|
|
|
|
|
* {@linkcode Deno.AtomicCheck}s that ensure that a mutation is only performed
|
|
|
|
|
* if the key-value pair in the KV has a specific versionstamp. If any of the
|
|
|
|
|
* checks fail, the entire operation will fail and no mutations will be made.
|
|
|
|
|
*
|
|
|
|
|
* The ordering of mutations is guaranteed to be the same as the ordering of
|
|
|
|
|
* the mutations specified in the operation. Checks are performed before any
|
|
|
|
|
* mutations are performed. The ordering of checks is unobservable.
|
|
|
|
|
*
|
|
|
|
|
* Atomic operations can be used to implement optimistic locking, where a
|
|
|
|
|
* mutation is only performed if the key-value pair in the KV store has not
|
|
|
|
|
* been modified since the last read. This can be done by specifying a check
|
|
|
|
|
* that ensures that the versionstamp of the key-value pair matches the
|
|
|
|
|
* versionstamp that was read. If the check fails, the mutation will not be
|
|
|
|
|
* performed and the operation will fail. One can then retry the read-modify-
|
|
|
|
|
* write operation in a loop until it succeeds.
|
|
|
|
|
*
|
2023-03-30 14:57:21 -04:00
|
|
|
|
* The `commit` method of an atomic operation returns a value indicating
|
2023-03-22 00:13:24 -04:00
|
|
|
|
* whether checks passed and mutations were performed. If the operation failed
|
2023-04-27 10:59:02 -04:00
|
|
|
|
* because of a failed check, the return value will be a
|
|
|
|
|
* {@linkcode Deno.KvCommitError} with an `ok: false` property. If the
|
2023-03-22 00:13:24 -04:00
|
|
|
|
* operation failed for any other reason (storage error, invalid value, etc.),
|
2023-03-30 14:57:21 -04:00
|
|
|
|
* an exception will be thrown. If the operation succeeded, the return value
|
2023-04-27 10:59:02 -04:00
|
|
|
|
* will be a {@linkcode Deno.KvCommitResult} object with a `ok: true` property
|
|
|
|
|
* and the versionstamp of the value committed to KV.
|
|
|
|
|
|
2023-03-22 00:13:24 -04:00
|
|
|
|
*
|
|
|
|
|
* @category KV
|
|
|
|
|
*/
|
|
|
|
|
export class AtomicOperation {
|
|
|
|
|
/**
|
|
|
|
|
* Add to the operation a check that ensures that the versionstamp of the
|
|
|
|
|
* key-value pair in the KV store matches the given versionstamp. If the
|
|
|
|
|
* check fails, the entire operation will fail and no mutations will be
|
|
|
|
|
* performed during the commit.
|
|
|
|
|
*/
|
|
|
|
|
check(...checks: AtomicCheck[]): this;
|
|
|
|
|
/**
|
|
|
|
|
* Add to the operation a mutation that performs the specified mutation on
|
|
|
|
|
* the specified key if all checks pass during the commit. The types and
|
|
|
|
|
* semantics of all available mutations are described in the documentation
|
|
|
|
|
* for {@linkcode Deno.KvMutation}.
|
|
|
|
|
*/
|
|
|
|
|
mutate(...mutations: KvMutation[]): this;
|
2023-04-15 04:33:31 -04:00
|
|
|
|
/**
|
2023-04-26 13:14:01 -04:00
|
|
|
|
* Shortcut for creating a `sum` mutation. This method wraps `n` in a
|
|
|
|
|
* {@linkcode Deno.KvU64}, so the value of `n` must be in the range
|
|
|
|
|
* `[0, 2^64-1]`.
|
2023-04-15 04:33:31 -04:00
|
|
|
|
*/
|
|
|
|
|
sum(key: KvKey, n: bigint): this;
|
2023-04-26 13:14:01 -04:00
|
|
|
|
/**
|
|
|
|
|
* Shortcut for creating a `min` mutation. This method wraps `n` in a
|
|
|
|
|
* {@linkcode Deno.KvU64}, so the value of `n` must be in the range
|
|
|
|
|
* `[0, 2^64-1]`.
|
|
|
|
|
*/
|
|
|
|
|
min(key: KvKey, n: bigint): this;
|
|
|
|
|
/**
|
|
|
|
|
* Shortcut for creating a `max` mutation. This method wraps `n` in a
|
|
|
|
|
* {@linkcode Deno.KvU64}, so the value of `n` must be in the range
|
|
|
|
|
* `[0, 2^64-1]`.
|
|
|
|
|
*/
|
|
|
|
|
max(key: KvKey, n: bigint): this;
|
2023-03-22 00:13:24 -04:00
|
|
|
|
/**
|
|
|
|
|
* Add to the operation a mutation that sets the value of the specified key
|
|
|
|
|
* to the specified value if all checks pass during the commit.
|
2023-08-18 05:34:16 -04:00
|
|
|
|
*
|
|
|
|
|
* Optionally an `expireIn` option can be specified to set a time-to-live
|
|
|
|
|
* (TTL) for the key. The TTL is specified in milliseconds, and the key will
|
|
|
|
|
* be deleted from the database at earliest after the specified number of
|
|
|
|
|
* milliseconds have elapsed. Once the specified duration has passed, the
|
|
|
|
|
* key may still be visible for some additional time. If the `expireIn`
|
|
|
|
|
* option is not specified, the key will not expire.
|
2023-03-22 00:13:24 -04:00
|
|
|
|
*/
|
2023-08-18 05:34:16 -04:00
|
|
|
|
set(key: KvKey, value: unknown, options?: { expireIn?: number }): this;
|
2023-03-22 00:13:24 -04:00
|
|
|
|
/**
|
|
|
|
|
* Add to the operation a mutation that deletes the specified key if all
|
|
|
|
|
* checks pass during the commit.
|
|
|
|
|
*/
|
|
|
|
|
delete(key: KvKey): this;
|
2023-06-13 20:49:57 -04:00
|
|
|
|
/**
|
|
|
|
|
* Add to the operation a mutation that enqueues a value into the queue
|
|
|
|
|
* if all checks pass during the commit.
|
|
|
|
|
*/
|
|
|
|
|
enqueue(
|
|
|
|
|
value: unknown,
|
2023-12-13 01:51:23 -05:00
|
|
|
|
options?: {
|
|
|
|
|
delay?: number;
|
|
|
|
|
keysIfUndelivered?: Deno.KvKey[];
|
|
|
|
|
backoffSchedule?: number[];
|
|
|
|
|
},
|
2023-06-13 20:49:57 -04:00
|
|
|
|
): this;
|
2023-03-22 00:13:24 -04:00
|
|
|
|
/**
|
2023-03-30 14:57:21 -04:00
|
|
|
|
* Commit the operation to the KV store. Returns a value indicating whether
|
|
|
|
|
* checks passed and mutations were performed. If the operation failed
|
2023-04-27 10:59:02 -04:00
|
|
|
|
* because of a failed check, the return value will be a {@linkcode
|
|
|
|
|
* Deno.KvCommitError} with an `ok: false` property. If the operation failed
|
|
|
|
|
* for any other reason (storage error, invalid value, etc.), an exception
|
|
|
|
|
* will be thrown. If the operation succeeded, the return value will be a
|
|
|
|
|
* {@linkcode Deno.KvCommitResult} object with a `ok: true` property and the
|
|
|
|
|
* versionstamp of the value committed to KV.
|
2023-03-22 00:13:24 -04:00
|
|
|
|
*
|
2023-04-27 10:59:02 -04:00
|
|
|
|
* If the commit returns `ok: false`, one may create a new atomic operation
|
|
|
|
|
* with updated checks and mutations and attempt to commit it again. See the
|
|
|
|
|
* note on optimistic locking in the documentation for
|
|
|
|
|
* {@linkcode Deno.AtomicOperation}.
|
2023-03-22 00:13:24 -04:00
|
|
|
|
*/
|
2023-04-27 10:59:02 -04:00
|
|
|
|
commit(): Promise<KvCommitResult | KvCommitError>;
|
2023-03-22 00:13:24 -04:00
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
|
|
|
|
*
|
|
|
|
|
* A key-value database that can be used to store and retrieve data.
|
|
|
|
|
*
|
|
|
|
|
* Data is stored as key-value pairs, where the key is a {@linkcode Deno.KvKey}
|
|
|
|
|
* and the value is an arbitrary structured-serializable JavaScript value.
|
|
|
|
|
* Keys are ordered lexicographically as described in the documentation for
|
|
|
|
|
* {@linkcode Deno.KvKey}. Keys are unique within a database, and the last
|
|
|
|
|
* value set for a given key is the one that is returned when reading the
|
|
|
|
|
* key. Keys can be deleted from the database, in which case they will no
|
|
|
|
|
* longer be returned when reading keys.
|
|
|
|
|
*
|
|
|
|
|
* Values can be any structured-serializable JavaScript value (objects,
|
|
|
|
|
* arrays, strings, numbers, etc.). The special value {@linkcode Deno.KvU64}
|
|
|
|
|
* can be used to store 64-bit unsigned integers in the database. This special
|
|
|
|
|
* value can not be nested within other objects or arrays. In addition to the
|
|
|
|
|
* regular database mutation operations, the unsigned 64-bit integer value
|
|
|
|
|
* also supports `sum`, `max`, and `min` mutations.
|
|
|
|
|
*
|
|
|
|
|
* Keys are versioned on write by assigning the key an ever-increasing
|
|
|
|
|
* "versionstamp". The versionstamp represents the version of a key-value pair
|
|
|
|
|
* in the database at some point in time, and can be used to perform
|
|
|
|
|
* transactional operations on the database without requiring any locking.
|
|
|
|
|
* This is enabled by atomic operations, which can have conditions that ensure
|
|
|
|
|
* that the operation only succeeds if the versionstamp of the key-value pair
|
|
|
|
|
* matches an expected versionstamp.
|
|
|
|
|
*
|
|
|
|
|
* Keys have a maximum length of 2048 bytes after serialization. Values have a
|
2023-03-25 03:29:36 -04:00
|
|
|
|
* maximum length of 64 KiB after serialization. Serialization of both keys
|
2023-03-22 00:13:24 -04:00
|
|
|
|
* and values is somewhat opaque, but one can usually assume that the
|
|
|
|
|
* serialization of any value is about the same length as the resulting string
|
2023-04-27 10:59:02 -04:00
|
|
|
|
* of a JSON serialization of that same value. If theses limits are exceeded,
|
|
|
|
|
* an exception will be thrown.
|
2023-03-22 00:13:24 -04:00
|
|
|
|
*
|
|
|
|
|
* @category KV
|
|
|
|
|
*/
|
2023-11-01 15:26:12 -04:00
|
|
|
|
export class Kv implements Disposable {
|
2023-03-22 00:13:24 -04:00
|
|
|
|
/**
|
|
|
|
|
* Retrieve the value and versionstamp for the given key from the database
|
2023-03-30 16:52:31 -04:00
|
|
|
|
* in the form of a {@linkcode Deno.KvEntryMaybe}. If no value exists for
|
|
|
|
|
* the key, the returned entry will have a `null` value and versionstamp.
|
2023-03-22 00:13:24 -04:00
|
|
|
|
*
|
|
|
|
|
* ```ts
|
2023-03-22 15:23:36 -04:00
|
|
|
|
* const db = await Deno.openKv();
|
2023-03-22 00:13:24 -04:00
|
|
|
|
* const result = await db.get(["foo"]);
|
|
|
|
|
* result.key; // ["foo"]
|
|
|
|
|
* result.value; // "bar"
|
|
|
|
|
* result.versionstamp; // "00000000000000010000"
|
|
|
|
|
* ```
|
|
|
|
|
*
|
|
|
|
|
* The `consistency` option can be used to specify the consistency level
|
|
|
|
|
* for the read operation. The default consistency level is "strong". Some
|
|
|
|
|
* use cases can benefit from using a weaker consistency level. For more
|
|
|
|
|
* information on consistency levels, see the documentation for
|
|
|
|
|
* {@linkcode Deno.KvConsistencyLevel}.
|
|
|
|
|
*/
|
2023-03-30 16:52:31 -04:00
|
|
|
|
get<T = unknown>(
|
2023-03-22 00:13:24 -04:00
|
|
|
|
key: KvKey,
|
|
|
|
|
options?: { consistency?: KvConsistencyLevel },
|
2023-03-30 16:52:31 -04:00
|
|
|
|
): Promise<KvEntryMaybe<T>>;
|
2023-03-22 00:13:24 -04:00
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* Retrieve multiple values and versionstamps from the database in the form
|
2023-03-30 16:52:31 -04:00
|
|
|
|
* of an array of {@linkcode Deno.KvEntryMaybe} objects. The returned array
|
|
|
|
|
* will have the same length as the `keys` array, and the entries will be in
|
|
|
|
|
* the same order as the keys. If no value exists for a given key, the
|
|
|
|
|
* returned entry will have a `null` value and versionstamp.
|
2023-03-22 00:13:24 -04:00
|
|
|
|
*
|
|
|
|
|
* ```ts
|
2023-03-22 15:23:36 -04:00
|
|
|
|
* const db = await Deno.openKv();
|
2023-03-22 00:13:24 -04:00
|
|
|
|
* const result = await db.getMany([["foo"], ["baz"]]);
|
|
|
|
|
* result[0].key; // ["foo"]
|
|
|
|
|
* result[0].value; // "bar"
|
|
|
|
|
* result[0].versionstamp; // "00000000000000010000"
|
|
|
|
|
* result[1].key; // ["baz"]
|
|
|
|
|
* result[1].value; // null
|
|
|
|
|
* result[1].versionstamp; // null
|
|
|
|
|
* ```
|
|
|
|
|
*
|
|
|
|
|
* The `consistency` option can be used to specify the consistency level
|
|
|
|
|
* for the read operation. The default consistency level is "strong". Some
|
|
|
|
|
* use cases can benefit from using a weaker consistency level. For more
|
|
|
|
|
* information on consistency levels, see the documentation for
|
|
|
|
|
* {@linkcode Deno.KvConsistencyLevel}.
|
|
|
|
|
*/
|
2023-03-30 16:52:31 -04:00
|
|
|
|
getMany<T extends readonly unknown[]>(
|
|
|
|
|
keys: readonly [...{ [K in keyof T]: KvKey }],
|
2023-03-22 00:13:24 -04:00
|
|
|
|
options?: { consistency?: KvConsistencyLevel },
|
2023-03-30 16:52:31 -04:00
|
|
|
|
): Promise<{ [K in keyof T]: KvEntryMaybe<T[K]> }>;
|
2023-03-22 00:13:24 -04:00
|
|
|
|
/**
|
|
|
|
|
* Set the value for the given key in the database. If a value already
|
|
|
|
|
* exists for the key, it will be overwritten.
|
|
|
|
|
*
|
|
|
|
|
* ```ts
|
2023-03-22 15:23:36 -04:00
|
|
|
|
* const db = await Deno.openKv();
|
2023-03-22 00:13:24 -04:00
|
|
|
|
* await db.set(["foo"], "bar");
|
|
|
|
|
* ```
|
2023-08-18 05:34:16 -04:00
|
|
|
|
*
|
|
|
|
|
* Optionally an `expireIn` option can be specified to set a time-to-live
|
|
|
|
|
* (TTL) for the key. The TTL is specified in milliseconds, and the key will
|
|
|
|
|
* be deleted from the database at earliest after the specified number of
|
|
|
|
|
* milliseconds have elapsed. Once the specified duration has passed, the
|
|
|
|
|
* key may still be visible for some additional time. If the `expireIn`
|
|
|
|
|
* option is not specified, the key will not expire.
|
2023-03-22 00:13:24 -04:00
|
|
|
|
*/
|
2023-08-18 05:34:16 -04:00
|
|
|
|
set(
|
|
|
|
|
key: KvKey,
|
|
|
|
|
value: unknown,
|
|
|
|
|
options?: { expireIn?: number },
|
|
|
|
|
): Promise<KvCommitResult>;
|
2023-03-22 00:13:24 -04:00
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* Delete the value for the given key from the database. If no value exists
|
|
|
|
|
* for the key, this operation is a no-op.
|
|
|
|
|
*
|
|
|
|
|
* ```ts
|
2023-03-22 15:23:36 -04:00
|
|
|
|
* const db = await Deno.openKv();
|
2023-03-22 00:13:24 -04:00
|
|
|
|
* await db.delete(["foo"]);
|
|
|
|
|
* ```
|
|
|
|
|
*/
|
|
|
|
|
delete(key: KvKey): Promise<void>;
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* Retrieve a list of keys in the database. The returned list is an
|
|
|
|
|
* {@linkcode Deno.KvListIterator} which can be used to iterate over the
|
|
|
|
|
* entries in the database.
|
|
|
|
|
*
|
|
|
|
|
* Each list operation must specify a selector which is used to specify the
|
|
|
|
|
* range of keys to return. The selector can either be a prefix selector, or
|
|
|
|
|
* a range selector:
|
|
|
|
|
*
|
|
|
|
|
* - A prefix selector selects all keys that start with the given prefix of
|
|
|
|
|
* key parts. For example, the selector `["users"]` will select all keys
|
|
|
|
|
* that start with the prefix `["users"]`, such as `["users", "alice"]`
|
|
|
|
|
* and `["users", "bob"]`. Note that you can not partially match a key
|
|
|
|
|
* part, so the selector `["users", "a"]` will not match the key
|
|
|
|
|
* `["users", "alice"]`. A prefix selector may specify a `start` key that
|
|
|
|
|
* is used to skip over keys that are lexicographically less than the
|
|
|
|
|
* start key.
|
|
|
|
|
* - A range selector selects all keys that are lexicographically between
|
|
|
|
|
* the given start and end keys (including the start, and excluding the
|
|
|
|
|
* end). For example, the selector `["users", "a"], ["users", "n"]` will
|
|
|
|
|
* select all keys that start with the prefix `["users"]` and have a
|
|
|
|
|
* second key part that is lexicographically between `a` and `n`, such as
|
|
|
|
|
* `["users", "alice"]`, `["users", "bob"]`, and `["users", "mike"]`, but
|
|
|
|
|
* not `["users", "noa"]` or `["users", "zoe"]`.
|
|
|
|
|
*
|
|
|
|
|
* ```ts
|
2023-03-22 15:23:36 -04:00
|
|
|
|
* const db = await Deno.openKv();
|
2023-03-22 00:13:24 -04:00
|
|
|
|
* const entries = db.list({ prefix: ["users"] });
|
|
|
|
|
* for await (const entry of entries) {
|
|
|
|
|
* entry.key; // ["users", "alice"]
|
|
|
|
|
* entry.value; // { name: "Alice" }
|
|
|
|
|
* entry.versionstamp; // "00000000000000010000"
|
|
|
|
|
* }
|
|
|
|
|
* ```
|
|
|
|
|
*
|
|
|
|
|
* The `options` argument can be used to specify additional options for the
|
|
|
|
|
* list operation. See the documentation for {@linkcode Deno.KvListOptions}
|
|
|
|
|
* for more information.
|
|
|
|
|
*/
|
2023-03-30 16:52:31 -04:00
|
|
|
|
list<T = unknown>(
|
|
|
|
|
selector: KvListSelector,
|
|
|
|
|
options?: KvListOptions,
|
|
|
|
|
): KvListIterator<T>;
|
2023-03-22 00:13:24 -04:00
|
|
|
|
|
2023-06-13 20:49:57 -04:00
|
|
|
|
/**
|
|
|
|
|
* Add a value into the database queue to be delivered to the queue
|
|
|
|
|
* listener via {@linkcode Deno.Kv.listenQueue}.
|
|
|
|
|
*
|
|
|
|
|
* ```ts
|
|
|
|
|
* const db = await Deno.openKv();
|
|
|
|
|
* await db.enqueue("bar");
|
|
|
|
|
* ```
|
|
|
|
|
*
|
|
|
|
|
* The `delay` option can be used to specify the delay (in milliseconds)
|
|
|
|
|
* of the value delivery. The default delay is 0, which means immediate
|
|
|
|
|
* delivery.
|
|
|
|
|
*
|
|
|
|
|
* ```ts
|
|
|
|
|
* const db = await Deno.openKv();
|
|
|
|
|
* await db.enqueue("bar", { delay: 60000 });
|
|
|
|
|
* ```
|
|
|
|
|
*
|
|
|
|
|
* The `keysIfUndelivered` option can be used to specify the keys to
|
|
|
|
|
* be set if the value is not successfully delivered to the queue
|
|
|
|
|
* listener after several attempts. The values are set to the value of
|
|
|
|
|
* the queued message.
|
|
|
|
|
*
|
2023-12-13 01:51:23 -05:00
|
|
|
|
* The `backoffSchedule` option can be used to specify the retry policy for
|
|
|
|
|
* failed message delivery. Each element in the array represents the number of
|
|
|
|
|
* milliseconds to wait before retrying the delivery. For example,
|
|
|
|
|
* `[1000, 5000, 10000]` means that a failed delivery will be retried
|
|
|
|
|
* at most 3 times, with 1 second, 5 seconds, and 10 seconds delay
|
|
|
|
|
* between each retry.
|
|
|
|
|
*
|
2023-06-13 20:49:57 -04:00
|
|
|
|
* ```ts
|
|
|
|
|
* const db = await Deno.openKv();
|
2023-12-13 01:51:23 -05:00
|
|
|
|
* await db.enqueue("bar", {
|
|
|
|
|
* keysIfUndelivered: [["foo", "bar"]],
|
|
|
|
|
* backoffSchedule: [1000, 5000, 10000],
|
|
|
|
|
* });
|
2023-06-13 20:49:57 -04:00
|
|
|
|
* ```
|
|
|
|
|
*/
|
|
|
|
|
enqueue(
|
|
|
|
|
value: unknown,
|
2023-12-13 01:51:23 -05:00
|
|
|
|
options?: {
|
|
|
|
|
delay?: number;
|
|
|
|
|
keysIfUndelivered?: Deno.KvKey[];
|
|
|
|
|
backoffSchedule?: number[];
|
|
|
|
|
},
|
2023-06-13 20:49:57 -04:00
|
|
|
|
): Promise<KvCommitResult>;
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* Listen for queue values to be delivered from the database queue, which
|
|
|
|
|
* were enqueued with {@linkcode Deno.Kv.enqueue}. The provided handler
|
|
|
|
|
* callback is invoked on every dequeued value. A failed callback
|
|
|
|
|
* invocation is automatically retried multiple times until it succeeds
|
|
|
|
|
* or until the maximum number of retries is reached.
|
|
|
|
|
*
|
|
|
|
|
* ```ts
|
|
|
|
|
* const db = await Deno.openKv();
|
|
|
|
|
* db.listenQueue(async (msg: unknown) => {
|
|
|
|
|
* await db.set(["foo"], msg);
|
|
|
|
|
* });
|
|
|
|
|
* ```
|
|
|
|
|
*/
|
2024-01-06 08:42:14 -05:00
|
|
|
|
// deno-lint-ignore no-explicit-any
|
|
|
|
|
listenQueue(handler: (value: any) => Promise<void> | void): Promise<void>;
|
2023-06-13 20:49:57 -04:00
|
|
|
|
|
2023-03-22 00:13:24 -04:00
|
|
|
|
/**
|
|
|
|
|
* Create a new {@linkcode Deno.AtomicOperation} object which can be used to
|
|
|
|
|
* perform an atomic transaction on the database. This does not perform any
|
|
|
|
|
* operations on the database - the atomic transaction must be committed
|
|
|
|
|
* explicitly using the {@linkcode Deno.AtomicOperation.commit} method once
|
|
|
|
|
* all checks and mutations have been added to the operation.
|
|
|
|
|
*/
|
|
|
|
|
atomic(): AtomicOperation;
|
|
|
|
|
|
2023-12-05 08:21:46 -05:00
|
|
|
|
/**
|
|
|
|
|
* Watch for changes to the given keys in the database. The returned stream
|
|
|
|
|
* is a {@linkcode ReadableStream} that emits a new value whenever any of
|
|
|
|
|
* the watched keys change their versionstamp. The emitted value is an array
|
|
|
|
|
* of {@linkcode Deno.KvEntryMaybe} objects, with the same length and order
|
|
|
|
|
* as the `keys` array. If no value exists for a given key, the returned
|
|
|
|
|
* entry will have a `null` value and versionstamp.
|
|
|
|
|
*
|
|
|
|
|
* The returned stream does not return every single intermediate state of
|
|
|
|
|
* the watched keys, but rather only keeps you up to date with the latest
|
|
|
|
|
* state of the keys. This means that if a key is modified multiple times
|
|
|
|
|
* quickly, you may not receive a notification for every single change, but
|
|
|
|
|
* rather only the latest state of the key.
|
|
|
|
|
*
|
|
|
|
|
* ```ts
|
|
|
|
|
* const db = await Deno.openKv();
|
|
|
|
|
*
|
|
|
|
|
* const stream = db.watch([["foo"], ["bar"]]);
|
|
|
|
|
* for await (const entries of stream) {
|
|
|
|
|
* entries[0].key; // ["foo"]
|
|
|
|
|
* entries[0].value; // "bar"
|
|
|
|
|
* entries[0].versionstamp; // "00000000000000010000"
|
|
|
|
|
* entries[1].key; // ["bar"]
|
|
|
|
|
* entries[1].value; // null
|
|
|
|
|
* entries[1].versionstamp; // null
|
|
|
|
|
* }
|
|
|
|
|
* ```
|
|
|
|
|
*
|
|
|
|
|
* The `options` argument can be used to specify additional options for the
|
|
|
|
|
* watch operation. The `raw` option can be used to specify whether a new
|
|
|
|
|
* value should be emitted whenever a mutation occurs on any of the watched
|
|
|
|
|
* keys (even if the value of the key does not change, such as deleting a
|
|
|
|
|
* deleted key), or only when entries have observably changed in some way.
|
|
|
|
|
* When `raw: true` is used, it is possible for the stream to occasionally
|
|
|
|
|
* emit values even if no mutations have occurred on any of the watched
|
|
|
|
|
* keys. The default value for this option is `false`.
|
|
|
|
|
*/
|
|
|
|
|
watch<T extends readonly unknown[]>(
|
|
|
|
|
keys: readonly [...{ [K in keyof T]: KvKey }],
|
|
|
|
|
options?: { raw?: boolean },
|
|
|
|
|
): ReadableStream<{ [K in keyof T]: KvEntryMaybe<T[K]> }>;
|
|
|
|
|
|
2023-03-22 00:13:24 -04:00
|
|
|
|
/**
|
|
|
|
|
* Close the database connection. This will prevent any further operations
|
2023-05-17 00:18:47 -04:00
|
|
|
|
* from being performed on the database, and interrupt any in-flight
|
|
|
|
|
* operations immediately.
|
2023-03-22 00:13:24 -04:00
|
|
|
|
*/
|
2023-05-17 00:18:47 -04:00
|
|
|
|
close(): void;
|
2023-11-01 15:26:12 -04:00
|
|
|
|
|
2023-12-13 11:58:20 -05:00
|
|
|
|
/**
|
|
|
|
|
* Get a symbol that represents the versionstamp of the current atomic
|
|
|
|
|
* operation. This symbol can be used as the last part of a key in
|
|
|
|
|
* `.set()`, both directly on the `Kv` object and on an `AtomicOperation`
|
|
|
|
|
* object created from this `Kv` instance.
|
|
|
|
|
*/
|
|
|
|
|
commitVersionstamp(): symbol;
|
|
|
|
|
|
2023-11-01 15:26:12 -04:00
|
|
|
|
[Symbol.dispose](): void;
|
2023-03-22 00:13:24 -04:00
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
|
|
|
|
*
|
|
|
|
|
* Wrapper type for 64-bit unsigned integers for use as values in a
|
|
|
|
|
* {@linkcode Deno.Kv}.
|
|
|
|
|
*
|
|
|
|
|
* @category KV
|
|
|
|
|
*/
|
|
|
|
|
export class KvU64 {
|
|
|
|
|
/** Create a new `KvU64` instance from the given bigint value. If the value
|
|
|
|
|
* is signed or greater than 64-bits, an error will be thrown. */
|
|
|
|
|
constructor(value: bigint);
|
|
|
|
|
/** The value of this unsigned 64-bit integer, represented as a bigint. */
|
|
|
|
|
readonly value: bigint;
|
|
|
|
|
}
|
2023-09-11 20:06:38 -04:00
|
|
|
|
|
2023-09-26 20:21:06 -04:00
|
|
|
|
/**
|
|
|
|
|
* A namespace containing runtime APIs available in Jupyter notebooks.
|
|
|
|
|
*
|
|
|
|
|
* When accessed outside of Jupyter notebook context an error will be thrown.
|
|
|
|
|
*
|
|
|
|
|
* @category Jupyter */
|
|
|
|
|
export namespace jupyter {
|
2023-11-02 18:43:02 -04:00
|
|
|
|
/** @category Jupyter */
|
2023-10-12 18:32:38 -04:00
|
|
|
|
export interface DisplayOptions {
|
|
|
|
|
raw?: boolean;
|
|
|
|
|
update?: boolean;
|
|
|
|
|
display_id?: string;
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
type VegaObject = {
|
|
|
|
|
$schema: string;
|
|
|
|
|
[key: string]: unknown;
|
|
|
|
|
};
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* A collection of supported media types and data for Jupyter frontends.
|
2023-11-02 18:43:02 -04:00
|
|
|
|
*
|
|
|
|
|
* @category Jupyter
|
2023-10-12 18:32:38 -04:00
|
|
|
|
*/
|
|
|
|
|
export type MediaBundle = {
|
|
|
|
|
"text/plain"?: string;
|
|
|
|
|
"text/html"?: string;
|
|
|
|
|
"image/svg+xml"?: string;
|
|
|
|
|
"text/markdown"?: string;
|
|
|
|
|
"application/javascript"?: string;
|
|
|
|
|
|
|
|
|
|
// Images (per Jupyter spec) must be base64 encoded. We could _allow_
|
|
|
|
|
// accepting Uint8Array or ArrayBuffer within `display` calls, however we still
|
|
|
|
|
// must encode them for jupyter.
|
|
|
|
|
"image/png"?: string; // WISH: Uint8Array | ArrayBuffer
|
|
|
|
|
"image/jpeg"?: string; // WISH: Uint8Array | ArrayBuffer
|
|
|
|
|
"image/gif"?: string; // WISH: Uint8Array | ArrayBuffer
|
|
|
|
|
"application/pdf"?: string; // WISH: Uint8Array | ArrayBuffer
|
|
|
|
|
|
|
|
|
|
// NOTE: all JSON types must be objects at the top level (no arrays, strings, or other primitives)
|
|
|
|
|
"application/json"?: object;
|
|
|
|
|
"application/geo+json"?: object;
|
|
|
|
|
"application/vdom.v1+json"?: object;
|
|
|
|
|
"application/vnd.plotly.v1+json"?: object;
|
|
|
|
|
"application/vnd.vega.v5+json"?: VegaObject;
|
|
|
|
|
"application/vnd.vegalite.v4+json"?: VegaObject;
|
|
|
|
|
"application/vnd.vegalite.v5+json"?: VegaObject;
|
|
|
|
|
|
|
|
|
|
// Must support a catch all for custom media types / mimetypes
|
|
|
|
|
[key: string]: string | object | undefined;
|
|
|
|
|
};
|
|
|
|
|
|
2023-11-02 18:43:02 -04:00
|
|
|
|
/** @category Jupyter */
|
2023-10-12 18:32:38 -04:00
|
|
|
|
export const $display: unique symbol;
|
|
|
|
|
|
2023-11-02 18:43:02 -04:00
|
|
|
|
/** @category Jupyter */
|
2023-10-12 18:32:38 -04:00
|
|
|
|
export type Displayable = {
|
|
|
|
|
[$display]: () => MediaBundle | Promise<MediaBundle>;
|
|
|
|
|
};
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* Display function for Jupyter Deno Kernel.
|
|
|
|
|
* Mimics the behavior of IPython's `display(obj, raw=True)` function to allow
|
|
|
|
|
* asynchronous displaying of objects in Jupyter.
|
|
|
|
|
*
|
|
|
|
|
* @param obj - The object to be displayed
|
|
|
|
|
* @param options - Display options with a default { raw: true }
|
2023-11-02 18:43:02 -04:00
|
|
|
|
* @category Jupyter
|
2023-10-12 18:32:38 -04:00
|
|
|
|
*/
|
|
|
|
|
export function display(obj: unknown, options?: DisplayOptions): void;
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* Show Markdown in Jupyter frontends with a tagged template function.
|
|
|
|
|
*
|
|
|
|
|
* Takes a template string and returns a displayable object for Jupyter frontends.
|
|
|
|
|
*
|
|
|
|
|
* @example
|
|
|
|
|
* Create a Markdown view.
|
|
|
|
|
*
|
|
|
|
|
* ```typescript
|
|
|
|
|
* const { md } = Deno.jupyter;
|
|
|
|
|
* md`# Notebooks in TypeScript via Deno ![Deno logo](https://github.com/denoland.png?size=32)
|
|
|
|
|
*
|
|
|
|
|
* * TypeScript ${Deno.version.typescript}
|
|
|
|
|
* * V8 ${Deno.version.v8}
|
|
|
|
|
* * Deno ${Deno.version.deno}
|
|
|
|
|
*
|
|
|
|
|
* Interactive compute with Jupyter _built into Deno_!
|
|
|
|
|
* `
|
|
|
|
|
* ```
|
2023-11-02 18:43:02 -04:00
|
|
|
|
*
|
|
|
|
|
* @category Jupyter
|
2023-10-12 18:32:38 -04:00
|
|
|
|
*/
|
|
|
|
|
export function md(
|
|
|
|
|
strings: TemplateStringsArray,
|
|
|
|
|
...values: unknown[]
|
|
|
|
|
): Displayable;
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* Show HTML in Jupyter frontends with a tagged template function.
|
|
|
|
|
*
|
|
|
|
|
* Takes a template string and returns a displayable object for Jupyter frontends.
|
|
|
|
|
*
|
|
|
|
|
* @example
|
|
|
|
|
* Create an HTML view.
|
|
|
|
|
* ```typescript
|
|
|
|
|
* const { html } = Deno.jupyter;
|
|
|
|
|
* html`<h1>Hello, world!</h1>`
|
|
|
|
|
* ```
|
2023-11-02 18:43:02 -04:00
|
|
|
|
*
|
|
|
|
|
* @category Jupyter
|
2023-10-12 18:32:38 -04:00
|
|
|
|
*/
|
|
|
|
|
export function html(
|
|
|
|
|
strings: TemplateStringsArray,
|
|
|
|
|
...values: unknown[]
|
|
|
|
|
): Displayable;
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* SVG Tagged Template Function.
|
|
|
|
|
*
|
|
|
|
|
* Takes a template string and returns a displayable object for Jupyter frontends.
|
|
|
|
|
*
|
|
|
|
|
* Example usage:
|
|
|
|
|
*
|
|
|
|
|
* svg`<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100">
|
|
|
|
|
* <circle cx="50" cy="50" r="40" stroke="green" stroke-width="4" fill="yellow" />
|
|
|
|
|
* </svg>`
|
2023-11-02 18:43:02 -04:00
|
|
|
|
*
|
|
|
|
|
* @category Jupyter
|
2023-10-12 18:32:38 -04:00
|
|
|
|
*/
|
|
|
|
|
export function svg(
|
|
|
|
|
strings: TemplateStringsArray,
|
|
|
|
|
...values: unknown[]
|
|
|
|
|
): Displayable;
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* Format an object for displaying in Deno
|
|
|
|
|
*
|
|
|
|
|
* @param obj - The object to be displayed
|
|
|
|
|
* @returns MediaBundle
|
2023-11-02 18:43:02 -04:00
|
|
|
|
*
|
|
|
|
|
* @category Jupyter
|
2023-10-12 18:32:38 -04:00
|
|
|
|
*/
|
|
|
|
|
export function format(obj: unknown): MediaBundle;
|
|
|
|
|
|
2023-09-26 20:21:06 -04:00
|
|
|
|
/**
|
|
|
|
|
* Broadcast a message on IO pub channel.
|
|
|
|
|
*
|
|
|
|
|
* ```
|
|
|
|
|
* await Deno.jupyter.broadcast("display_data", {
|
|
|
|
|
* data: { "text/html": "<b>Processing.</b>" },
|
|
|
|
|
* metadata: {},
|
|
|
|
|
* transient: { display_id: "progress" }
|
|
|
|
|
* });
|
|
|
|
|
*
|
|
|
|
|
* await new Promise((resolve) => setTimeout(resolve, 500));
|
|
|
|
|
*
|
|
|
|
|
* await Deno.jupyter.broadcast("update_display_data", {
|
|
|
|
|
* data: { "text/html": "<b>Processing..</b>" },
|
|
|
|
|
* metadata: {},
|
|
|
|
|
* transient: { display_id: "progress" }
|
|
|
|
|
* });
|
|
|
|
|
* ```
|
|
|
|
|
*
|
|
|
|
|
* @category Jupyter */
|
|
|
|
|
export function broadcast(
|
|
|
|
|
msgType: string,
|
|
|
|
|
content: Record<string, unknown>,
|
2023-09-29 18:24:09 -04:00
|
|
|
|
extra?: {
|
|
|
|
|
metadata?: Record<string, unknown>;
|
2023-10-04 07:05:20 -04:00
|
|
|
|
buffers?: Uint8Array[];
|
2023-09-29 18:24:09 -04:00
|
|
|
|
},
|
2023-09-26 20:21:06 -04:00
|
|
|
|
): Promise<void>;
|
|
|
|
|
}
|
2020-04-30 11:23:40 -04:00
|
|
|
|
}
|
2020-08-05 14:44:03 -04:00
|
|
|
|
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
2022-10-26 09:53:48 -04:00
|
|
|
|
*
|
|
|
|
|
* 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.
|
2022-09-15 10:37:35 -04:00
|
|
|
|
*
|
2022-08-22 20:57:01 -04:00
|
|
|
|
* @tags allow-net, allow-read
|
|
|
|
|
* @category Fetch API
|
|
|
|
|
*/
|
2020-08-05 14:44:03 -04:00
|
|
|
|
declare function fetch(
|
|
|
|
|
input: Request | URL | string,
|
|
|
|
|
init?: RequestInit & { client: Deno.HttpClient },
|
|
|
|
|
): Promise<Response>;
|
2021-01-29 08:15:59 -05:00
|
|
|
|
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
|
|
|
|
*
|
|
|
|
|
* @category Web Workers
|
|
|
|
|
*/
|
2021-01-29 08:15:59 -05:00
|
|
|
|
declare interface WorkerOptions {
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
2022-09-15 08:09:23 -04:00
|
|
|
|
*
|
|
|
|
|
* Configure permissions options to change the level of access the worker will
|
2022-03-24 11:27:24 -04:00
|
|
|
|
* have. By default it will have no permissions. Note that the permissions
|
2021-01-29 08:15:59 -05:00
|
|
|
|
* of a worker can't be extended beyond its parent's permissions reach.
|
2022-10-26 09:53:48 -04:00
|
|
|
|
*
|
|
|
|
|
* - `"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)
|
2021-01-29 08:15:59 -05:00
|
|
|
|
*
|
|
|
|
|
* Example:
|
|
|
|
|
*
|
|
|
|
|
* ```ts
|
|
|
|
|
* // mod.ts
|
|
|
|
|
* const worker = new Worker(
|
|
|
|
|
* new URL("deno_worker.ts", import.meta.url).href, {
|
|
|
|
|
* type: "module",
|
|
|
|
|
* deno: {
|
|
|
|
|
* permissions: {
|
|
|
|
|
* read: true,
|
|
|
|
|
* },
|
|
|
|
|
* },
|
|
|
|
|
* }
|
|
|
|
|
* );
|
|
|
|
|
* ```
|
|
|
|
|
*/
|
2022-05-17 16:27:17 -04:00
|
|
|
|
deno?: {
|
2021-01-29 08:15:59 -05:00
|
|
|
|
/** Set to `"none"` to disable all the permissions in the worker. */
|
2022-03-10 19:35:33 -05:00
|
|
|
|
permissions?: Deno.PermissionOptions;
|
2021-01-29 08:15:59 -05:00
|
|
|
|
};
|
|
|
|
|
}
|
2021-08-09 18:28:17 -04:00
|
|
|
|
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
|
|
|
|
*
|
|
|
|
|
* @category Web Sockets
|
|
|
|
|
*/
|
2021-08-09 18:28:17 -04:00
|
|
|
|
declare interface WebSocketStreamOptions {
|
|
|
|
|
protocols?: string[];
|
|
|
|
|
signal?: AbortSignal;
|
2022-01-05 11:41:44 -05:00
|
|
|
|
headers?: HeadersInit;
|
2021-08-09 18:28:17 -04:00
|
|
|
|
}
|
|
|
|
|
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
|
|
|
|
*
|
|
|
|
|
* @category Web Sockets
|
|
|
|
|
*/
|
2021-08-09 18:28:17 -04:00
|
|
|
|
declare interface WebSocketConnection {
|
|
|
|
|
readable: ReadableStream<string | Uint8Array>;
|
|
|
|
|
writable: WritableStream<string | Uint8Array>;
|
|
|
|
|
extensions: string;
|
|
|
|
|
protocol: string;
|
|
|
|
|
}
|
|
|
|
|
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
|
|
|
|
*
|
|
|
|
|
* @category Web Sockets
|
|
|
|
|
*/
|
2021-08-09 18:28:17 -04:00
|
|
|
|
declare interface WebSocketCloseInfo {
|
|
|
|
|
code?: number;
|
|
|
|
|
reason?: string;
|
|
|
|
|
}
|
|
|
|
|
|
2022-09-15 10:37:35 -04:00
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
|
|
|
|
*
|
2022-08-22 20:57:01 -04:00
|
|
|
|
* @tags allow-net
|
|
|
|
|
* @category Web Sockets
|
|
|
|
|
*/
|
2023-07-03 14:36:55 -04:00
|
|
|
|
declare interface WebSocketStream {
|
2021-08-09 18:28:17 -04:00
|
|
|
|
url: string;
|
2023-10-11 01:31:05 -04:00
|
|
|
|
opened: Promise<WebSocketConnection>;
|
2021-08-09 18:28:17 -04:00
|
|
|
|
closed: Promise<WebSocketCloseInfo>;
|
|
|
|
|
close(closeInfo?: WebSocketCloseInfo): void;
|
|
|
|
|
}
|
2023-07-03 14:36:55 -04:00
|
|
|
|
|
|
|
|
|
/** **UNSTABLE**: New API, yet to be vetted.
|
|
|
|
|
*
|
|
|
|
|
* @tags allow-net
|
|
|
|
|
* @category Web Sockets
|
|
|
|
|
*/
|
|
|
|
|
declare var WebSocketStream: {
|
|
|
|
|
readonly prototype: WebSocketStream;
|
|
|
|
|
new (url: string, options?: WebSocketStreamOptions): WebSocketStream;
|
|
|
|
|
};
|
2024-01-14 19:26:57 -05:00
|
|
|
|
|
|
|
|
|
// Adapted from `tc39/proposal-temporal`: https://github.com/tc39/proposal-temporal/blob/main/polyfill/index.d.ts
|
|
|
|
|
|
|
|
|
|
declare namespace Temporal {
|
|
|
|
|
export type ComparisonResult = -1 | 0 | 1;
|
|
|
|
|
export type RoundingMode =
|
|
|
|
|
| "ceil"
|
|
|
|
|
| "floor"
|
|
|
|
|
| "expand"
|
|
|
|
|
| "trunc"
|
|
|
|
|
| "halfCeil"
|
|
|
|
|
| "halfFloor"
|
|
|
|
|
| "halfExpand"
|
|
|
|
|
| "halfTrunc"
|
|
|
|
|
| "halfEven";
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* Options for assigning fields using `with()` or entire objects with
|
|
|
|
|
* `from()`.
|
|
|
|
|
*/
|
|
|
|
|
export type AssignmentOptions = {
|
|
|
|
|
/**
|
|
|
|
|
* How to deal with out-of-range values
|
|
|
|
|
*
|
|
|
|
|
* - In `'constrain'` mode, out-of-range values are clamped to the nearest
|
|
|
|
|
* in-range value.
|
|
|
|
|
* - In `'reject'` mode, out-of-range values will cause the function to
|
|
|
|
|
* throw a RangeError.
|
|
|
|
|
*
|
|
|
|
|
* The default is `'constrain'`.
|
|
|
|
|
*/
|
|
|
|
|
overflow?: "constrain" | "reject";
|
|
|
|
|
};
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* Options for assigning fields using `Duration.prototype.with()` or entire
|
|
|
|
|
* objects with `Duration.from()`, and for arithmetic with
|
|
|
|
|
* `Duration.prototype.add()` and `Duration.prototype.subtract()`.
|
|
|
|
|
*/
|
|
|
|
|
export type DurationOptions = {
|
|
|
|
|
/**
|
|
|
|
|
* How to deal with out-of-range values
|
|
|
|
|
*
|
|
|
|
|
* - In `'constrain'` mode, out-of-range values are clamped to the nearest
|
|
|
|
|
* in-range value.
|
|
|
|
|
* - In `'balance'` mode, out-of-range values are resolved by balancing them
|
|
|
|
|
* with the next highest unit.
|
|
|
|
|
*
|
|
|
|
|
* The default is `'constrain'`.
|
|
|
|
|
*/
|
|
|
|
|
overflow?: "constrain" | "balance";
|
|
|
|
|
};
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* Options for conversions of `Temporal.PlainDateTime` to `Temporal.Instant`
|
|
|
|
|
*/
|
|
|
|
|
export type ToInstantOptions = {
|
|
|
|
|
/**
|
|
|
|
|
* Controls handling of invalid or ambiguous times caused by time zone
|
|
|
|
|
* offset changes like Daylight Saving time (DST) transitions.
|
|
|
|
|
*
|
|
|
|
|
* This option is only relevant if a `DateTime` value does not exist in the
|
|
|
|
|
* destination time zone (e.g. near "Spring Forward" DST transitions), or
|
|
|
|
|
* exists more than once (e.g. near "Fall Back" DST transitions).
|
|
|
|
|
*
|
|
|
|
|
* In case of ambiguous or nonexistent times, this option controls what
|
|
|
|
|
* exact time to return:
|
|
|
|
|
* - `'compatible'`: Equivalent to `'earlier'` for backward transitions like
|
|
|
|
|
* the start of DST in the Spring, and `'later'` for forward transitions
|
|
|
|
|
* like the end of DST in the Fall. This matches the behavior of legacy
|
|
|
|
|
* `Date`, of libraries like moment.js, Luxon, or date-fns, and of
|
|
|
|
|
* cross-platform standards like [RFC 5545
|
|
|
|
|
* (iCalendar)](https://tools.ietf.org/html/rfc5545).
|
|
|
|
|
* - `'earlier'`: The earlier time of two possible times
|
|
|
|
|
* - `'later'`: The later of two possible times
|
|
|
|
|
* - `'reject'`: Throw a RangeError instead
|
|
|
|
|
*
|
|
|
|
|
* The default is `'compatible'`.
|
|
|
|
|
*/
|
|
|
|
|
disambiguation?: "compatible" | "earlier" | "later" | "reject";
|
|
|
|
|
};
|
|
|
|
|
|
|
|
|
|
type OffsetDisambiguationOptions = {
|
|
|
|
|
/**
|
|
|
|
|
* Time zone definitions can change. If an application stores data about
|
|
|
|
|
* events in the future, then stored data about future events may become
|
|
|
|
|
* ambiguous, for example if a country permanently abolishes DST. The
|
|
|
|
|
* `offset` option controls this unusual case.
|
|
|
|
|
*
|
|
|
|
|
* - `'use'` always uses the offset (if it's provided) to calculate the
|
|
|
|
|
* instant. This ensures that the result will match the instant that was
|
|
|
|
|
* originally stored, even if local clock time is different.
|
|
|
|
|
* - `'prefer'` uses the offset if it's valid for the date/time in this time
|
|
|
|
|
* zone, but if it's not valid then the time zone will be used as a
|
|
|
|
|
* fallback to calculate the instant.
|
|
|
|
|
* - `'ignore'` will disregard any provided offset. Instead, the time zone
|
|
|
|
|
* and date/time value are used to calculate the instant. This will keep
|
|
|
|
|
* local clock time unchanged but may result in a different real-world
|
|
|
|
|
* instant.
|
|
|
|
|
* - `'reject'` acts like `'prefer'`, except it will throw a RangeError if
|
|
|
|
|
* the offset is not valid for the given time zone identifier and
|
|
|
|
|
* date/time value.
|
|
|
|
|
*
|
|
|
|
|
* If the ISO string ends in 'Z' then this option is ignored because there
|
|
|
|
|
* is no possibility of ambiguity.
|
|
|
|
|
*
|
|
|
|
|
* If a time zone offset is not present in the input, then this option is
|
|
|
|
|
* ignored because the time zone will always be used to calculate the
|
|
|
|
|
* offset.
|
|
|
|
|
*
|
|
|
|
|
* If the offset is not used, and if the date/time and time zone don't
|
|
|
|
|
* uniquely identify a single instant, then the `disambiguation` option will
|
|
|
|
|
* be used to choose the correct instant. However, if the offset is used
|
|
|
|
|
* then the `disambiguation` option will be ignored.
|
|
|
|
|
*/
|
|
|
|
|
offset?: "use" | "prefer" | "ignore" | "reject";
|
|
|
|
|
};
|
|
|
|
|
|
|
|
|
|
export type ZonedDateTimeAssignmentOptions = Partial<
|
|
|
|
|
AssignmentOptions & ToInstantOptions & OffsetDisambiguationOptions
|
|
|
|
|
>;
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* Options for arithmetic operations like `add()` and `subtract()`
|
|
|
|
|
*/
|
|
|
|
|
export type ArithmeticOptions = {
|
|
|
|
|
/**
|
|
|
|
|
* Controls handling of out-of-range arithmetic results.
|
|
|
|
|
*
|
|
|
|
|
* If a result is out of range, then `'constrain'` will clamp the result to
|
|
|
|
|
* the allowed range, while `'reject'` will throw a RangeError.
|
|
|
|
|
*
|
|
|
|
|
* The default is `'constrain'`.
|
|
|
|
|
*/
|
|
|
|
|
overflow?: "constrain" | "reject";
|
|
|
|
|
};
|
|
|
|
|
|
|
|
|
|
export type DateUnit = "year" | "month" | "week" | "day";
|
|
|
|
|
export type TimeUnit =
|
|
|
|
|
| "hour"
|
|
|
|
|
| "minute"
|
|
|
|
|
| "second"
|
|
|
|
|
| "millisecond"
|
|
|
|
|
| "microsecond"
|
|
|
|
|
| "nanosecond";
|
|
|
|
|
export type DateTimeUnit = DateUnit | TimeUnit;
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* When the name of a unit is provided to a Temporal API as a string, it is
|
|
|
|
|
* usually singular, e.g. 'day' or 'hour'. But plural unit names like 'days'
|
|
|
|
|
* or 'hours' are aso accepted too.
|
|
|
|
|
*/
|
|
|
|
|
export type PluralUnit<T extends DateTimeUnit> = {
|
|
|
|
|
year: "years";
|
|
|
|
|
month: "months";
|
|
|
|
|
week: "weeks";
|
|
|
|
|
day: "days";
|
|
|
|
|
hour: "hours";
|
|
|
|
|
minute: "minutes";
|
|
|
|
|
second: "seconds";
|
|
|
|
|
millisecond: "milliseconds";
|
|
|
|
|
microsecond: "microseconds";
|
|
|
|
|
nanosecond: "nanoseconds";
|
|
|
|
|
}[T];
|
|
|
|
|
|
|
|
|
|
export type LargestUnit<T extends DateTimeUnit> = "auto" | T | PluralUnit<T>;
|
|
|
|
|
export type SmallestUnit<T extends DateTimeUnit> = T | PluralUnit<T>;
|
|
|
|
|
export type TotalUnit<T extends DateTimeUnit> = T | PluralUnit<T>;
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* Options for outputting precision in toString() on types with seconds
|
|
|
|
|
*/
|
|
|
|
|
export type ToStringPrecisionOptions = {
|
|
|
|
|
fractionalSecondDigits?: "auto" | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9;
|
|
|
|
|
smallestUnit?: SmallestUnit<
|
|
|
|
|
"minute" | "second" | "millisecond" | "microsecond" | "nanosecond"
|
|
|
|
|
>;
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* Controls how rounding is performed:
|
|
|
|
|
* - `halfExpand`: Round to the nearest of the values allowed by
|
|
|
|
|
* `roundingIncrement` and `smallestUnit`. When there is a tie, round up.
|
|
|
|
|
* This mode is the default.
|
|
|
|
|
* - `ceil`: Always round up, towards the end of time.
|
|
|
|
|
* - `trunc`: Always round down, towards the beginning of time.
|
|
|
|
|
* - `floor`: Also round down, towards the beginning of time. This mode acts
|
|
|
|
|
* the same as `trunc`, but it's included for consistency with
|
|
|
|
|
* `Temporal.Duration.round()` where negative values are allowed and
|
|
|
|
|
* `trunc` rounds towards zero, unlike `floor` which rounds towards
|
|
|
|
|
* negative infinity which is usually unexpected. For this reason, `trunc`
|
|
|
|
|
* is recommended for most use cases.
|
|
|
|
|
*/
|
|
|
|
|
roundingMode?: RoundingMode;
|
|
|
|
|
};
|
|
|
|
|
|
|
|
|
|
export type ShowCalendarOption = {
|
|
|
|
|
calendarName?: "auto" | "always" | "never" | "critical";
|
|
|
|
|
};
|
|
|
|
|
|
|
|
|
|
export type CalendarTypeToStringOptions = Partial<
|
|
|
|
|
ToStringPrecisionOptions & ShowCalendarOption
|
|
|
|
|
>;
|
|
|
|
|
|
|
|
|
|
export type ZonedDateTimeToStringOptions = Partial<
|
|
|
|
|
CalendarTypeToStringOptions & {
|
|
|
|
|
timeZoneName?: "auto" | "never" | "critical";
|
|
|
|
|
offset?: "auto" | "never";
|
|
|
|
|
}
|
|
|
|
|
>;
|
|
|
|
|
|
|
|
|
|
export type InstantToStringOptions = Partial<
|
|
|
|
|
ToStringPrecisionOptions & {
|
|
|
|
|
timeZone: TimeZoneLike;
|
|
|
|
|
}
|
|
|
|
|
>;
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* Options to control the result of `until()` and `since()` methods in
|
|
|
|
|
* `Temporal` types.
|
|
|
|
|
*/
|
|
|
|
|
export interface DifferenceOptions<T extends DateTimeUnit> {
|
|
|
|
|
/**
|
|
|
|
|
* The unit to round to. For example, to round to the nearest minute, use
|
|
|
|
|
* `smallestUnit: 'minute'`. This property is optional for `until()` and
|
|
|
|
|
* `since()`, because those methods default behavior is not to round.
|
|
|
|
|
* However, the same property is required for `round()`.
|
|
|
|
|
*/
|
|
|
|
|
smallestUnit?: SmallestUnit<T>;
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* The largest unit to allow in the resulting `Temporal.Duration` object.
|
|
|
|
|
*
|
|
|
|
|
* Larger units will be "balanced" into smaller units. For example, if
|
|
|
|
|
* `largestUnit` is `'minute'` then a two-hour duration will be output as a
|
|
|
|
|
* 120-minute duration.
|
|
|
|
|
*
|
|
|
|
|
* Valid values may include `'year'`, `'month'`, `'week'`, `'day'`,
|
|
|
|
|
* `'hour'`, `'minute'`, `'second'`, `'millisecond'`, `'microsecond'`,
|
|
|
|
|
* `'nanosecond'` and `'auto'`, although some types may throw an exception
|
|
|
|
|
* if a value is used that would produce an invalid result. For example,
|
|
|
|
|
* `hours` is not accepted by `Temporal.PlainDate.prototype.since()`.
|
|
|
|
|
*
|
|
|
|
|
* The default is always `'auto'`, though the meaning of this depends on the
|
|
|
|
|
* type being used.
|
|
|
|
|
*/
|
|
|
|
|
largestUnit?: LargestUnit<T>;
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* Allows rounding to an integer number of units. For example, to round to
|
|
|
|
|
* increments of a half hour, use `{ smallestUnit: 'minute',
|
|
|
|
|
* roundingIncrement: 30 }`.
|
|
|
|
|
*/
|
|
|
|
|
roundingIncrement?: number;
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* Controls how rounding is performed:
|
|
|
|
|
* - `halfExpand`: Round to the nearest of the values allowed by
|
|
|
|
|
* `roundingIncrement` and `smallestUnit`. When there is a tie, round away
|
|
|
|
|
* from zero like `ceil` for positive durations and like `floor` for
|
|
|
|
|
* negative durations.
|
|
|
|
|
* - `ceil`: Always round up, towards the end of time.
|
|
|
|
|
* - `trunc`: Always round down, towards the beginning of time. This mode is
|
|
|
|
|
* the default.
|
|
|
|
|
* - `floor`: Also round down, towards the beginning of time. This mode acts
|
|
|
|
|
* the same as `trunc`, but it's included for consistency with
|
|
|
|
|
* `Temporal.Duration.round()` where negative values are allowed and
|
|
|
|
|
* `trunc` rounds towards zero, unlike `floor` which rounds towards
|
|
|
|
|
* negative infinity which is usually unexpected. For this reason, `trunc`
|
|
|
|
|
* is recommended for most use cases.
|
|
|
|
|
*/
|
|
|
|
|
roundingMode?: RoundingMode;
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* `round` methods take one required parameter. If a string is provided, the
|
|
|
|
|
* resulting `Temporal.Duration` object will be rounded to that unit. If an
|
|
|
|
|
* object is provided, its `smallestUnit` property is required while other
|
|
|
|
|
* properties are optional. A string is treated the same as an object whose
|
|
|
|
|
* `smallestUnit` property value is that string.
|
|
|
|
|
*/
|
|
|
|
|
export type RoundTo<T extends DateTimeUnit> =
|
|
|
|
|
| SmallestUnit<T>
|
|
|
|
|
| {
|
|
|
|
|
/**
|
|
|
|
|
* The unit to round to. For example, to round to the nearest minute,
|
|
|
|
|
* use `smallestUnit: 'minute'`. This option is required. Note that the
|
|
|
|
|
* same-named property is optional when passed to `until` or `since`
|
|
|
|
|
* methods, because those methods do no rounding by default.
|
|
|
|
|
*/
|
|
|
|
|
smallestUnit: SmallestUnit<T>;
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* Allows rounding to an integer number of units. For example, to round to
|
|
|
|
|
* increments of a half hour, use `{ smallestUnit: 'minute',
|
|
|
|
|
* roundingIncrement: 30 }`.
|
|
|
|
|
*/
|
|
|
|
|
roundingIncrement?: number;
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* Controls how rounding is performed:
|
|
|
|
|
* - `halfExpand`: Round to the nearest of the values allowed by
|
|
|
|
|
* `roundingIncrement` and `smallestUnit`. When there is a tie, round up.
|
|
|
|
|
* This mode is the default.
|
|
|
|
|
* - `ceil`: Always round up, towards the end of time.
|
|
|
|
|
* - `trunc`: Always round down, towards the beginning of time.
|
|
|
|
|
* - `floor`: Also round down, towards the beginning of time. This mode acts
|
|
|
|
|
* the same as `trunc`, but it's included for consistency with
|
|
|
|
|
* `Temporal.Duration.round()` where negative values are allowed and
|
|
|
|
|
* `trunc` rounds towards zero, unlike `floor` which rounds towards
|
|
|
|
|
* negative infinity which is usually unexpected. For this reason, `trunc`
|
|
|
|
|
* is recommended for most use cases.
|
|
|
|
|
*/
|
|
|
|
|
roundingMode?: RoundingMode;
|
|
|
|
|
};
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* The `round` method of the `Temporal.Duration` accepts one required
|
|
|
|
|
* parameter. If a string is provided, the resulting `Temporal.Duration`
|
|
|
|
|
* object will be rounded to that unit. If an object is provided, the
|
|
|
|
|
* `smallestUnit` and/or `largestUnit` property is required, while other
|
|
|
|
|
* properties are optional. A string parameter is treated the same as an
|
|
|
|
|
* object whose `smallestUnit` property value is that string.
|
|
|
|
|
*/
|
|
|
|
|
export type DurationRoundTo =
|
|
|
|
|
| SmallestUnit<DateTimeUnit>
|
|
|
|
|
| (
|
|
|
|
|
& (
|
|
|
|
|
| {
|
|
|
|
|
/**
|
|
|
|
|
* The unit to round to. For example, to round to the nearest
|
|
|
|
|
* minute, use `smallestUnit: 'minute'`. This property is normally
|
|
|
|
|
* required, but is optional if `largestUnit` is provided and not
|
|
|
|
|
* undefined.
|
|
|
|
|
*/
|
|
|
|
|
smallestUnit: SmallestUnit<DateTimeUnit>;
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* The largest unit to allow in the resulting `Temporal.Duration`
|
|
|
|
|
* object.
|
|
|
|
|
*
|
|
|
|
|
* Larger units will be "balanced" into smaller units. For example,
|
|
|
|
|
* if `largestUnit` is `'minute'` then a two-hour duration will be
|
|
|
|
|
* output as a 120-minute duration.
|
|
|
|
|
*
|
|
|
|
|
* Valid values include `'year'`, `'month'`, `'week'`, `'day'`,
|
|
|
|
|
* `'hour'`, `'minute'`, `'second'`, `'millisecond'`,
|
|
|
|
|
* `'microsecond'`, `'nanosecond'` and `'auto'`.
|
|
|
|
|
*
|
|
|
|
|
* The default is `'auto'`, which means "the largest nonzero unit in
|
|
|
|
|
* the input duration". This default prevents expanding durations to
|
|
|
|
|
* larger units unless the caller opts into this behavior.
|
|
|
|
|
*
|
|
|
|
|
* If `smallestUnit` is larger, then `smallestUnit` will be used as
|
|
|
|
|
* `largestUnit`, superseding a caller-supplied or default value.
|
|
|
|
|
*/
|
|
|
|
|
largestUnit?: LargestUnit<DateTimeUnit>;
|
|
|
|
|
}
|
|
|
|
|
| {
|
|
|
|
|
/**
|
|
|
|
|
* The unit to round to. For example, to round to the nearest
|
|
|
|
|
* minute, use `smallestUnit: 'minute'`. This property is normally
|
|
|
|
|
* required, but is optional if `largestUnit` is provided and not
|
|
|
|
|
* undefined.
|
|
|
|
|
*/
|
|
|
|
|
smallestUnit?: SmallestUnit<DateTimeUnit>;
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* The largest unit to allow in the resulting `Temporal.Duration`
|
|
|
|
|
* object.
|
|
|
|
|
*
|
|
|
|
|
* Larger units will be "balanced" into smaller units. For example,
|
|
|
|
|
* if `largestUnit` is `'minute'` then a two-hour duration will be
|
|
|
|
|
* output as a 120-minute duration.
|
|
|
|
|
*
|
|
|
|
|
* Valid values include `'year'`, `'month'`, `'week'`, `'day'`,
|
|
|
|
|
* `'hour'`, `'minute'`, `'second'`, `'millisecond'`,
|
|
|
|
|
* `'microsecond'`, `'nanosecond'` and `'auto'`.
|
|
|
|
|
*
|
|
|
|
|
* The default is `'auto'`, which means "the largest nonzero unit in
|
|
|
|
|
* the input duration". This default prevents expanding durations to
|
|
|
|
|
* larger units unless the caller opts into this behavior.
|
|
|
|
|
*
|
|
|
|
|
* If `smallestUnit` is larger, then `smallestUnit` will be used as
|
|
|
|
|
* `largestUnit`, superseding a caller-supplied or default value.
|
|
|
|
|
*/
|
|
|
|
|
largestUnit: LargestUnit<DateTimeUnit>;
|
|
|
|
|
}
|
|
|
|
|
)
|
|
|
|
|
& {
|
|
|
|
|
/**
|
|
|
|
|
* Allows rounding to an integer number of units. For example, to round
|
|
|
|
|
* to increments of a half hour, use `{ smallestUnit: 'minute',
|
|
|
|
|
* roundingIncrement: 30 }`.
|
|
|
|
|
*/
|
|
|
|
|
roundingIncrement?: number;
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* Controls how rounding is performed:
|
|
|
|
|
* - `halfExpand`: Round to the nearest of the values allowed by
|
|
|
|
|
* `roundingIncrement` and `smallestUnit`. When there is a tie, round
|
|
|
|
|
* away from zero like `ceil` for positive durations and like `floor`
|
|
|
|
|
* for negative durations. This mode is the default.
|
|
|
|
|
* - `ceil`: Always round towards positive infinity. For negative
|
|
|
|
|
* durations this option will decrease the absolute value of the
|
|
|
|
|
* duration which may be unexpected. To round away from zero, use
|
|
|
|
|
* `ceil` for positive durations and `floor` for negative durations.
|
|
|
|
|
* - `trunc`: Always round down towards zero.
|
|
|
|
|
* - `floor`: Always round towards negative infinity. This mode acts the
|
|
|
|
|
* same as `trunc` for positive durations but for negative durations
|
|
|
|
|
* it will increase the absolute value of the result which may be
|
|
|
|
|
* unexpected. For this reason, `trunc` is recommended for most "round
|
|
|
|
|
* down" use cases.
|
|
|
|
|
*/
|
|
|
|
|
roundingMode?: RoundingMode;
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* The starting point to use for rounding and conversions when
|
|
|
|
|
* variable-length units (years, months, weeks depending on the
|
|
|
|
|
* calendar) are involved. This option is required if any of the
|
|
|
|
|
* following are true:
|
|
|
|
|
* - `unit` is `'week'` or larger units
|
|
|
|
|
* - `this` has a nonzero value for `weeks` or larger units
|
|
|
|
|
*
|
|
|
|
|
* This value must be either a `Temporal.PlainDateTime`, a
|
|
|
|
|
* `Temporal.ZonedDateTime`, or a string or object value that can be
|
|
|
|
|
* passed to `from()` of those types. Examples:
|
|
|
|
|
* - `'2020-01'01T00:00-08:00[America/Los_Angeles]'`
|
|
|
|
|
* - `'2020-01'01'`
|
|
|
|
|
* - `Temporal.PlainDate.from('2020-01-01')`
|
|
|
|
|
*
|
|
|
|
|
* `Temporal.ZonedDateTime` will be tried first because it's more
|
|
|
|
|
* specific, with `Temporal.PlainDateTime` as a fallback.
|
|
|
|
|
*
|
|
|
|
|
* If the value resolves to a `Temporal.ZonedDateTime`, then operation
|
|
|
|
|
* will adjust for DST and other time zone transitions. Otherwise
|
|
|
|
|
* (including if this option is omitted), then the operation will ignore
|
|
|
|
|
* time zone transitions and all days will be assumed to be 24 hours
|
|
|
|
|
* long.
|
|
|
|
|
*/
|
|
|
|
|
relativeTo?:
|
|
|
|
|
| Temporal.PlainDateTime
|
|
|
|
|
| Temporal.ZonedDateTime
|
|
|
|
|
| PlainDateTimeLike
|
|
|
|
|
| ZonedDateTimeLike
|
|
|
|
|
| string;
|
|
|
|
|
}
|
|
|
|
|
);
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* Options to control behavior of `Duration.prototype.total()`
|
|
|
|
|
*/
|
|
|
|
|
export type DurationTotalOf =
|
|
|
|
|
| TotalUnit<DateTimeUnit>
|
|
|
|
|
| {
|
|
|
|
|
/**
|
|
|
|
|
* The unit to convert the duration to. This option is required.
|
|
|
|
|
*/
|
|
|
|
|
unit: TotalUnit<DateTimeUnit>;
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* The starting point to use when variable-length units (years, months,
|
|
|
|
|
* weeks depending on the calendar) are involved. This option is required if
|
|
|
|
|
* any of the following are true:
|
|
|
|
|
* - `unit` is `'week'` or larger units
|
|
|
|
|
* - `this` has a nonzero value for `weeks` or larger units
|
|
|
|
|
*
|
|
|
|
|
* This value must be either a `Temporal.PlainDateTime`, a
|
|
|
|
|
* `Temporal.ZonedDateTime`, or a string or object value that can be passed
|
|
|
|
|
* to `from()` of those types. Examples:
|
|
|
|
|
* - `'2020-01'01T00:00-08:00[America/Los_Angeles]'`
|
|
|
|
|
* - `'2020-01'01'`
|
|
|
|
|
* - `Temporal.PlainDate.from('2020-01-01')`
|
|
|
|
|
*
|
|
|
|
|
* `Temporal.ZonedDateTime` will be tried first because it's more
|
|
|
|
|
* specific, with `Temporal.PlainDateTime` as a fallback.
|
|
|
|
|
*
|
|
|
|
|
* If the value resolves to a `Temporal.ZonedDateTime`, then operation will
|
|
|
|
|
* adjust for DST and other time zone transitions. Otherwise (including if
|
|
|
|
|
* this option is omitted), then the operation will ignore time zone
|
|
|
|
|
* transitions and all days will be assumed to be 24 hours long.
|
|
|
|
|
*/
|
|
|
|
|
relativeTo?:
|
|
|
|
|
| Temporal.ZonedDateTime
|
|
|
|
|
| Temporal.PlainDateTime
|
|
|
|
|
| ZonedDateTimeLike
|
|
|
|
|
| PlainDateTimeLike
|
|
|
|
|
| string;
|
|
|
|
|
};
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* Options to control behavior of `Duration.compare()`, `Duration.add()`, and
|
|
|
|
|
* `Duration.subtract()`
|
|
|
|
|
*/
|
|
|
|
|
export interface DurationArithmeticOptions {
|
|
|
|
|
/**
|
|
|
|
|
* The starting point to use when variable-length units (years, months,
|
|
|
|
|
* weeks depending on the calendar) are involved. This option is required if
|
|
|
|
|
* either of the durations has a nonzero value for `weeks` or larger units.
|
|
|
|
|
*
|
|
|
|
|
* This value must be either a `Temporal.PlainDateTime`, a
|
|
|
|
|
* `Temporal.ZonedDateTime`, or a string or object value that can be passed
|
|
|
|
|
* to `from()` of those types. Examples:
|
|
|
|
|
* - `'2020-01'01T00:00-08:00[America/Los_Angeles]'`
|
|
|
|
|
* - `'2020-01'01'`
|
|
|
|
|
* - `Temporal.PlainDate.from('2020-01-01')`
|
|
|
|
|
*
|
|
|
|
|
* `Temporal.ZonedDateTime` will be tried first because it's more
|
|
|
|
|
* specific, with `Temporal.PlainDateTime` as a fallback.
|
|
|
|
|
*
|
|
|
|
|
* If the value resolves to a `Temporal.ZonedDateTime`, then operation will
|
|
|
|
|
* adjust for DST and other time zone transitions. Otherwise (including if
|
|
|
|
|
* this option is omitted), then the operation will ignore time zone
|
|
|
|
|
* transitions and all days will be assumed to be 24 hours long.
|
|
|
|
|
*/
|
|
|
|
|
relativeTo?:
|
|
|
|
|
| Temporal.ZonedDateTime
|
|
|
|
|
| Temporal.PlainDateTime
|
|
|
|
|
| ZonedDateTimeLike
|
|
|
|
|
| PlainDateTimeLike
|
|
|
|
|
| string;
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
export type DurationLike = {
|
|
|
|
|
years?: number;
|
|
|
|
|
months?: number;
|
|
|
|
|
weeks?: number;
|
|
|
|
|
days?: number;
|
|
|
|
|
hours?: number;
|
|
|
|
|
minutes?: number;
|
|
|
|
|
seconds?: number;
|
|
|
|
|
milliseconds?: number;
|
|
|
|
|
microseconds?: number;
|
|
|
|
|
nanoseconds?: number;
|
|
|
|
|
};
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* A `Temporal.Duration` represents an immutable duration of time which can be
|
|
|
|
|
* used in date/time arithmetic.
|
|
|
|
|
*
|
|
|
|
|
* See https://tc39.es/proposal-temporal/docs/duration.html for more details.
|
|
|
|
|
*/
|
|
|
|
|
export class Duration {
|
|
|
|
|
static from(
|
|
|
|
|
item: Temporal.Duration | DurationLike | string,
|
|
|
|
|
): Temporal.Duration;
|
|
|
|
|
static compare(
|
|
|
|
|
one: Temporal.Duration | DurationLike | string,
|
|
|
|
|
two: Temporal.Duration | DurationLike | string,
|
|
|
|
|
options?: DurationArithmeticOptions,
|
|
|
|
|
): ComparisonResult;
|
|
|
|
|
constructor(
|
|
|
|
|
years?: number,
|
|
|
|
|
months?: number,
|
|
|
|
|
weeks?: number,
|
|
|
|
|
days?: number,
|
|
|
|
|
hours?: number,
|
|
|
|
|
minutes?: number,
|
|
|
|
|
seconds?: number,
|
|
|
|
|
milliseconds?: number,
|
|
|
|
|
microseconds?: number,
|
|
|
|
|
nanoseconds?: number,
|
|
|
|
|
);
|
|
|
|
|
readonly sign: -1 | 0 | 1;
|
|
|
|
|
readonly blank: boolean;
|
|
|
|
|
readonly years: number;
|
|
|
|
|
readonly months: number;
|
|
|
|
|
readonly weeks: number;
|
|
|
|
|
readonly days: number;
|
|
|
|
|
readonly hours: number;
|
|
|
|
|
readonly minutes: number;
|
|
|
|
|
readonly seconds: number;
|
|
|
|
|
readonly milliseconds: number;
|
|
|
|
|
readonly microseconds: number;
|
|
|
|
|
readonly nanoseconds: number;
|
|
|
|
|
negated(): Temporal.Duration;
|
|
|
|
|
abs(): Temporal.Duration;
|
|
|
|
|
with(durationLike: DurationLike): Temporal.Duration;
|
|
|
|
|
add(
|
|
|
|
|
other: Temporal.Duration | DurationLike | string,
|
|
|
|
|
options?: DurationArithmeticOptions,
|
|
|
|
|
): Temporal.Duration;
|
|
|
|
|
subtract(
|
|
|
|
|
other: Temporal.Duration | DurationLike | string,
|
|
|
|
|
options?: DurationArithmeticOptions,
|
|
|
|
|
): Temporal.Duration;
|
|
|
|
|
round(roundTo: DurationRoundTo): Temporal.Duration;
|
|
|
|
|
total(totalOf: DurationTotalOf): number;
|
|
|
|
|
toLocaleString(
|
|
|
|
|
locales?: string | string[],
|
|
|
|
|
options?: Intl.DateTimeFormatOptions,
|
|
|
|
|
): string;
|
|
|
|
|
toJSON(): string;
|
|
|
|
|
toString(options?: ToStringPrecisionOptions): string;
|
|
|
|
|
valueOf(): never;
|
|
|
|
|
readonly [Symbol.toStringTag]: "Temporal.Duration";
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* A `Temporal.Instant` is an exact point in time, with a precision in
|
|
|
|
|
* nanoseconds. No time zone or calendar information is present. Therefore,
|
|
|
|
|
* `Temporal.Instant` has no concept of days, months, or even hours.
|
|
|
|
|
*
|
|
|
|
|
* For convenience of interoperability, it internally uses nanoseconds since
|
|
|
|
|
* the {@link https://en.wikipedia.org/wiki/Unix_time|Unix epoch} (midnight
|
|
|
|
|
* UTC on January 1, 1970). However, a `Temporal.Instant` can be created from
|
|
|
|
|
* any of several expressions that refer to a single point in time, including
|
|
|
|
|
* an {@link https://en.wikipedia.org/wiki/ISO_8601|ISO 8601 string} with a
|
|
|
|
|
* time zone offset such as '2020-01-23T17:04:36.491865121-08:00'.
|
|
|
|
|
*
|
|
|
|
|
* See https://tc39.es/proposal-temporal/docs/instant.html for more details.
|
|
|
|
|
*/
|
|
|
|
|
export class Instant {
|
|
|
|
|
static fromEpochSeconds(epochSeconds: number): Temporal.Instant;
|
|
|
|
|
static fromEpochMilliseconds(epochMilliseconds: number): Temporal.Instant;
|
|
|
|
|
static fromEpochMicroseconds(epochMicroseconds: bigint): Temporal.Instant;
|
|
|
|
|
static fromEpochNanoseconds(epochNanoseconds: bigint): Temporal.Instant;
|
|
|
|
|
static from(item: Temporal.Instant | string): Temporal.Instant;
|
|
|
|
|
static compare(
|
|
|
|
|
one: Temporal.Instant | string,
|
|
|
|
|
two: Temporal.Instant | string,
|
|
|
|
|
): ComparisonResult;
|
|
|
|
|
constructor(epochNanoseconds: bigint);
|
|
|
|
|
readonly epochSeconds: number;
|
|
|
|
|
readonly epochMilliseconds: number;
|
|
|
|
|
readonly epochMicroseconds: bigint;
|
|
|
|
|
readonly epochNanoseconds: bigint;
|
|
|
|
|
equals(other: Temporal.Instant | string): boolean;
|
|
|
|
|
add(
|
|
|
|
|
durationLike:
|
|
|
|
|
| Omit<
|
|
|
|
|
Temporal.Duration | DurationLike,
|
|
|
|
|
"years" | "months" | "weeks" | "days"
|
|
|
|
|
>
|
|
|
|
|
| string,
|
|
|
|
|
): Temporal.Instant;
|
|
|
|
|
subtract(
|
|
|
|
|
durationLike:
|
|
|
|
|
| Omit<
|
|
|
|
|
Temporal.Duration | DurationLike,
|
|
|
|
|
"years" | "months" | "weeks" | "days"
|
|
|
|
|
>
|
|
|
|
|
| string,
|
|
|
|
|
): Temporal.Instant;
|
|
|
|
|
until(
|
|
|
|
|
other: Temporal.Instant | string,
|
|
|
|
|
options?: DifferenceOptions<
|
|
|
|
|
| "hour"
|
|
|
|
|
| "minute"
|
|
|
|
|
| "second"
|
|
|
|
|
| "millisecond"
|
|
|
|
|
| "microsecond"
|
|
|
|
|
| "nanosecond"
|
|
|
|
|
>,
|
|
|
|
|
): Temporal.Duration;
|
|
|
|
|
since(
|
|
|
|
|
other: Temporal.Instant | string,
|
|
|
|
|
options?: DifferenceOptions<
|
|
|
|
|
| "hour"
|
|
|
|
|
| "minute"
|
|
|
|
|
| "second"
|
|
|
|
|
| "millisecond"
|
|
|
|
|
| "microsecond"
|
|
|
|
|
| "nanosecond"
|
|
|
|
|
>,
|
|
|
|
|
): Temporal.Duration;
|
|
|
|
|
round(
|
|
|
|
|
roundTo: RoundTo<
|
|
|
|
|
| "hour"
|
|
|
|
|
| "minute"
|
|
|
|
|
| "second"
|
|
|
|
|
| "millisecond"
|
|
|
|
|
| "microsecond"
|
|
|
|
|
| "nanosecond"
|
|
|
|
|
>,
|
|
|
|
|
): Temporal.Instant;
|
|
|
|
|
toZonedDateTime(
|
|
|
|
|
calendarAndTimeZone: { timeZone: TimeZoneLike; calendar: CalendarLike },
|
|
|
|
|
): Temporal.ZonedDateTime;
|
|
|
|
|
toZonedDateTimeISO(tzLike: TimeZoneLike): Temporal.ZonedDateTime;
|
|
|
|
|
toLocaleString(
|
|
|
|
|
locales?: string | string[],
|
|
|
|
|
options?: Intl.DateTimeFormatOptions,
|
|
|
|
|
): string;
|
|
|
|
|
toJSON(): string;
|
|
|
|
|
toString(options?: InstantToStringOptions): string;
|
|
|
|
|
valueOf(): never;
|
|
|
|
|
readonly [Symbol.toStringTag]: "Temporal.Instant";
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
type YearOrEraAndEraYear = { era: string; eraYear: number } | {
|
|
|
|
|
year: number;
|
|
|
|
|
};
|
|
|
|
|
type MonthCodeOrMonthAndYear = (YearOrEraAndEraYear & { month: number }) | {
|
|
|
|
|
monthCode: string;
|
|
|
|
|
};
|
|
|
|
|
type MonthOrMonthCode = { month: number } | { monthCode: string };
|
|
|
|
|
|
|
|
|
|
export interface CalendarProtocol {
|
|
|
|
|
id: string;
|
|
|
|
|
year(
|
|
|
|
|
date:
|
|
|
|
|
| Temporal.PlainDate
|
|
|
|
|
| Temporal.PlainDateTime
|
|
|
|
|
| Temporal.PlainYearMonth
|
|
|
|
|
| PlainDateLike
|
|
|
|
|
| string,
|
|
|
|
|
): number;
|
|
|
|
|
month(
|
|
|
|
|
date:
|
|
|
|
|
| Temporal.PlainDate
|
|
|
|
|
| Temporal.PlainDateTime
|
|
|
|
|
| Temporal.PlainYearMonth
|
|
|
|
|
| Temporal.PlainMonthDay
|
|
|
|
|
| PlainDateLike
|
|
|
|
|
| string,
|
|
|
|
|
): number;
|
|
|
|
|
monthCode(
|
|
|
|
|
date:
|
|
|
|
|
| Temporal.PlainDate
|
|
|
|
|
| Temporal.PlainDateTime
|
|
|
|
|
| Temporal.PlainYearMonth
|
|
|
|
|
| Temporal.PlainMonthDay
|
|
|
|
|
| PlainDateLike
|
|
|
|
|
| string,
|
|
|
|
|
): string;
|
|
|
|
|
day(
|
|
|
|
|
date:
|
|
|
|
|
| Temporal.PlainDate
|
|
|
|
|
| Temporal.PlainDateTime
|
|
|
|
|
| Temporal.PlainMonthDay
|
|
|
|
|
| PlainDateLike
|
|
|
|
|
| string,
|
|
|
|
|
): number;
|
|
|
|
|
era(
|
|
|
|
|
date:
|
|
|
|
|
| Temporal.PlainDate
|
|
|
|
|
| Temporal.PlainDateTime
|
|
|
|
|
| PlainDateLike
|
|
|
|
|
| string,
|
|
|
|
|
): string | undefined;
|
|
|
|
|
eraYear(
|
|
|
|
|
date:
|
|
|
|
|
| Temporal.PlainDate
|
|
|
|
|
| Temporal.PlainDateTime
|
|
|
|
|
| PlainDateLike
|
|
|
|
|
| string,
|
|
|
|
|
): number | undefined;
|
|
|
|
|
dayOfWeek(
|
|
|
|
|
date:
|
|
|
|
|
| Temporal.PlainDate
|
|
|
|
|
| Temporal.PlainDateTime
|
|
|
|
|
| PlainDateLike
|
|
|
|
|
| string,
|
|
|
|
|
): number;
|
|
|
|
|
dayOfYear(
|
|
|
|
|
date:
|
|
|
|
|
| Temporal.PlainDate
|
|
|
|
|
| Temporal.PlainDateTime
|
|
|
|
|
| PlainDateLike
|
|
|
|
|
| string,
|
|
|
|
|
): number;
|
|
|
|
|
weekOfYear(
|
|
|
|
|
date:
|
|
|
|
|
| Temporal.PlainDate
|
|
|
|
|
| Temporal.PlainDateTime
|
|
|
|
|
| PlainDateLike
|
|
|
|
|
| string,
|
|
|
|
|
): number;
|
|
|
|
|
yearOfWeek(
|
|
|
|
|
date:
|
|
|
|
|
| Temporal.PlainDate
|
|
|
|
|
| Temporal.PlainDateTime
|
|
|
|
|
| PlainDateLike
|
|
|
|
|
| string,
|
|
|
|
|
): number;
|
|
|
|
|
daysInWeek(
|
|
|
|
|
date:
|
|
|
|
|
| Temporal.PlainDate
|
|
|
|
|
| Temporal.PlainDateTime
|
|
|
|
|
| PlainDateLike
|
|
|
|
|
| string,
|
|
|
|
|
): number;
|
|
|
|
|
daysInMonth(
|
|
|
|
|
date:
|
|
|
|
|
| Temporal.PlainDate
|
|
|
|
|
| Temporal.PlainDateTime
|
|
|
|
|
| Temporal.PlainYearMonth
|
|
|
|
|
| PlainDateLike
|
|
|
|
|
| string,
|
|
|
|
|
): number;
|
|
|
|
|
daysInYear(
|
|
|
|
|
date:
|
|
|
|
|
| Temporal.PlainDate
|
|
|
|
|
| Temporal.PlainDateTime
|
|
|
|
|
| Temporal.PlainYearMonth
|
|
|
|
|
| PlainDateLike
|
|
|
|
|
| string,
|
|
|
|
|
): number;
|
|
|
|
|
monthsInYear(
|
|
|
|
|
date:
|
|
|
|
|
| Temporal.PlainDate
|
|
|
|
|
| Temporal.PlainDateTime
|
|
|
|
|
| Temporal.PlainYearMonth
|
|
|
|
|
| PlainDateLike
|
|
|
|
|
| string,
|
|
|
|
|
): number;
|
|
|
|
|
inLeapYear(
|
|
|
|
|
date:
|
|
|
|
|
| Temporal.PlainDate
|
|
|
|
|
| Temporal.PlainDateTime
|
|
|
|
|
| Temporal.PlainYearMonth
|
|
|
|
|
| PlainDateLike
|
|
|
|
|
| string,
|
|
|
|
|
): boolean;
|
|
|
|
|
dateFromFields(
|
|
|
|
|
fields: YearOrEraAndEraYear & MonthOrMonthCode & { day: number },
|
|
|
|
|
options?: AssignmentOptions,
|
|
|
|
|
): Temporal.PlainDate;
|
|
|
|
|
yearMonthFromFields(
|
|
|
|
|
fields: YearOrEraAndEraYear & MonthOrMonthCode,
|
|
|
|
|
options?: AssignmentOptions,
|
|
|
|
|
): Temporal.PlainYearMonth;
|
|
|
|
|
monthDayFromFields(
|
|
|
|
|
fields: MonthCodeOrMonthAndYear & { day: number },
|
|
|
|
|
options?: AssignmentOptions,
|
|
|
|
|
): Temporal.PlainMonthDay;
|
|
|
|
|
dateAdd(
|
|
|
|
|
date: Temporal.PlainDate | PlainDateLike | string,
|
|
|
|
|
duration: Temporal.Duration | DurationLike | string,
|
|
|
|
|
options?: ArithmeticOptions,
|
|
|
|
|
): Temporal.PlainDate;
|
|
|
|
|
dateUntil(
|
|
|
|
|
one: Temporal.PlainDate | PlainDateLike | string,
|
|
|
|
|
two: Temporal.PlainDate | PlainDateLike | string,
|
|
|
|
|
options?: DifferenceOptions<"year" | "month" | "week" | "day">,
|
|
|
|
|
): Temporal.Duration;
|
|
|
|
|
fields(fields: Iterable<string>): Iterable<string>;
|
|
|
|
|
mergeFields(
|
|
|
|
|
fields: Record<string, unknown>,
|
|
|
|
|
additionalFields: Record<string, unknown>,
|
|
|
|
|
): Record<string, unknown>;
|
|
|
|
|
toString?(): string;
|
|
|
|
|
toJSON?(): string;
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* Any of these types can be passed to Temporal methods instead of a Temporal.Calendar.
|
|
|
|
|
*/
|
|
|
|
|
export type CalendarLike =
|
|
|
|
|
| string
|
|
|
|
|
| CalendarProtocol
|
|
|
|
|
| ZonedDateTime
|
|
|
|
|
| PlainDateTime
|
|
|
|
|
| PlainDate
|
|
|
|
|
| PlainYearMonth
|
|
|
|
|
| PlainMonthDay;
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* A `Temporal.Calendar` is a representation of a calendar system. It includes
|
|
|
|
|
* information about how many days are in each year, how many months are in
|
|
|
|
|
* each year, how many days are in each month, and how to do arithmetic in
|
|
|
|
|
* that calendar system.
|
|
|
|
|
*
|
|
|
|
|
* See https://tc39.es/proposal-temporal/docs/calendar.html for more details.
|
|
|
|
|
*/
|
|
|
|
|
export class Calendar implements CalendarProtocol {
|
|
|
|
|
static from(item: CalendarLike): Temporal.Calendar | CalendarProtocol;
|
|
|
|
|
constructor(calendarIdentifier: string);
|
|
|
|
|
readonly id: string;
|
|
|
|
|
year(
|
|
|
|
|
date:
|
|
|
|
|
| Temporal.PlainDate
|
|
|
|
|
| Temporal.PlainDateTime
|
|
|
|
|
| Temporal.PlainYearMonth
|
|
|
|
|
| PlainDateLike
|
|
|
|
|
| string,
|
|
|
|
|
): number;
|
|
|
|
|
month(
|
|
|
|
|
date:
|
|
|
|
|
| Temporal.PlainDate
|
|
|
|
|
| Temporal.PlainDateTime
|
|
|
|
|
| Temporal.PlainYearMonth
|
|
|
|
|
| Temporal.PlainMonthDay
|
|
|
|
|
| PlainDateLike
|
|
|
|
|
| string,
|
|
|
|
|
): number;
|
|
|
|
|
monthCode(
|
|
|
|
|
date:
|
|
|
|
|
| Temporal.PlainDate
|
|
|
|
|
| Temporal.PlainDateTime
|
|
|
|
|
| Temporal.PlainYearMonth
|
|
|
|
|
| Temporal.PlainMonthDay
|
|
|
|
|
| PlainDateLike
|
|
|
|
|
| string,
|
|
|
|
|
): string;
|
|
|
|
|
day(
|
|
|
|
|
date:
|
|
|
|
|
| Temporal.PlainDate
|
|
|
|
|
| Temporal.PlainDateTime
|
|
|
|
|
| Temporal.PlainMonthDay
|
|
|
|
|
| PlainDateLike
|
|
|
|
|
| string,
|
|
|
|
|
): number;
|
|
|
|
|
era(
|
|
|
|
|
date:
|
|
|
|
|
| Temporal.PlainDate
|
|
|
|
|
| Temporal.PlainDateTime
|
|
|
|
|
| PlainDateLike
|
|
|
|
|
| string,
|
|
|
|
|
): string | undefined;
|
|
|
|
|
eraYear(
|
|
|
|
|
date:
|
|
|
|
|
| Temporal.PlainDate
|
|
|
|
|
| Temporal.PlainDateTime
|
|
|
|
|
| PlainDateLike
|
|
|
|
|
| string,
|
|
|
|
|
): number | undefined;
|
|
|
|
|
dayOfWeek(
|
|
|
|
|
date:
|
|
|
|
|
| Temporal.PlainDate
|
|
|
|
|
| Temporal.PlainDateTime
|
|
|
|
|
| PlainDateLike
|
|
|
|
|
| string,
|
|
|
|
|
): number;
|
|
|
|
|
dayOfYear(
|
|
|
|
|
date:
|
|
|
|
|
| Temporal.PlainDate
|
|
|
|
|
| Temporal.PlainDateTime
|
|
|
|
|
| PlainDateLike
|
|
|
|
|
| string,
|
|
|
|
|
): number;
|
|
|
|
|
weekOfYear(
|
|
|
|
|
date:
|
|
|
|
|
| Temporal.PlainDate
|
|
|
|
|
| Temporal.PlainDateTime
|
|
|
|
|
| PlainDateLike
|
|
|
|
|
| string,
|
|
|
|
|
): number;
|
|
|
|
|
yearOfWeek(
|
|
|
|
|
date:
|
|
|
|
|
| Temporal.PlainDate
|
|
|
|
|
| Temporal.PlainDateTime
|
|
|
|
|
| PlainDateLike
|
|
|
|
|
| string,
|
|
|
|
|
): number;
|
|
|
|
|
daysInWeek(
|
|
|
|
|
date:
|
|
|
|
|
| Temporal.PlainDate
|
|
|
|
|
| Temporal.PlainDateTime
|
|
|
|
|
| PlainDateLike
|
|
|
|
|
| string,
|
|
|
|
|
): number;
|
|
|
|
|
daysInMonth(
|
|
|
|
|
date:
|
|
|
|
|
| Temporal.PlainDate
|
|
|
|
|
| Temporal.PlainDateTime
|
|
|
|
|
| Temporal.PlainYearMonth
|
|
|
|
|
| PlainDateLike
|
|
|
|
|
| string,
|
|
|
|
|
): number;
|
|
|
|
|
daysInYear(
|
|
|
|
|
date:
|
|
|
|
|
| Temporal.PlainDate
|
|
|
|
|
| Temporal.PlainDateTime
|
|
|
|
|
| Temporal.PlainYearMonth
|
|
|
|
|
| PlainDateLike
|
|
|
|
|
| string,
|
|
|
|
|
): number;
|
|
|
|
|
monthsInYear(
|
|
|
|
|
date:
|
|
|
|
|
| Temporal.PlainDate
|
|
|
|
|
| Temporal.PlainDateTime
|
|
|
|
|
| Temporal.PlainYearMonth
|
|
|
|
|
| PlainDateLike
|
|
|
|
|
| string,
|
|
|
|
|
): number;
|
|
|
|
|
inLeapYear(
|
|
|
|
|
date:
|
|
|
|
|
| Temporal.PlainDate
|
|
|
|
|
| Temporal.PlainDateTime
|
|
|
|
|
| Temporal.PlainYearMonth
|
|
|
|
|
| PlainDateLike
|
|
|
|
|
| string,
|
|
|
|
|
): boolean;
|
|
|
|
|
dateFromFields(
|
|
|
|
|
fields: YearOrEraAndEraYear & MonthOrMonthCode & { day: number },
|
|
|
|
|
options?: AssignmentOptions,
|
|
|
|
|
): Temporal.PlainDate;
|
|
|
|
|
yearMonthFromFields(
|
|
|
|
|
fields: YearOrEraAndEraYear & MonthOrMonthCode,
|
|
|
|
|
options?: AssignmentOptions,
|
|
|
|
|
): Temporal.PlainYearMonth;
|
|
|
|
|
monthDayFromFields(
|
|
|
|
|
fields: MonthCodeOrMonthAndYear & { day: number },
|
|
|
|
|
options?: AssignmentOptions,
|
|
|
|
|
): Temporal.PlainMonthDay;
|
|
|
|
|
dateAdd(
|
|
|
|
|
date: Temporal.PlainDate | PlainDateLike | string,
|
|
|
|
|
duration: Temporal.Duration | DurationLike | string,
|
|
|
|
|
options?: ArithmeticOptions,
|
|
|
|
|
): Temporal.PlainDate;
|
|
|
|
|
dateUntil(
|
|
|
|
|
one: Temporal.PlainDate | PlainDateLike | string,
|
|
|
|
|
two: Temporal.PlainDate | PlainDateLike | string,
|
|
|
|
|
options?: DifferenceOptions<"year" | "month" | "week" | "day">,
|
|
|
|
|
): Temporal.Duration;
|
|
|
|
|
fields(fields: Iterable<string>): string[];
|
|
|
|
|
mergeFields(
|
|
|
|
|
fields: Record<string, unknown>,
|
|
|
|
|
additionalFields: Record<string, unknown>,
|
|
|
|
|
): Record<string, unknown>;
|
|
|
|
|
toString(): string;
|
|
|
|
|
toJSON(): string;
|
|
|
|
|
readonly [Symbol.toStringTag]: "Temporal.Calendar";
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
export type PlainDateLike = {
|
|
|
|
|
era?: string | undefined;
|
|
|
|
|
eraYear?: number | undefined;
|
|
|
|
|
year?: number;
|
|
|
|
|
month?: number;
|
|
|
|
|
monthCode?: string;
|
|
|
|
|
day?: number;
|
|
|
|
|
calendar?: CalendarLike;
|
|
|
|
|
};
|
|
|
|
|
|
|
|
|
|
type PlainDateISOFields = {
|
|
|
|
|
isoYear: number;
|
|
|
|
|
isoMonth: number;
|
|
|
|
|
isoDay: number;
|
|
|
|
|
calendar: string | CalendarProtocol;
|
|
|
|
|
};
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* A `Temporal.PlainDate` represents a calendar date. "Calendar date" refers to the
|
|
|
|
|
* concept of a date as expressed in everyday usage, independent of any time
|
|
|
|
|
* zone. For example, it could be used to represent an event on a calendar
|
|
|
|
|
* which happens during the whole day no matter which time zone it's happening
|
|
|
|
|
* in.
|
|
|
|
|
*
|
|
|
|
|
* See https://tc39.es/proposal-temporal/docs/date.html for more details.
|
|
|
|
|
*/
|
|
|
|
|
export class PlainDate {
|
|
|
|
|
static from(
|
|
|
|
|
item: Temporal.PlainDate | PlainDateLike | string,
|
|
|
|
|
options?: AssignmentOptions,
|
|
|
|
|
): Temporal.PlainDate;
|
|
|
|
|
static compare(
|
|
|
|
|
one: Temporal.PlainDate | PlainDateLike | string,
|
|
|
|
|
two: Temporal.PlainDate | PlainDateLike | string,
|
|
|
|
|
): ComparisonResult;
|
|
|
|
|
constructor(
|
|
|
|
|
isoYear: number,
|
|
|
|
|
isoMonth: number,
|
|
|
|
|
isoDay: number,
|
|
|
|
|
calendar?: CalendarLike,
|
|
|
|
|
);
|
|
|
|
|
readonly era: string | undefined;
|
|
|
|
|
readonly eraYear: number | undefined;
|
|
|
|
|
readonly year: number;
|
|
|
|
|
readonly month: number;
|
|
|
|
|
readonly monthCode: string;
|
|
|
|
|
readonly day: number;
|
|
|
|
|
readonly calendarId: string;
|
|
|
|
|
getCalendar(): CalendarProtocol;
|
|
|
|
|
readonly dayOfWeek: number;
|
|
|
|
|
readonly dayOfYear: number;
|
|
|
|
|
readonly weekOfYear: number;
|
|
|
|
|
readonly yearOfWeek: number;
|
|
|
|
|
readonly daysInWeek: number;
|
|
|
|
|
readonly daysInYear: number;
|
|
|
|
|
readonly daysInMonth: number;
|
|
|
|
|
readonly monthsInYear: number;
|
|
|
|
|
readonly inLeapYear: boolean;
|
|
|
|
|
equals(other: Temporal.PlainDate | PlainDateLike | string): boolean;
|
|
|
|
|
with(
|
|
|
|
|
dateLike: PlainDateLike,
|
|
|
|
|
options?: AssignmentOptions,
|
|
|
|
|
): Temporal.PlainDate;
|
|
|
|
|
withCalendar(calendar: CalendarLike): Temporal.PlainDate;
|
|
|
|
|
add(
|
|
|
|
|
durationLike: Temporal.Duration | DurationLike | string,
|
|
|
|
|
options?: ArithmeticOptions,
|
|
|
|
|
): Temporal.PlainDate;
|
|
|
|
|
subtract(
|
|
|
|
|
durationLike: Temporal.Duration | DurationLike | string,
|
|
|
|
|
options?: ArithmeticOptions,
|
|
|
|
|
): Temporal.PlainDate;
|
|
|
|
|
until(
|
|
|
|
|
other: Temporal.PlainDate | PlainDateLike | string,
|
|
|
|
|
options?: DifferenceOptions<"year" | "month" | "week" | "day">,
|
|
|
|
|
): Temporal.Duration;
|
|
|
|
|
since(
|
|
|
|
|
other: Temporal.PlainDate | PlainDateLike | string,
|
|
|
|
|
options?: DifferenceOptions<"year" | "month" | "week" | "day">,
|
|
|
|
|
): Temporal.Duration;
|
|
|
|
|
toPlainDateTime(
|
|
|
|
|
temporalTime?: Temporal.PlainTime | PlainTimeLike | string,
|
|
|
|
|
): Temporal.PlainDateTime;
|
|
|
|
|
toZonedDateTime(
|
|
|
|
|
timeZoneAndTime:
|
|
|
|
|
| TimeZoneProtocol
|
|
|
|
|
| string
|
|
|
|
|
| {
|
|
|
|
|
timeZone: TimeZoneLike;
|
|
|
|
|
plainTime?: Temporal.PlainTime | PlainTimeLike | string;
|
|
|
|
|
},
|
|
|
|
|
): Temporal.ZonedDateTime;
|
|
|
|
|
toPlainYearMonth(): Temporal.PlainYearMonth;
|
|
|
|
|
toPlainMonthDay(): Temporal.PlainMonthDay;
|
|
|
|
|
getISOFields(): PlainDateISOFields;
|
|
|
|
|
toLocaleString(
|
|
|
|
|
locales?: string | string[],
|
|
|
|
|
options?: Intl.DateTimeFormatOptions,
|
|
|
|
|
): string;
|
|
|
|
|
toJSON(): string;
|
|
|
|
|
toString(options?: ShowCalendarOption): string;
|
|
|
|
|
valueOf(): never;
|
|
|
|
|
readonly [Symbol.toStringTag]: "Temporal.PlainDate";
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
export type PlainDateTimeLike = {
|
|
|
|
|
era?: string | undefined;
|
|
|
|
|
eraYear?: number | undefined;
|
|
|
|
|
year?: number;
|
|
|
|
|
month?: number;
|
|
|
|
|
monthCode?: string;
|
|
|
|
|
day?: number;
|
|
|
|
|
hour?: number;
|
|
|
|
|
minute?: number;
|
|
|
|
|
second?: number;
|
|
|
|
|
millisecond?: number;
|
|
|
|
|
microsecond?: number;
|
|
|
|
|
nanosecond?: number;
|
|
|
|
|
calendar?: CalendarLike;
|
|
|
|
|
};
|
|
|
|
|
|
|
|
|
|
type PlainDateTimeISOFields = {
|
|
|
|
|
isoYear: number;
|
|
|
|
|
isoMonth: number;
|
|
|
|
|
isoDay: number;
|
|
|
|
|
isoHour: number;
|
|
|
|
|
isoMinute: number;
|
|
|
|
|
isoSecond: number;
|
|
|
|
|
isoMillisecond: number;
|
|
|
|
|
isoMicrosecond: number;
|
|
|
|
|
isoNanosecond: number;
|
|
|
|
|
calendar: string | CalendarProtocol;
|
|
|
|
|
};
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* A `Temporal.PlainDateTime` represents a calendar date and wall-clock time, with
|
|
|
|
|
* a precision in nanoseconds, and without any time zone. Of the Temporal
|
|
|
|
|
* classes carrying human-readable time information, it is the most general
|
|
|
|
|
* and complete one. `Temporal.PlainDate`, `Temporal.PlainTime`, `Temporal.PlainYearMonth`,
|
|
|
|
|
* and `Temporal.PlainMonthDay` all carry less information and should be used when
|
|
|
|
|
* complete information is not required.
|
|
|
|
|
*
|
|
|
|
|
* See https://tc39.es/proposal-temporal/docs/datetime.html for more details.
|
|
|
|
|
*/
|
|
|
|
|
export class PlainDateTime {
|
|
|
|
|
static from(
|
|
|
|
|
item: Temporal.PlainDateTime | PlainDateTimeLike | string,
|
|
|
|
|
options?: AssignmentOptions,
|
|
|
|
|
): Temporal.PlainDateTime;
|
|
|
|
|
static compare(
|
|
|
|
|
one: Temporal.PlainDateTime | PlainDateTimeLike | string,
|
|
|
|
|
two: Temporal.PlainDateTime | PlainDateTimeLike | string,
|
|
|
|
|
): ComparisonResult;
|
|
|
|
|
constructor(
|
|
|
|
|
isoYear: number,
|
|
|
|
|
isoMonth: number,
|
|
|
|
|
isoDay: number,
|
|
|
|
|
hour?: number,
|
|
|
|
|
minute?: number,
|
|
|
|
|
second?: number,
|
|
|
|
|
millisecond?: number,
|
|
|
|
|
microsecond?: number,
|
|
|
|
|
nanosecond?: number,
|
|
|
|
|
calendar?: CalendarLike,
|
|
|
|
|
);
|
|
|
|
|
readonly era: string | undefined;
|
|
|
|
|
readonly eraYear: number | undefined;
|
|
|
|
|
readonly year: number;
|
|
|
|
|
readonly month: number;
|
|
|
|
|
readonly monthCode: string;
|
|
|
|
|
readonly day: number;
|
|
|
|
|
readonly hour: number;
|
|
|
|
|
readonly minute: number;
|
|
|
|
|
readonly second: number;
|
|
|
|
|
readonly millisecond: number;
|
|
|
|
|
readonly microsecond: number;
|
|
|
|
|
readonly nanosecond: number;
|
|
|
|
|
readonly calendarId: string;
|
|
|
|
|
getCalendar(): CalendarProtocol;
|
|
|
|
|
readonly dayOfWeek: number;
|
|
|
|
|
readonly dayOfYear: number;
|
|
|
|
|
readonly weekOfYear: number;
|
|
|
|
|
readonly yearOfWeek: number;
|
|
|
|
|
readonly daysInWeek: number;
|
|
|
|
|
readonly daysInYear: number;
|
|
|
|
|
readonly daysInMonth: number;
|
|
|
|
|
readonly monthsInYear: number;
|
|
|
|
|
readonly inLeapYear: boolean;
|
|
|
|
|
equals(other: Temporal.PlainDateTime | PlainDateTimeLike | string): boolean;
|
|
|
|
|
with(
|
|
|
|
|
dateTimeLike: PlainDateTimeLike,
|
|
|
|
|
options?: AssignmentOptions,
|
|
|
|
|
): Temporal.PlainDateTime;
|
|
|
|
|
withPlainTime(
|
|
|
|
|
timeLike?: Temporal.PlainTime | PlainTimeLike | string,
|
|
|
|
|
): Temporal.PlainDateTime;
|
|
|
|
|
withPlainDate(
|
|
|
|
|
dateLike: Temporal.PlainDate | PlainDateLike | string,
|
|
|
|
|
): Temporal.PlainDateTime;
|
|
|
|
|
withCalendar(calendar: CalendarLike): Temporal.PlainDateTime;
|
|
|
|
|
add(
|
|
|
|
|
durationLike: Temporal.Duration | DurationLike | string,
|
|
|
|
|
options?: ArithmeticOptions,
|
|
|
|
|
): Temporal.PlainDateTime;
|
|
|
|
|
subtract(
|
|
|
|
|
durationLike: Temporal.Duration | DurationLike | string,
|
|
|
|
|
options?: ArithmeticOptions,
|
|
|
|
|
): Temporal.PlainDateTime;
|
|
|
|
|
until(
|
|
|
|
|
other: Temporal.PlainDateTime | PlainDateTimeLike | string,
|
|
|
|
|
options?: DifferenceOptions<
|
|
|
|
|
| "year"
|
|
|
|
|
| "month"
|
|
|
|
|
| "week"
|
|
|
|
|
| "day"
|
|
|
|
|
| "hour"
|
|
|
|
|
| "minute"
|
|
|
|
|
| "second"
|
|
|
|
|
| "millisecond"
|
|
|
|
|
| "microsecond"
|
|
|
|
|
| "nanosecond"
|
|
|
|
|
>,
|
|
|
|
|
): Temporal.Duration;
|
|
|
|
|
since(
|
|
|
|
|
other: Temporal.PlainDateTime | PlainDateTimeLike | string,
|
|
|
|
|
options?: DifferenceOptions<
|
|
|
|
|
| "year"
|
|
|
|
|
| "month"
|
|
|
|
|
| "week"
|
|
|
|
|
| "day"
|
|
|
|
|
| "hour"
|
|
|
|
|
| "minute"
|
|
|
|
|
| "second"
|
|
|
|
|
| "millisecond"
|
|
|
|
|
| "microsecond"
|
|
|
|
|
| "nanosecond"
|
|
|
|
|
>,
|
|
|
|
|
): Temporal.Duration;
|
|
|
|
|
round(
|
|
|
|
|
roundTo: RoundTo<
|
|
|
|
|
| "day"
|
|
|
|
|
| "hour"
|
|
|
|
|
| "minute"
|
|
|
|
|
| "second"
|
|
|
|
|
| "millisecond"
|
|
|
|
|
| "microsecond"
|
|
|
|
|
| "nanosecond"
|
|
|
|
|
>,
|
|
|
|
|
): Temporal.PlainDateTime;
|
|
|
|
|
toZonedDateTime(
|
|
|
|
|
tzLike: TimeZoneLike,
|
|
|
|
|
options?: ToInstantOptions,
|
|
|
|
|
): Temporal.ZonedDateTime;
|
|
|
|
|
toPlainDate(): Temporal.PlainDate;
|
|
|
|
|
toPlainYearMonth(): Temporal.PlainYearMonth;
|
|
|
|
|
toPlainMonthDay(): Temporal.PlainMonthDay;
|
|
|
|
|
toPlainTime(): Temporal.PlainTime;
|
|
|
|
|
getISOFields(): PlainDateTimeISOFields;
|
|
|
|
|
toLocaleString(
|
|
|
|
|
locales?: string | string[],
|
|
|
|
|
options?: Intl.DateTimeFormatOptions,
|
|
|
|
|
): string;
|
|
|
|
|
toJSON(): string;
|
|
|
|
|
toString(options?: CalendarTypeToStringOptions): string;
|
|
|
|
|
valueOf(): never;
|
|
|
|
|
readonly [Symbol.toStringTag]: "Temporal.PlainDateTime";
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
export type PlainMonthDayLike = {
|
|
|
|
|
era?: string | undefined;
|
|
|
|
|
eraYear?: number | undefined;
|
|
|
|
|
year?: number;
|
|
|
|
|
month?: number;
|
|
|
|
|
monthCode?: string;
|
|
|
|
|
day?: number;
|
|
|
|
|
calendar?: CalendarLike;
|
|
|
|
|
};
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* A `Temporal.PlainMonthDay` represents a particular day on the calendar, but
|
|
|
|
|
* without a year. For example, it could be used to represent a yearly
|
|
|
|
|
* recurring event, like "Bastille Day is on the 14th of July."
|
|
|
|
|
*
|
|
|
|
|
* See https://tc39.es/proposal-temporal/docs/monthday.html for more details.
|
|
|
|
|
*/
|
|
|
|
|
export class PlainMonthDay {
|
|
|
|
|
static from(
|
|
|
|
|
item: Temporal.PlainMonthDay | PlainMonthDayLike | string,
|
|
|
|
|
options?: AssignmentOptions,
|
|
|
|
|
): Temporal.PlainMonthDay;
|
|
|
|
|
constructor(
|
|
|
|
|
isoMonth: number,
|
|
|
|
|
isoDay: number,
|
|
|
|
|
calendar?: CalendarLike,
|
|
|
|
|
referenceISOYear?: number,
|
|
|
|
|
);
|
|
|
|
|
readonly monthCode: string;
|
|
|
|
|
readonly day: number;
|
|
|
|
|
readonly calendarId: string;
|
|
|
|
|
getCalendar(): CalendarProtocol;
|
|
|
|
|
equals(other: Temporal.PlainMonthDay | PlainMonthDayLike | string): boolean;
|
|
|
|
|
with(
|
|
|
|
|
monthDayLike: PlainMonthDayLike,
|
|
|
|
|
options?: AssignmentOptions,
|
|
|
|
|
): Temporal.PlainMonthDay;
|
|
|
|
|
toPlainDate(year: { year: number }): Temporal.PlainDate;
|
|
|
|
|
getISOFields(): PlainDateISOFields;
|
|
|
|
|
toLocaleString(
|
|
|
|
|
locales?: string | string[],
|
|
|
|
|
options?: Intl.DateTimeFormatOptions,
|
|
|
|
|
): string;
|
|
|
|
|
toJSON(): string;
|
|
|
|
|
toString(options?: ShowCalendarOption): string;
|
|
|
|
|
valueOf(): never;
|
|
|
|
|
readonly [Symbol.toStringTag]: "Temporal.PlainMonthDay";
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
export type PlainTimeLike = {
|
|
|
|
|
hour?: number;
|
|
|
|
|
minute?: number;
|
|
|
|
|
second?: number;
|
|
|
|
|
millisecond?: number;
|
|
|
|
|
microsecond?: number;
|
|
|
|
|
nanosecond?: number;
|
|
|
|
|
};
|
|
|
|
|
|
|
|
|
|
type PlainTimeISOFields = {
|
|
|
|
|
isoHour: number;
|
|
|
|
|
isoMinute: number;
|
|
|
|
|
isoSecond: number;
|
|
|
|
|
isoMillisecond: number;
|
|
|
|
|
isoMicrosecond: number;
|
|
|
|
|
isoNanosecond: number;
|
|
|
|
|
};
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* A `Temporal.PlainTime` represents a wall-clock time, with a precision in
|
|
|
|
|
* nanoseconds, and without any time zone. "Wall-clock time" refers to the
|
|
|
|
|
* concept of a time as expressed in everyday usage — the time that you read
|
|
|
|
|
* off the clock on the wall. For example, it could be used to represent an
|
|
|
|
|
* event that happens daily at a certain time, no matter what time zone.
|
|
|
|
|
*
|
|
|
|
|
* `Temporal.PlainTime` refers to a time with no associated calendar date; if you
|
|
|
|
|
* need to refer to a specific time on a specific day, use
|
|
|
|
|
* `Temporal.PlainDateTime`. A `Temporal.PlainTime` can be converted into a
|
|
|
|
|
* `Temporal.PlainDateTime` by combining it with a `Temporal.PlainDate` using the
|
|
|
|
|
* `toPlainDateTime()` method.
|
|
|
|
|
*
|
|
|
|
|
* See https://tc39.es/proposal-temporal/docs/time.html for more details.
|
|
|
|
|
*/
|
|
|
|
|
export class PlainTime {
|
|
|
|
|
static from(
|
|
|
|
|
item: Temporal.PlainTime | PlainTimeLike | string,
|
|
|
|
|
options?: AssignmentOptions,
|
|
|
|
|
): Temporal.PlainTime;
|
|
|
|
|
static compare(
|
|
|
|
|
one: Temporal.PlainTime | PlainTimeLike | string,
|
|
|
|
|
two: Temporal.PlainTime | PlainTimeLike | string,
|
|
|
|
|
): ComparisonResult;
|
|
|
|
|
constructor(
|
|
|
|
|
hour?: number,
|
|
|
|
|
minute?: number,
|
|
|
|
|
second?: number,
|
|
|
|
|
millisecond?: number,
|
|
|
|
|
microsecond?: number,
|
|
|
|
|
nanosecond?: number,
|
|
|
|
|
);
|
|
|
|
|
readonly hour: number;
|
|
|
|
|
readonly minute: number;
|
|
|
|
|
readonly second: number;
|
|
|
|
|
readonly millisecond: number;
|
|
|
|
|
readonly microsecond: number;
|
|
|
|
|
readonly nanosecond: number;
|
|
|
|
|
equals(other: Temporal.PlainTime | PlainTimeLike | string): boolean;
|
|
|
|
|
with(
|
|
|
|
|
timeLike: Temporal.PlainTime | PlainTimeLike,
|
|
|
|
|
options?: AssignmentOptions,
|
|
|
|
|
): Temporal.PlainTime;
|
|
|
|
|
add(
|
|
|
|
|
durationLike: Temporal.Duration | DurationLike | string,
|
|
|
|
|
options?: ArithmeticOptions,
|
|
|
|
|
): Temporal.PlainTime;
|
|
|
|
|
subtract(
|
|
|
|
|
durationLike: Temporal.Duration | DurationLike | string,
|
|
|
|
|
options?: ArithmeticOptions,
|
|
|
|
|
): Temporal.PlainTime;
|
|
|
|
|
until(
|
|
|
|
|
other: Temporal.PlainTime | PlainTimeLike | string,
|
|
|
|
|
options?: DifferenceOptions<
|
|
|
|
|
| "hour"
|
|
|
|
|
| "minute"
|
|
|
|
|
| "second"
|
|
|
|
|
| "millisecond"
|
|
|
|
|
| "microsecond"
|
|
|
|
|
| "nanosecond"
|
|
|
|
|
>,
|
|
|
|
|
): Temporal.Duration;
|
|
|
|
|
since(
|
|
|
|
|
other: Temporal.PlainTime | PlainTimeLike | string,
|
|
|
|
|
options?: DifferenceOptions<
|
|
|
|
|
| "hour"
|
|
|
|
|
| "minute"
|
|
|
|
|
| "second"
|
|
|
|
|
| "millisecond"
|
|
|
|
|
| "microsecond"
|
|
|
|
|
| "nanosecond"
|
|
|
|
|
>,
|
|
|
|
|
): Temporal.Duration;
|
|
|
|
|
round(
|
|
|
|
|
roundTo: RoundTo<
|
|
|
|
|
| "hour"
|
|
|
|
|
| "minute"
|
|
|
|
|
| "second"
|
|
|
|
|
| "millisecond"
|
|
|
|
|
| "microsecond"
|
|
|
|
|
| "nanosecond"
|
|
|
|
|
>,
|
|
|
|
|
): Temporal.PlainTime;
|
|
|
|
|
toPlainDateTime(
|
|
|
|
|
temporalDate: Temporal.PlainDate | PlainDateLike | string,
|
|
|
|
|
): Temporal.PlainDateTime;
|
|
|
|
|
toZonedDateTime(timeZoneAndDate: {
|
|
|
|
|
timeZone: TimeZoneLike;
|
|
|
|
|
plainDate: Temporal.PlainDate | PlainDateLike | string;
|
|
|
|
|
}): Temporal.ZonedDateTime;
|
|
|
|
|
getISOFields(): PlainTimeISOFields;
|
|
|
|
|
toLocaleString(
|
|
|
|
|
locales?: string | string[],
|
|
|
|
|
options?: Intl.DateTimeFormatOptions,
|
|
|
|
|
): string;
|
|
|
|
|
toJSON(): string;
|
|
|
|
|
toString(options?: ToStringPrecisionOptions): string;
|
|
|
|
|
valueOf(): never;
|
|
|
|
|
readonly [Symbol.toStringTag]: "Temporal.PlainTime";
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* A plain object implementing the protocol for a custom time zone.
|
|
|
|
|
*/
|
|
|
|
|
export interface TimeZoneProtocol {
|
|
|
|
|
id: string;
|
|
|
|
|
getOffsetNanosecondsFor(instant: Temporal.Instant | string): number;
|
|
|
|
|
getOffsetStringFor?(instant: Temporal.Instant | string): string;
|
|
|
|
|
getPlainDateTimeFor?(
|
|
|
|
|
instant: Temporal.Instant | string,
|
|
|
|
|
calendar?: CalendarLike,
|
|
|
|
|
): Temporal.PlainDateTime;
|
|
|
|
|
getInstantFor?(
|
|
|
|
|
dateTime: Temporal.PlainDateTime | PlainDateTimeLike | string,
|
|
|
|
|
options?: ToInstantOptions,
|
|
|
|
|
): Temporal.Instant;
|
|
|
|
|
getNextTransition?(
|
|
|
|
|
startingPoint: Temporal.Instant | string,
|
|
|
|
|
): Temporal.Instant | null;
|
|
|
|
|
getPreviousTransition?(
|
|
|
|
|
startingPoint: Temporal.Instant | string,
|
|
|
|
|
): Temporal.Instant | null;
|
|
|
|
|
getPossibleInstantsFor(
|
|
|
|
|
dateTime: Temporal.PlainDateTime | PlainDateTimeLike | string,
|
|
|
|
|
): Temporal.Instant[];
|
|
|
|
|
toString?(): string;
|
|
|
|
|
toJSON?(): string;
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* Any of these types can be passed to Temporal methods instead of a Temporal.TimeZone.
|
|
|
|
|
*/
|
|
|
|
|
export type TimeZoneLike = string | TimeZoneProtocol | ZonedDateTime;
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* A `Temporal.TimeZone` is a representation of a time zone: either an
|
|
|
|
|
* {@link https://www.iana.org/time-zones|IANA time zone}, including
|
|
|
|
|
* information about the time zone such as the offset between the local time
|
|
|
|
|
* and UTC at a particular time, and daylight saving time (DST) changes; or
|
|
|
|
|
* simply a particular UTC offset with no DST.
|
|
|
|
|
*
|
|
|
|
|
* `Temporal.ZonedDateTime` is the only Temporal type to contain a time zone.
|
|
|
|
|
* Other types, like `Temporal.Instant` and `Temporal.PlainDateTime`, do not
|
|
|
|
|
* contain any time zone information, and a `Temporal.TimeZone` object is
|
|
|
|
|
* required to convert between them.
|
|
|
|
|
*
|
|
|
|
|
* See https://tc39.es/proposal-temporal/docs/timezone.html for more details.
|
|
|
|
|
*/
|
|
|
|
|
export class TimeZone implements TimeZoneProtocol {
|
|
|
|
|
static from(timeZone: TimeZoneLike): Temporal.TimeZone | TimeZoneProtocol;
|
|
|
|
|
constructor(timeZoneIdentifier: string);
|
|
|
|
|
readonly id: string;
|
|
|
|
|
equals(timeZone: TimeZoneLike): boolean;
|
|
|
|
|
getOffsetNanosecondsFor(instant: Temporal.Instant | string): number;
|
|
|
|
|
getOffsetStringFor(instant: Temporal.Instant | string): string;
|
|
|
|
|
getPlainDateTimeFor(
|
|
|
|
|
instant: Temporal.Instant | string,
|
|
|
|
|
calendar?: CalendarLike,
|
|
|
|
|
): Temporal.PlainDateTime;
|
|
|
|
|
getInstantFor(
|
|
|
|
|
dateTime: Temporal.PlainDateTime | PlainDateTimeLike | string,
|
|
|
|
|
options?: ToInstantOptions,
|
|
|
|
|
): Temporal.Instant;
|
|
|
|
|
getNextTransition(
|
|
|
|
|
startingPoint: Temporal.Instant | string,
|
|
|
|
|
): Temporal.Instant | null;
|
|
|
|
|
getPreviousTransition(
|
|
|
|
|
startingPoint: Temporal.Instant | string,
|
|
|
|
|
): Temporal.Instant | null;
|
|
|
|
|
getPossibleInstantsFor(
|
|
|
|
|
dateTime: Temporal.PlainDateTime | PlainDateTimeLike | string,
|
|
|
|
|
): Temporal.Instant[];
|
|
|
|
|
toString(): string;
|
|
|
|
|
toJSON(): string;
|
|
|
|
|
readonly [Symbol.toStringTag]: "Temporal.TimeZone";
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
export type PlainYearMonthLike = {
|
|
|
|
|
era?: string | undefined;
|
|
|
|
|
eraYear?: number | undefined;
|
|
|
|
|
year?: number;
|
|
|
|
|
month?: number;
|
|
|
|
|
monthCode?: string;
|
|
|
|
|
calendar?: CalendarLike;
|
|
|
|
|
};
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* A `Temporal.PlainYearMonth` represents a particular month on the calendar. For
|
|
|
|
|
* example, it could be used to represent a particular instance of a monthly
|
|
|
|
|
* recurring event, like "the June 2019 meeting".
|
|
|
|
|
*
|
|
|
|
|
* See https://tc39.es/proposal-temporal/docs/yearmonth.html for more details.
|
|
|
|
|
*/
|
|
|
|
|
export class PlainYearMonth {
|
|
|
|
|
static from(
|
|
|
|
|
item: Temporal.PlainYearMonth | PlainYearMonthLike | string,
|
|
|
|
|
options?: AssignmentOptions,
|
|
|
|
|
): Temporal.PlainYearMonth;
|
|
|
|
|
static compare(
|
|
|
|
|
one: Temporal.PlainYearMonth | PlainYearMonthLike | string,
|
|
|
|
|
two: Temporal.PlainYearMonth | PlainYearMonthLike | string,
|
|
|
|
|
): ComparisonResult;
|
|
|
|
|
constructor(
|
|
|
|
|
isoYear: number,
|
|
|
|
|
isoMonth: number,
|
|
|
|
|
calendar?: CalendarLike,
|
|
|
|
|
referenceISODay?: number,
|
|
|
|
|
);
|
|
|
|
|
readonly era: string | undefined;
|
|
|
|
|
readonly eraYear: number | undefined;
|
|
|
|
|
readonly year: number;
|
|
|
|
|
readonly month: number;
|
|
|
|
|
readonly monthCode: string;
|
|
|
|
|
readonly calendarId: string;
|
|
|
|
|
getCalendar(): CalendarProtocol;
|
|
|
|
|
readonly daysInMonth: number;
|
|
|
|
|
readonly daysInYear: number;
|
|
|
|
|
readonly monthsInYear: number;
|
|
|
|
|
readonly inLeapYear: boolean;
|
|
|
|
|
equals(
|
|
|
|
|
other: Temporal.PlainYearMonth | PlainYearMonthLike | string,
|
|
|
|
|
): boolean;
|
|
|
|
|
with(
|
|
|
|
|
yearMonthLike: PlainYearMonthLike,
|
|
|
|
|
options?: AssignmentOptions,
|
|
|
|
|
): Temporal.PlainYearMonth;
|
|
|
|
|
add(
|
|
|
|
|
durationLike: Temporal.Duration | DurationLike | string,
|
|
|
|
|
options?: ArithmeticOptions,
|
|
|
|
|
): Temporal.PlainYearMonth;
|
|
|
|
|
subtract(
|
|
|
|
|
durationLike: Temporal.Duration | DurationLike | string,
|
|
|
|
|
options?: ArithmeticOptions,
|
|
|
|
|
): Temporal.PlainYearMonth;
|
|
|
|
|
until(
|
|
|
|
|
other: Temporal.PlainYearMonth | PlainYearMonthLike | string,
|
|
|
|
|
options?: DifferenceOptions<"year" | "month">,
|
|
|
|
|
): Temporal.Duration;
|
|
|
|
|
since(
|
|
|
|
|
other: Temporal.PlainYearMonth | PlainYearMonthLike | string,
|
|
|
|
|
options?: DifferenceOptions<"year" | "month">,
|
|
|
|
|
): Temporal.Duration;
|
|
|
|
|
toPlainDate(day: { day: number }): Temporal.PlainDate;
|
|
|
|
|
getISOFields(): PlainDateISOFields;
|
|
|
|
|
toLocaleString(
|
|
|
|
|
locales?: string | string[],
|
|
|
|
|
options?: Intl.DateTimeFormatOptions,
|
|
|
|
|
): string;
|
|
|
|
|
toJSON(): string;
|
|
|
|
|
toString(options?: ShowCalendarOption): string;
|
|
|
|
|
valueOf(): never;
|
|
|
|
|
readonly [Symbol.toStringTag]: "Temporal.PlainYearMonth";
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
export type ZonedDateTimeLike = {
|
|
|
|
|
era?: string | undefined;
|
|
|
|
|
eraYear?: number | undefined;
|
|
|
|
|
year?: number;
|
|
|
|
|
month?: number;
|
|
|
|
|
monthCode?: string;
|
|
|
|
|
day?: number;
|
|
|
|
|
hour?: number;
|
|
|
|
|
minute?: number;
|
|
|
|
|
second?: number;
|
|
|
|
|
millisecond?: number;
|
|
|
|
|
microsecond?: number;
|
|
|
|
|
nanosecond?: number;
|
|
|
|
|
offset?: string;
|
|
|
|
|
timeZone?: TimeZoneLike;
|
|
|
|
|
calendar?: CalendarLike;
|
|
|
|
|
};
|
|
|
|
|
|
|
|
|
|
type ZonedDateTimeISOFields = {
|
|
|
|
|
isoYear: number;
|
|
|
|
|
isoMonth: number;
|
|
|
|
|
isoDay: number;
|
|
|
|
|
isoHour: number;
|
|
|
|
|
isoMinute: number;
|
|
|
|
|
isoSecond: number;
|
|
|
|
|
isoMillisecond: number;
|
|
|
|
|
isoMicrosecond: number;
|
|
|
|
|
isoNanosecond: number;
|
|
|
|
|
offset: string;
|
|
|
|
|
timeZone: string | TimeZoneProtocol;
|
|
|
|
|
calendar: string | CalendarProtocol;
|
|
|
|
|
};
|
|
|
|
|
|
|
|
|
|
export class ZonedDateTime {
|
|
|
|
|
static from(
|
|
|
|
|
item: Temporal.ZonedDateTime | ZonedDateTimeLike | string,
|
|
|
|
|
options?: ZonedDateTimeAssignmentOptions,
|
|
|
|
|
): ZonedDateTime;
|
|
|
|
|
static compare(
|
|
|
|
|
one: Temporal.ZonedDateTime | ZonedDateTimeLike | string,
|
|
|
|
|
two: Temporal.ZonedDateTime | ZonedDateTimeLike | string,
|
|
|
|
|
): ComparisonResult;
|
|
|
|
|
constructor(
|
|
|
|
|
epochNanoseconds: bigint,
|
|
|
|
|
timeZone: TimeZoneLike,
|
|
|
|
|
calendar?: CalendarLike,
|
|
|
|
|
);
|
|
|
|
|
readonly era: string | undefined;
|
|
|
|
|
readonly eraYear: number | undefined;
|
|
|
|
|
readonly year: number;
|
|
|
|
|
readonly month: number;
|
|
|
|
|
readonly monthCode: string;
|
|
|
|
|
readonly day: number;
|
|
|
|
|
readonly hour: number;
|
|
|
|
|
readonly minute: number;
|
|
|
|
|
readonly second: number;
|
|
|
|
|
readonly millisecond: number;
|
|
|
|
|
readonly microsecond: number;
|
|
|
|
|
readonly nanosecond: number;
|
|
|
|
|
readonly timeZoneId: string;
|
|
|
|
|
getTimeZone(): TimeZoneProtocol;
|
|
|
|
|
readonly calendarId: string;
|
|
|
|
|
getCalendar(): CalendarProtocol;
|
|
|
|
|
readonly dayOfWeek: number;
|
|
|
|
|
readonly dayOfYear: number;
|
|
|
|
|
readonly weekOfYear: number;
|
|
|
|
|
readonly yearOfWeek: number;
|
|
|
|
|
readonly hoursInDay: number;
|
|
|
|
|
readonly daysInWeek: number;
|
|
|
|
|
readonly daysInMonth: number;
|
|
|
|
|
readonly daysInYear: number;
|
|
|
|
|
readonly monthsInYear: number;
|
|
|
|
|
readonly inLeapYear: boolean;
|
|
|
|
|
readonly offsetNanoseconds: number;
|
|
|
|
|
readonly offset: string;
|
|
|
|
|
readonly epochSeconds: number;
|
|
|
|
|
readonly epochMilliseconds: number;
|
|
|
|
|
readonly epochMicroseconds: bigint;
|
|
|
|
|
readonly epochNanoseconds: bigint;
|
|
|
|
|
equals(other: Temporal.ZonedDateTime | ZonedDateTimeLike | string): boolean;
|
|
|
|
|
with(
|
|
|
|
|
zonedDateTimeLike: ZonedDateTimeLike,
|
|
|
|
|
options?: ZonedDateTimeAssignmentOptions,
|
|
|
|
|
): Temporal.ZonedDateTime;
|
|
|
|
|
withPlainTime(
|
|
|
|
|
timeLike?: Temporal.PlainTime | PlainTimeLike | string,
|
|
|
|
|
): Temporal.ZonedDateTime;
|
|
|
|
|
withPlainDate(
|
|
|
|
|
dateLike: Temporal.PlainDate | PlainDateLike | string,
|
|
|
|
|
): Temporal.ZonedDateTime;
|
|
|
|
|
withCalendar(calendar: CalendarLike): Temporal.ZonedDateTime;
|
|
|
|
|
withTimeZone(timeZone: TimeZoneLike): Temporal.ZonedDateTime;
|
|
|
|
|
add(
|
|
|
|
|
durationLike: Temporal.Duration | DurationLike | string,
|
|
|
|
|
options?: ArithmeticOptions,
|
|
|
|
|
): Temporal.ZonedDateTime;
|
|
|
|
|
subtract(
|
|
|
|
|
durationLike: Temporal.Duration | DurationLike | string,
|
|
|
|
|
options?: ArithmeticOptions,
|
|
|
|
|
): Temporal.ZonedDateTime;
|
|
|
|
|
until(
|
|
|
|
|
other: Temporal.ZonedDateTime | ZonedDateTimeLike | string,
|
|
|
|
|
options?: Temporal.DifferenceOptions<
|
|
|
|
|
| "year"
|
|
|
|
|
| "month"
|
|
|
|
|
| "week"
|
|
|
|
|
| "day"
|
|
|
|
|
| "hour"
|
|
|
|
|
| "minute"
|
|
|
|
|
| "second"
|
|
|
|
|
| "millisecond"
|
|
|
|
|
| "microsecond"
|
|
|
|
|
| "nanosecond"
|
|
|
|
|
>,
|
|
|
|
|
): Temporal.Duration;
|
|
|
|
|
since(
|
|
|
|
|
other: Temporal.ZonedDateTime | ZonedDateTimeLike | string,
|
|
|
|
|
options?: Temporal.DifferenceOptions<
|
|
|
|
|
| "year"
|
|
|
|
|
| "month"
|
|
|
|
|
| "week"
|
|
|
|
|
| "day"
|
|
|
|
|
| "hour"
|
|
|
|
|
| "minute"
|
|
|
|
|
| "second"
|
|
|
|
|
| "millisecond"
|
|
|
|
|
| "microsecond"
|
|
|
|
|
| "nanosecond"
|
|
|
|
|
>,
|
|
|
|
|
): Temporal.Duration;
|
|
|
|
|
round(
|
|
|
|
|
roundTo: RoundTo<
|
|
|
|
|
| "day"
|
|
|
|
|
| "hour"
|
|
|
|
|
| "minute"
|
|
|
|
|
| "second"
|
|
|
|
|
| "millisecond"
|
|
|
|
|
| "microsecond"
|
|
|
|
|
| "nanosecond"
|
|
|
|
|
>,
|
|
|
|
|
): Temporal.ZonedDateTime;
|
|
|
|
|
startOfDay(): Temporal.ZonedDateTime;
|
|
|
|
|
toInstant(): Temporal.Instant;
|
|
|
|
|
toPlainDateTime(): Temporal.PlainDateTime;
|
|
|
|
|
toPlainDate(): Temporal.PlainDate;
|
|
|
|
|
toPlainYearMonth(): Temporal.PlainYearMonth;
|
|
|
|
|
toPlainMonthDay(): Temporal.PlainMonthDay;
|
|
|
|
|
toPlainTime(): Temporal.PlainTime;
|
|
|
|
|
getISOFields(): ZonedDateTimeISOFields;
|
|
|
|
|
toLocaleString(
|
|
|
|
|
locales?: string | string[],
|
|
|
|
|
options?: Intl.DateTimeFormatOptions,
|
|
|
|
|
): string;
|
|
|
|
|
toJSON(): string;
|
|
|
|
|
toString(options?: ZonedDateTimeToStringOptions): string;
|
|
|
|
|
valueOf(): never;
|
|
|
|
|
readonly [Symbol.toStringTag]: "Temporal.ZonedDateTime";
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* The `Temporal.Now` object has several methods which give information about
|
|
|
|
|
* the current date, time, and time zone.
|
|
|
|
|
*
|
|
|
|
|
* See https://tc39.es/proposal-temporal/docs/now.html for more details.
|
|
|
|
|
*/
|
|
|
|
|
export const Now: {
|
|
|
|
|
/**
|
|
|
|
|
* Get the exact system date and time as a `Temporal.Instant`.
|
|
|
|
|
*
|
|
|
|
|
* This method gets the current exact system time, without regard to
|
|
|
|
|
* calendar or time zone. This is a good way to get a timestamp for an
|
|
|
|
|
* event, for example. It works like the old-style JavaScript `Date.now()`,
|
|
|
|
|
* but with nanosecond precision instead of milliseconds.
|
|
|
|
|
*
|
|
|
|
|
* Note that a `Temporal.Instant` doesn't know about time zones. For the
|
|
|
|
|
* exact time in a specific time zone, use `Temporal.Now.zonedDateTimeISO`
|
|
|
|
|
* or `Temporal.Now.zonedDateTime`.
|
|
|
|
|
*/
|
|
|
|
|
instant: () => Temporal.Instant;
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* Get the current calendar date and clock time in a specific calendar and
|
|
|
|
|
* time zone.
|
|
|
|
|
*
|
|
|
|
|
* The `calendar` parameter is required. When using the ISO 8601 calendar or
|
|
|
|
|
* if you don't understand the need for or implications of a calendar, then
|
|
|
|
|
* a more ergonomic alternative to this method is
|
|
|
|
|
* `Temporal.Now.zonedDateTimeISO()`.
|
|
|
|
|
*
|
|
|
|
|
* @param {CalendarLike} [calendar] - calendar identifier, or
|
|
|
|
|
* a `Temporal.Calendar` instance, or an object implementing the calendar
|
|
|
|
|
* protocol.
|
|
|
|
|
* @param {TimeZoneLike} [tzLike] -
|
|
|
|
|
* {@link https://en.wikipedia.org/wiki/List_of_tz_database_time_zones|IANA time zone identifier}
|
|
|
|
|
* string (e.g. `'Europe/London'`), `Temporal.TimeZone` instance, or an
|
|
|
|
|
* object implementing the time zone protocol. If omitted, the environment's
|
|
|
|
|
* current time zone will be used.
|
|
|
|
|
*/
|
|
|
|
|
zonedDateTime: (
|
|
|
|
|
calendar: CalendarLike,
|
|
|
|
|
tzLike?: TimeZoneLike,
|
|
|
|
|
) => Temporal.ZonedDateTime;
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* Get the current calendar date and clock time in a specific time zone,
|
|
|
|
|
* using the ISO 8601 calendar.
|
|
|
|
|
*
|
|
|
|
|
* @param {TimeZoneLike} [tzLike] -
|
|
|
|
|
* {@link https://en.wikipedia.org/wiki/List_of_tz_database_time_zones|IANA time zone identifier}
|
|
|
|
|
* string (e.g. `'Europe/London'`), `Temporal.TimeZone` instance, or an
|
|
|
|
|
* object implementing the time zone protocol. If omitted, the environment's
|
|
|
|
|
* current time zone will be used.
|
|
|
|
|
*/
|
|
|
|
|
zonedDateTimeISO: (tzLike?: TimeZoneLike) => Temporal.ZonedDateTime;
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* Get the current calendar date and clock time in a specific calendar and
|
|
|
|
|
* time zone.
|
|
|
|
|
*
|
|
|
|
|
* The calendar is required. When using the ISO 8601 calendar or if you
|
|
|
|
|
* don't understand the need for or implications of a calendar, then a more
|
|
|
|
|
* ergonomic alternative to this method is `Temporal.Now.plainDateTimeISO`.
|
|
|
|
|
*
|
|
|
|
|
* Note that the `Temporal.PlainDateTime` type does not persist the time zone,
|
|
|
|
|
* but retaining the time zone is required for most time-zone-related use
|
|
|
|
|
* cases. Therefore, it's usually recommended to use
|
|
|
|
|
* `Temporal.Now.zonedDateTimeISO` or `Temporal.Now.zonedDateTime` instead
|
|
|
|
|
* of this function.
|
|
|
|
|
*
|
|
|
|
|
* @param {CalendarLike} [calendar] - calendar identifier, or
|
|
|
|
|
* a `Temporal.Calendar` instance, or an object implementing the calendar
|
|
|
|
|
* protocol.
|
|
|
|
|
* @param {TimeZoneLike} [tzLike] -
|
|
|
|
|
* {@link https://en.wikipedia.org/wiki/List_of_tz_database_time_zones|IANA time zone identifier}
|
|
|
|
|
* string (e.g. `'Europe/London'`), `Temporal.TimeZone` instance, or an
|
|
|
|
|
* object implementing the time zone protocol. If omitted,
|
|
|
|
|
* the environment's current time zone will be used.
|
|
|
|
|
*/
|
|
|
|
|
plainDateTime: (
|
|
|
|
|
calendar: CalendarLike,
|
|
|
|
|
tzLike?: TimeZoneLike,
|
|
|
|
|
) => Temporal.PlainDateTime;
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* Get the current date and clock time in a specific time zone, using the
|
|
|
|
|
* ISO 8601 calendar.
|
|
|
|
|
*
|
|
|
|
|
* Note that the `Temporal.PlainDateTime` type does not persist the time zone,
|
|
|
|
|
* but retaining the time zone is required for most time-zone-related use
|
|
|
|
|
* cases. Therefore, it's usually recommended to use
|
|
|
|
|
* `Temporal.Now.zonedDateTimeISO` instead of this function.
|
|
|
|
|
*
|
|
|
|
|
* @param {TimeZoneLike} [tzLike] -
|
|
|
|
|
* {@link https://en.wikipedia.org/wiki/List_of_tz_database_time_zones|IANA time zone identifier}
|
|
|
|
|
* string (e.g. `'Europe/London'`), `Temporal.TimeZone` instance, or an
|
|
|
|
|
* object implementing the time zone protocol. If omitted, the environment's
|
|
|
|
|
* current time zone will be used.
|
|
|
|
|
*/
|
|
|
|
|
plainDateTimeISO: (tzLike?: TimeZoneLike) => Temporal.PlainDateTime;
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* Get the current calendar date in a specific calendar and time zone.
|
|
|
|
|
*
|
|
|
|
|
* The calendar is required. When using the ISO 8601 calendar or if you
|
|
|
|
|
* don't understand the need for or implications of a calendar, then a more
|
|
|
|
|
* ergonomic alternative to this method is `Temporal.Now.plainDateISO`.
|
|
|
|
|
*
|
|
|
|
|
* @param {CalendarLike} [calendar] - calendar identifier, or
|
|
|
|
|
* a `Temporal.Calendar` instance, or an object implementing the calendar
|
|
|
|
|
* protocol.
|
|
|
|
|
* @param {TimeZoneLike} [tzLike] -
|
|
|
|
|
* {@link https://en.wikipedia.org/wiki/List_of_tz_database_time_zones|IANA time zone identifier}
|
|
|
|
|
* string (e.g. `'Europe/London'`), `Temporal.TimeZone` instance, or an
|
|
|
|
|
* object implementing the time zone protocol. If omitted,
|
|
|
|
|
* the environment's current time zone will be used.
|
|
|
|
|
*/
|
|
|
|
|
plainDate: (
|
|
|
|
|
calendar: CalendarLike,
|
|
|
|
|
tzLike?: TimeZoneLike,
|
|
|
|
|
) => Temporal.PlainDate;
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* Get the current date in a specific time zone, using the ISO 8601
|
|
|
|
|
* calendar.
|
|
|
|
|
*
|
|
|
|
|
* @param {TimeZoneLike} [tzLike] -
|
|
|
|
|
* {@link https://en.wikipedia.org/wiki/List_of_tz_database_time_zones|IANA time zone identifier}
|
|
|
|
|
* string (e.g. `'Europe/London'`), `Temporal.TimeZone` instance, or an
|
|
|
|
|
* object implementing the time zone protocol. If omitted, the environment's
|
|
|
|
|
* current time zone will be used.
|
|
|
|
|
*/
|
|
|
|
|
plainDateISO: (tzLike?: TimeZoneLike) => Temporal.PlainDate;
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* Get the current clock time in a specific time zone, using the ISO 8601 calendar.
|
|
|
|
|
*
|
|
|
|
|
* @param {TimeZoneLike} [tzLike] -
|
|
|
|
|
* {@link https://en.wikipedia.org/wiki/List_of_tz_database_time_zones|IANA time zone identifier}
|
|
|
|
|
* string (e.g. `'Europe/London'`), `Temporal.TimeZone` instance, or an
|
|
|
|
|
* object implementing the time zone protocol. If omitted, the environment's
|
|
|
|
|
* current time zone will be used.
|
|
|
|
|
*/
|
|
|
|
|
plainTimeISO: (tzLike?: TimeZoneLike) => Temporal.PlainTime;
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* Get the identifier of the environment's current time zone.
|
|
|
|
|
*
|
|
|
|
|
* This method gets the identifier of the current system time zone. This
|
|
|
|
|
* will usually be a named
|
|
|
|
|
* {@link https://en.wikipedia.org/wiki/List_of_tz_database_time_zones|IANA time zone}.
|
|
|
|
|
*/
|
|
|
|
|
timeZoneId: () => string;
|
|
|
|
|
|
|
|
|
|
readonly [Symbol.toStringTag]: "Temporal.Now";
|
|
|
|
|
};
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
declare namespace Intl {
|
|
|
|
|
type Formattable =
|
|
|
|
|
| Date
|
|
|
|
|
| Temporal.Instant
|
|
|
|
|
| Temporal.ZonedDateTime
|
|
|
|
|
| Temporal.PlainDate
|
|
|
|
|
| Temporal.PlainTime
|
|
|
|
|
| Temporal.PlainDateTime
|
|
|
|
|
| Temporal.PlainYearMonth
|
|
|
|
|
| Temporal.PlainMonthDay;
|
|
|
|
|
|
|
|
|
|
interface DateTimeFormatRangePart {
|
|
|
|
|
source: "shared" | "startRange" | "endRange";
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
export interface DateTimeFormat {
|
|
|
|
|
/**
|
|
|
|
|
* Format a date into a string according to the locale and formatting
|
|
|
|
|
* options of this `Intl.DateTimeFormat` object.
|
|
|
|
|
*
|
|
|
|
|
* @param date The date to format.
|
|
|
|
|
*/
|
|
|
|
|
format(date?: Formattable | number): string;
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* Allow locale-aware formatting of strings produced by
|
|
|
|
|
* `Intl.DateTimeFormat` formatters.
|
|
|
|
|
*
|
|
|
|
|
* @param date The date to format.
|
|
|
|
|
*/
|
|
|
|
|
formatToParts(
|
|
|
|
|
date?: Formattable | number,
|
|
|
|
|
): globalThis.Intl.DateTimeFormatPart[];
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* Format a date range in the most concise way based on the locale and
|
|
|
|
|
* options provided when instantiating this `Intl.DateTimeFormat` object.
|
|
|
|
|
*
|
|
|
|
|
* @param startDate The start date of the range to format.
|
|
|
|
|
* @param endDate The start date of the range to format. Must be the same
|
|
|
|
|
* type as `startRange`.
|
|
|
|
|
*/
|
|
|
|
|
formatRange<T extends Formattable>(startDate: T, endDate: T): string;
|
|
|
|
|
formatRange(startDate: Date | number, endDate: Date | number): string;
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* Allow locale-aware formatting of tokens representing each part of the
|
|
|
|
|
* formatted date range produced by `Intl.DateTimeFormat` formatters.
|
|
|
|
|
*
|
|
|
|
|
* @param startDate The start date of the range to format.
|
|
|
|
|
* @param endDate The start date of the range to format. Must be the same
|
|
|
|
|
* type as `startRange`.
|
|
|
|
|
*/
|
|
|
|
|
formatRangeToParts<T extends Formattable>(
|
|
|
|
|
startDate: T,
|
|
|
|
|
endDate: T,
|
|
|
|
|
): DateTimeFormatRangePart[];
|
|
|
|
|
formatRangeToParts(
|
|
|
|
|
startDate: Date | number,
|
|
|
|
|
endDate: Date | number,
|
|
|
|
|
): DateTimeFormatRangePart[];
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
export interface DateTimeFormatOptions {
|
|
|
|
|
// TODO: remove the props below after TS lib declarations are updated
|
|
|
|
|
dayPeriod?: "narrow" | "short" | "long";
|
|
|
|
|
dateStyle?: "full" | "long" | "medium" | "short";
|
|
|
|
|
timeStyle?: "full" | "long" | "medium" | "short";
|
|
|
|
|
}
|
|
|
|
|
}
|