foster/denoland-deno
1
0
Fork 0
mirror of https://github.com/denoland/deno.git synced 2024-11-21 15:04:11 -05:00
Code Issues Packages 1 Wiki Activity

refactor: move WebGPU, FFI and FS typings from unstable to stable (#25488)

Browse source 
Closes #25377
This commit is contained in:
Leo Kettmeir 2024-09-10 05:04:59 -07:00 committed by GitHub
parent 9a169e3cf1
commit c2f97494f7
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
7 changed files with 847 additions and 1375 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

689
cli/tsc/dts/lib.deno.ns.d.ts vendored
View file

@ -4556,6 +4556,24 @@ declare namespace Deno {
mtime: number | Date,
): Promise<void>;
/** Retrieve the process umask. If `mask` is provided, sets the process umask.
* This call always returns what the umask was before the call.
*
* ```ts
* console.log(Deno.umask()); // e.g. 18 (0o022)
* const prevUmaskValue = Deno.umask(0o077); // e.g. 18 (0o022)
* console.log(Deno.umask()); // e.g. 63 (0o077)
* ```
*
* This API is under consideration to determine if permissions are required to
* call it.
*
* *Note*: This API is not implemented on Windows
*
* @category File System
*/
export function umask(mask?: number): number;
/** The object that is returned from a {@linkcode Deno.upgradeWebSocket}
* request.
*
@ -5395,4 +5413,675 @@ declare namespace Deno {
& (ServeTcpOptions | (ServeTcpOptions & TlsCertifiedKeyOptions))
& ServeInit<Deno.NetAddr>,
): HttpServer<Deno.NetAddr>;
/** All plain number types for interfacing with foreign functions.
*
* @category FFI
*/
export type NativeNumberType =
| "u8"
| "i8"
| "u16"
| "i16"
| "u32"
| "i32"
| "f32"
| "f64";
/** All BigInt number types for interfacing with foreign functions.
*
* @category FFI
*/
export type NativeBigIntType =
| "u64"
| "i64"
| "usize"
| "isize";
/** The native boolean type for interfacing to foreign functions.
*
* @category FFI
*/
export type NativeBooleanType = "bool";
/** The native pointer type for interfacing to foreign functions.
*
* @category FFI
*/
export type NativePointerType = "pointer";
/** The native buffer type for interfacing to foreign functions.
*
* @category FFI
*/
export type NativeBufferType = "buffer";
/** The native function type for interfacing with foreign functions.
*
* @category FFI
*/
export type NativeFunctionType = "function";
/** The native void type for interfacing with foreign functions.
*
* @category FFI
*/
export type NativeVoidType = "void";
/** The native struct type for interfacing with foreign functions.
*
* @category FFI
*/
export type NativeStructType = { readonly struct: readonly NativeType[] };
/**
* @category FFI
*/
export 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;
};
/**
* @category FFI
*/
export type NativeTypedFunction<T extends UnsafeCallbackDefinition> =
& "function"
& {
[brand]: T;
};
/** All supported types for interfacing with foreign functions.
*
* @category FFI
*/
export type NativeType =
| NativeNumberType
| NativeBigIntType
| NativeBooleanType
| NativePointerType
| NativeBufferType
| NativeFunctionType
| NativeStructType;
/** @category FFI
*/
export type NativeResultType = NativeType | NativeVoidType;
/** Type conversion for foreign symbol parameters and unsafe callback return
* types.
*
* @category FFI
*/
export type ToNativeType<T extends NativeType = NativeType> = T extends
NativeStructType ? BufferSource
: 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 ? 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;
/** Type conversion for unsafe callback return types.
*
* @category FFI
*/
export type ToNativeResultType<
T extends NativeResultType = NativeResultType,
> = T extends NativeStructType ? BufferSource
: 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 ? 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;
/** A utility type for conversion of parameter types of foreign functions.
*
* @category FFI
*/
export 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]>;
}
: never;
/** Type conversion for foreign symbol return types and unsafe callback
* parameters.
*
* @category FFI
*/
export type FromNativeType<T extends NativeType = NativeType> = T extends
NativeStructType ? Uint8Array
: 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 ? 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;
/** Type conversion for foreign symbol return types.
*
* @category FFI
*/
export type FromNativeResultType<
T extends NativeResultType = NativeResultType,
> = T extends NativeStructType ? Uint8Array
: 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 ? 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;
/** @category FFI
*/
export 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]>;
}
: never;
/** The interface for a foreign function as defined by its parameter and result
* types.
*
* @category FFI
*/
export interface ForeignFunction<
Parameters extends readonly NativeType[] = readonly NativeType[],
Result extends NativeResultType = NativeResultType,
NonBlocking extends boolean = boolean,
> {
/** Name of the symbol.
*
* Defaults to the key name in symbols object. */
name?: string;
/** The parameters of the foreign function. */
parameters: Parameters;
/** The result (return value) of the foreign function. */
result: Result;
/** When `true`, function calls will run on a dedicated blocking thread and
* will return a `Promise` resolving to the `result`. */
nonblocking?: NonBlocking;
/** When `true`, dlopen will not fail if the symbol is not found.
* Instead, the symbol will be set to `null`.
*
* @default {false} */
optional?: boolean;
}
/** @category FFI
*/
export interface ForeignStatic<Type extends NativeType = NativeType> {
/** Name of the symbol, defaults to the key name in symbols object. */
name?: string;
/** The type of the foreign static value. */
type: Type;
/** When `true`, dlopen will not fail if the symbol is not found.
* Instead, the symbol will be set to `null`.
*
* @default {false} */
optional?: boolean;
}
/** A foreign library interface descriptor.
*
* @category FFI
*/
export interface ForeignLibraryInterface {
[name: string]: ForeignFunction | ForeignStatic;
}
/** A utility type that infers a foreign symbol.
*
* @category FFI
*/
export type StaticForeignSymbol<T extends ForeignFunction | ForeignStatic> =
T extends ForeignFunction ? FromForeignFunction<T>
: T extends ForeignStatic ? FromNativeType<T["type"]>
: never;
/** @category FFI
*/
export type FromForeignFunction<T extends ForeignFunction> =
T["parameters"] extends readonly [] ? () => StaticForeignSymbolReturnType<T>
: (
...args: ToNativeParameterTypes<T["parameters"]>
) => StaticForeignSymbolReturnType<T>;
/** @category FFI
*/
export type StaticForeignSymbolReturnType<T extends ForeignFunction> =
ConditionalAsync<T["nonblocking"], FromNativeResultType<T["result"]>>;
/** @category FFI
*/
export type ConditionalAsync<IsAsync extends boolean | undefined, T> =
IsAsync extends true ? Promise<T> : T;
/** A utility type that infers a foreign library interface.
*
* @category FFI
*/
export type StaticForeignLibraryInterface<T extends ForeignLibraryInterface> =
{
[K in keyof T]: T[K]["optional"] extends true
? StaticForeignSymbol<T[K]> | null
: StaticForeignSymbol<T[K]>;
};
/** 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 };
/** Pointers are represented either with a {@linkcode PointerObject}
* object or a `null` if the pointer is null.
*
* @category FFI
*/
export type PointerValue<T = unknown> = null | PointerObject<T>;
/** A collection of static functions for interacting with pointer objects.
*
* @category FFI
*/
export class UnsafePointer {
/** Create a pointer from a numeric value. This one is <i>really</i> dangerous! */
static create<T = unknown>(value: bigint): PointerValue<T>;
/** Returns `true` if the two pointers point to the same address. */
static equals<T = unknown>(a: PointerValue<T>, b: PointerValue<T>): boolean;
/** Return the direct memory pointer to the typed array in memory. */
static of<T = unknown>(
value: Deno.UnsafeCallback | BufferSource,
): PointerValue<T>;
/** Return a new pointer offset from the original by `offset` bytes. */
static offset<T = unknown>(
value: PointerObject,
offset: number,
): PointerValue<T>;
/** Get the numeric value of a pointer */
static value(value: PointerValue): bigint;
}
/** An unsafe pointer view to a memory location as specified by the `pointer`
* value. The `UnsafePointerView` API follows the standard built in interface
* {@linkcode DataView} for accessing the underlying types at an memory
* location (numbers, strings and raw bytes).
*
* @category FFI
*/
export class UnsafePointerView {
constructor(pointer: PointerObject);
pointer: PointerObject;
/** Gets a boolean at the specified byte offset from the pointer. */
getBool(offset?: number): boolean;
/** Gets an unsigned 8-bit integer at the specified byte offset from the
* pointer. */
getUint8(offset?: number): number;
/** Gets a signed 8-bit integer at the specified byte offset from the
* pointer. */
getInt8(offset?: number): number;
/** Gets an unsigned 16-bit integer at the specified byte offset from the
* pointer. */
getUint16(offset?: number): number;
/** Gets a signed 16-bit integer at the specified byte offset from the
* pointer. */
getInt16(offset?: number): number;
/** Gets an unsigned 32-bit integer at the specified byte offset from the
* pointer. */
getUint32(offset?: number): number;
/** Gets a signed 32-bit integer at the specified byte offset from the
* pointer. */
getInt32(offset?: number): number;
/** Gets an unsigned 64-bit integer at the specified byte offset from the
* pointer. */
getBigUint64(offset?: number): bigint;
/** Gets a signed 64-bit integer at the specified byte offset from the
* pointer. */
getBigInt64(offset?: number): bigint;
/** Gets a signed 32-bit float at the specified byte offset from the
* pointer. */
getFloat32(offset?: number): number;
/** Gets a signed 64-bit float at the specified byte offset from the
* pointer. */
getFloat64(offset?: number): number;
/** Gets a pointer at the specified byte offset from the pointer */
getPointer<T = unknown>(offset?: number): PointerValue<T>;
/** Gets a C string (`null` terminated string) at the specified byte offset
* from the pointer. */
getCString(offset?: number): string;
/** Gets a C string (`null` terminated string) at the specified byte offset
* from the specified pointer. */
static getCString(
pointer: PointerObject,
offset?: number,
): string;
/** Gets an `ArrayBuffer` of length `byteLength` at the specified byte
* offset from the pointer. */
getArrayBuffer(byteLength: number, offset?: number): ArrayBuffer;
/** Gets an `ArrayBuffer` of length `byteLength` at the specified byte
* offset from the specified pointer. */
static getArrayBuffer(
pointer: PointerObject,
byteLength: number,
offset?: number,
): ArrayBuffer;
/** Copies the memory of the pointer into a typed array.
*
* Length is determined from the typed array's `byteLength`.
*
* Also takes optional byte offset from the pointer. */
copyInto(destination: BufferSource, offset?: number): void;
/** Copies the memory of the specified pointer into a typed array.
*
* Length is determined from the typed array's `byteLength`.
*
* Also takes optional byte offset from the pointer. */
static copyInto(
pointer: PointerObject,
destination: BufferSource,
offset?: number,
): void;
}
/** An unsafe pointer to a function, for calling functions that are not present
* as symbols.
*
* @category FFI
*/
export class UnsafeFnPointer<const Fn extends ForeignFunction> {
/** The pointer to the function. */
pointer: PointerObject<Fn>;
/** The definition of the function. */
definition: Fn;
constructor(pointer: PointerObject<NoInfer<Fn>>, definition: Fn);
/** @deprecated Properly type {@linkcode pointer} using {@linkcode NativeTypedFunction} or {@linkcode UnsafeCallbackDefinition} types. */
constructor(pointer: PointerObject, definition: Fn);
/** Call the foreign function. */
call: FromForeignFunction<Fn>;
}
/** Definition of a unsafe callback function.
*
* @category FFI
*/
export interface UnsafeCallbackDefinition<
Parameters extends readonly NativeType[] = readonly NativeType[],
Result extends NativeResultType = NativeResultType,
> {
/** The parameters of the callbacks. */
parameters: Parameters;
/** The current result of the callback. */
result: Result;
}
/** An unsafe callback function.
*
* @category FFI
*/
export type UnsafeCallbackFunction<
Parameters extends readonly NativeType[] = readonly NativeType[],
Result extends NativeResultType = NativeResultType,
> = Parameters extends readonly [] ? () => ToNativeResultType<Result> : (
...args: FromNativeParameterTypes<Parameters>
) => ToNativeResultType<Result>;
/** An unsafe function pointer for passing JavaScript functions as C function
* pointers to foreign function calls.
*
* The function pointer remains valid until the `close()` method is called.
*
* All `UnsafeCallback` are always thread safe in that they can be called from
* foreign threads without crashing. However, they do not wake up the Deno event
* loop by default.
*
* If a callback is to be called from foreign threads, use the `threadSafe()`
* static constructor or explicitly call `ref()` to have the callback wake up
* the Deno event loop when called from foreign threads. This also stops
* Deno's process from exiting while the callback still exists and is not
* unref'ed.
*
* Use `deref()` to then allow Deno's process to exit. Calling `deref()` on
* a ref'ed callback does not stop it from waking up the Deno event loop when
* called from foreign threads.
*
* @category FFI
*/
export class UnsafeCallback<
const Definition extends UnsafeCallbackDefinition =
UnsafeCallbackDefinition,
> {
constructor(
definition: Definition,
callback: UnsafeCallbackFunction<
Definition["parameters"],
Definition["result"]
>,
);
/** The pointer to the unsafe callback. */
readonly pointer: PointerObject<Definition>;
/** The definition of the unsafe callback. */
readonly definition: Definition;
/** The callback function. */
readonly callback: UnsafeCallbackFunction<
Definition["parameters"],
Definition["result"]
>;
/**
* Creates an {@linkcode UnsafeCallback} and calls `ref()` once to allow it to
* wake up the Deno event loop when called from foreign threads.
*
* This also stops Deno's process from exiting while the callback still
* exists and is not unref'ed.
*/
static threadSafe<
Definition extends UnsafeCallbackDefinition = UnsafeCallbackDefinition,
>(
definition: Definition,
callback: UnsafeCallbackFunction<
Definition["parameters"],
Definition["result"]
>,
): UnsafeCallback<Definition>;
/**
* Increments the callback's reference counting and returns the new
* reference count.
*
* After `ref()` has been called, the callback always wakes up the
* Deno event loop when called from foreign threads.
*
* If the callback's reference count is non-zero, it keeps Deno's
* process from exiting.
*/
ref(): number;
/**
* Decrements the callback's reference counting and returns the new
* reference count.
*
* Calling `unref()` does not stop a callback from waking up the Deno
* event loop when called from foreign threads.
*
* If the callback's reference counter is zero, it no longer keeps
* Deno's process from exiting.
*/
unref(): number;
/**
* Removes the C function pointer associated with this instance.
*
* Continuing to use the instance or the C function pointer after closing
* the `UnsafeCallback` will lead to errors and crashes.
*
* Calling this method sets the callback's reference counting to zero,
* stops the callback from waking up the Deno event loop when called from
* foreign threads and no longer keeps Deno's process from exiting.
*/
close(): void;
}
/** A dynamic library resource. Use {@linkcode Deno.dlopen} to load a dynamic
* library and return this interface.
*
* @category FFI
*/
export interface DynamicLibrary<S extends ForeignLibraryInterface> {
/** All of the registered library along with functions for calling them. */
symbols: StaticForeignLibraryInterface<S>;
/** Removes the pointers associated with the library symbols.
*
* Continuing to use symbols that are part of the library will lead to
* errors and crashes.
*
* Calling this method will also immediately set any references to zero and
* will no longer keep Deno's process from exiting.
*/
close(): void;
}
/** Opens an external dynamic library and registers symbols, making foreign
* functions available to be called.
*
* Requires `allow-ffi` permission. Loading foreign dynamic libraries can in
* theory bypass all of the sandbox permissions. While it is a separate
* permission users should acknowledge in practice that is effectively the
* same as running with the `allow-all` permission.
*
* @example Given a C library which exports a foreign function named `add()`
*
* ```ts
* // Determine library extension based on
* // your OS.
* let libSuffix = "";
* switch (Deno.build.os) {
* case "windows":
* libSuffix = "dll";
* break;
* case "darwin":
* libSuffix = "dylib";
* break;
* default:
* libSuffix = "so";
* break;
* }
*
* const libName = `./libadd.${libSuffix}`;
* // Open library and define exported symbols
* const dylib = Deno.dlopen(
* libName,
* {
* "add": { parameters: ["isize", "isize"], result: "isize" },
* } as const,
* );
*
* // Call the symbol `add`
* const result = dylib.symbols.add(35n, 34n); // 69n
*
* console.log(`Result from external addition of 35 and 34: ${result}`);
* ```
*
* @tags allow-ffi
* @category FFI
*/
export function dlopen<const S extends ForeignLibraryInterface>(
filename: string | URL,
symbols: S,
): DynamicLibrary<S>;
}

804
cli/tsc/dts/lib.deno.unstable.d.ts vendored
View file

@ -3,816 +3,12 @@
/// <reference no-default-lib="true" />
/// <reference lib="deno.ns" />
/// <reference lib="deno.broadcast_channel" />
/// <reference lib="deno.webgpu" />
/// <reference lib="esnext" />
/// <reference lib="es2022.intl" />
declare namespace Deno {
export {}; // stop default export type behavior
/** **UNSTABLE**: New API, yet to be vetted.
*
* Retrieve the process umask. If `mask` is provided, sets the process umask.
* This call always returns what the umask was before the call.
*
* ```ts
* console.log(Deno.umask()); // e.g. 18 (0o022)
* const prevUmaskValue = Deno.umask(0o077); // e.g. 18 (0o022)
* console.log(Deno.umask()); // e.g. 63 (0o077)
* ```
*
* This API is under consideration to determine if permissions are required to
* call it.
*
* *Note*: This API is not implemented on Windows
*
* @category File System
* @experimental
*/
export function umask(mask?: number): number;
/** **UNSTABLE**: New API, yet to be vetted.
*
* All plain number types for interfacing with foreign functions.
*
* @category FFI
* @experimental
*/
export type NativeNumberType =
| "u8"
| "i8"
| "u16"
| "i16"
| "u32"
| "i32"
| "f32"
| "f64";
/** **UNSTABLE**: New API, yet to be vetted.
*
* All BigInt number types for interfacing with foreign functions.
*
* @category FFI
* @experimental
*/
export type NativeBigIntType =
| "u64"
| "i64"
| "usize"
| "isize";
/** **UNSTABLE**: New API, yet to be vetted.
*
* The native boolean type for interfacing to foreign functions.
*
* @category FFI
* @experimental
*/
export type NativeBooleanType = "bool";
/** **UNSTABLE**: New API, yet to be vetted.
*
* The native pointer type for interfacing to foreign functions.
*
* @category FFI
* @experimental
*/
export type NativePointerType = "pointer";
/** **UNSTABLE**: New API, yet to be vetted.
*
* The native buffer type for interfacing to foreign functions.
*
* @category FFI
* @experimental
*/
export type NativeBufferType = "buffer";
/** **UNSTABLE**: New API, yet to be vetted.
*
* The native function type for interfacing with foreign functions.
*
* @category FFI
* @experimental
*/
export type NativeFunctionType = "function";
/** **UNSTABLE**: New API, yet to be vetted.
*
* The native void type for interfacing with foreign functions.
*
* @category FFI
* @experimental
*/
export type NativeVoidType = "void";
/** **UNSTABLE**: New API, yet to be vetted.
*
* The native struct type for interfacing with foreign functions.
*
* @category FFI
* @experimental
*/
export type NativeStructType = { readonly struct: readonly NativeType[] };
/**
* @category FFI
* @experimental
*/
export const brand: unique symbol;
/**
* @category FFI
* @experimental
*/
export type NativeU8Enum<T extends number> = "u8" & { [brand]: T };
/**
* @category FFI
* @experimental
*/
export type NativeI8Enum<T extends number> = "i8" & { [brand]: T };
/**
* @category FFI
* @experimental
*/
export type NativeU16Enum<T extends number> = "u16" & { [brand]: T };
/**
* @category FFI
* @experimental
*/
export type NativeI16Enum<T extends number> = "i16" & { [brand]: T };
/**
* @category FFI
* @experimental
*/
export type NativeU32Enum<T extends number> = "u32" & { [brand]: T };
/**
* @category FFI
* @experimental
*/
export type NativeI32Enum<T extends number> = "i32" & { [brand]: T };
/**
* @category FFI
* @experimental
*/
export type NativeTypedPointer<T extends PointerObject> = "pointer" & {
[brand]: T;
};
/**
* @category FFI
* @experimental
*/
export type NativeTypedFunction<T extends UnsafeCallbackDefinition> =
& "function"
& {
[brand]: T;
};
/** **UNSTABLE**: New API, yet to be vetted.
*
* All supported types for interfacing with foreign functions.
*
* @category FFI
* @experimental
*/
export type NativeType =
| NativeNumberType
| NativeBigIntType
| NativeBooleanType
| NativePointerType
| NativeBufferType
| NativeFunctionType
| NativeStructType;
/** **UNSTABLE**: New API, yet to be vetted.
*
* @category FFI
* @experimental
*/
export type NativeResultType = NativeType | NativeVoidType;
/** **UNSTABLE**: New API, yet to be vetted.
*
* Type conversion for foreign symbol parameters and unsafe callback return
* types.
*
* @category FFI
* @experimental
*/
export type ToNativeType<T extends NativeType = NativeType> = T extends
NativeStructType ? BufferSource
: 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 ? 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;
/** **UNSTABLE**: New API, yet to be vetted.
*
* Type conversion for unsafe callback return types.
*
* @category FFI
* @experimental
*/
export type ToNativeResultType<
T extends NativeResultType = NativeResultType,
> = T extends NativeStructType ? BufferSource
: 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 ? 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;
/** **UNSTABLE**: New API, yet to be vetted.
*
* A utility type for conversion of parameter types of foreign functions.
*
* @category FFI
* @experimental
*/
export 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]>;
}
: never;
/** **UNSTABLE**: New API, yet to be vetted.
*
* Type conversion for foreign symbol return types and unsafe callback
* parameters.
*
* @category FFI
* @experimental
*/
export type FromNativeType<T extends NativeType = NativeType> = T extends
NativeStructType ? Uint8Array
: 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 ? 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;
/** **UNSTABLE**: New API, yet to be vetted.
*
* Type conversion for foreign symbol return types.
*
* @category FFI
* @experimental
*/
export type FromNativeResultType<
T extends NativeResultType = NativeResultType,
> = T extends NativeStructType ? Uint8Array
: 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 ? 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;
/** **UNSTABLE**: New API, yet to be vetted.
*
* @category FFI
* @experimental
*/
export 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]>;
}
: never;
/** **UNSTABLE**: New API, yet to be vetted.
*
* The interface for a foreign function as defined by its parameter and result
* types.
*
* @category FFI
* @experimental
*/
export interface ForeignFunction<
Parameters extends readonly NativeType[] = readonly NativeType[],
Result extends NativeResultType = NativeResultType,
NonBlocking extends boolean = boolean,
> {
/** Name of the symbol.
*
* Defaults to the key name in symbols object. */
name?: string;
/** The parameters of the foreign function. */
parameters: Parameters;
/** The result (return value) of the foreign function. */
result: Result;
/** When `true`, function calls will run on a dedicated blocking thread and
* will return a `Promise` resolving to the `result`. */
nonblocking?: NonBlocking;
/** When `true`, dlopen will not fail if the symbol is not found.
* Instead, the symbol will be set to `null`.
*
* @default {false} */
optional?: boolean;
}
/** **UNSTABLE**: New API, yet to be vetted.
*
* @category FFI
* @experimental
*/
export interface ForeignStatic<Type extends NativeType = NativeType> {
/** Name of the symbol, defaults to the key name in symbols object. */
name?: string;
/** The type of the foreign static value. */
type: Type;
/** When `true`, dlopen will not fail if the symbol is not found.
* Instead, the symbol will be set to `null`.
*
* @default {false} */
optional?: boolean;
}
/** **UNSTABLE**: New API, yet to be vetted.
*
* A foreign library interface descriptor.
*
* @category FFI
* @experimental
*/
export interface ForeignLibraryInterface {
[name: string]: ForeignFunction | ForeignStatic;
}
/** **UNSTABLE**: New API, yet to be vetted.
*
* A utility type that infers a foreign symbol.
*
* @category FFI
* @experimental
*/
export type StaticForeignSymbol<T extends ForeignFunction | ForeignStatic> =
T extends ForeignFunction ? FromForeignFunction<T>
: T extends ForeignStatic ? FromNativeType<T["type"]>
: never;
/** **UNSTABLE**: New API, yet to be vetted.
*
* @category FFI
* @experimental
*/
export type FromForeignFunction<T extends ForeignFunction> =
T["parameters"] extends readonly [] ? () => StaticForeignSymbolReturnType<T>
: (
...args: ToNativeParameterTypes<T["parameters"]>
) => StaticForeignSymbolReturnType<T>;
/** **UNSTABLE**: New API, yet to be vetted.
*
* @category FFI
* @experimental
*/
export type StaticForeignSymbolReturnType<T extends ForeignFunction> =
ConditionalAsync<T["nonblocking"], FromNativeResultType<T["result"]>>;
/** **UNSTABLE**: New API, yet to be vetted.
*
* @category FFI
* @experimental
*/
export type ConditionalAsync<IsAsync extends boolean | undefined, T> =
IsAsync extends true ? Promise<T> : T;
/** **UNSTABLE**: New API, yet to be vetted.
*
* A utility type that infers a foreign library interface.
*
* @category FFI
* @experimental
*/
export type StaticForeignLibraryInterface<T extends ForeignLibraryInterface> =
{
[K in keyof T]: T[K]["optional"] extends true
? StaticForeignSymbol<T[K]> | null
: StaticForeignSymbol<T[K]>;
};
/** **UNSTABLE**: New API, yet to be vetted.
*
* A non-null pointer, represented as an object
* at runtime. The object's prototype is `null`
* and cannot be changed. The object cannot be
* assigned to either and is thus entirely read-only.
*
* To interact with memory through a pointer use the
* {@linkcode UnsafePointerView} class. To create a
* pointer from an address or the get the address of
* a pointer use the static methods of the
* {@linkcode UnsafePointer} class.
*
* @category FFI
* @experimental
*/
export type PointerObject<T = unknown> = { [brand]: T };
/** **UNSTABLE**: New API, yet to be vetted.
*
* Pointers are represented either with a {@linkcode PointerObject}
* object or a `null` if the pointer is null.
*
* @category FFI
* @experimental
*/
export type PointerValue<T = unknown> = null | PointerObject<T>;
/** **UNSTABLE**: New API, yet to be vetted.
*
* A collection of static functions for interacting with pointer objects.
*
* @category FFI
* @experimental
*/
export class UnsafePointer {
/** Create a pointer from a numeric value. This one is <i>really</i> dangerous! */
static create<T = unknown>(value: bigint): PointerValue<T>;
/** Returns `true` if the two pointers point to the same address. */
static equals<T = unknown>(a: PointerValue<T>, b: PointerValue<T>): boolean;
/** Return the direct memory pointer to the typed array in memory. */
static of<T = unknown>(
value: Deno.UnsafeCallback | BufferSource,
): PointerValue<T>;
/** Return a new pointer offset from the original by `offset` bytes. */
static offset<T = unknown>(
value: PointerObject,
offset: number,
): PointerValue<T>;
/** Get the numeric value of a pointer */
static value(value: PointerValue): bigint;
}
/** **UNSTABLE**: New API, yet to be vetted.
*
* An unsafe pointer view to a memory location as specified by the `pointer`
* value. The `UnsafePointerView` API follows the standard built in interface
* {@linkcode DataView} for accessing the underlying types at an memory
* location (numbers, strings and raw bytes).
*
* @category FFI
* @experimental
*/
export class UnsafePointerView {
constructor(pointer: PointerObject);
pointer: PointerObject;
/** Gets a boolean at the specified byte offset from the pointer. */
getBool(offset?: number): boolean;
/** Gets an unsigned 8-bit integer at the specified byte offset from the
* pointer. */
getUint8(offset?: number): number;
/** Gets a signed 8-bit integer at the specified byte offset from the
* pointer. */
getInt8(offset?: number): number;
/** Gets an unsigned 16-bit integer at the specified byte offset from the
* pointer. */
getUint16(offset?: number): number;
/** Gets a signed 16-bit integer at the specified byte offset from the
* pointer. */
getInt16(offset?: number): number;
/** Gets an unsigned 32-bit integer at the specified byte offset from the
* pointer. */
getUint32(offset?: number): number;
/** Gets a signed 32-bit integer at the specified byte offset from the
* pointer. */
getInt32(offset?: number): number;
/** Gets an unsigned 64-bit integer at the specified byte offset from the
* pointer. */
getBigUint64(offset?: number): bigint;
/** Gets a signed 64-bit integer at the specified byte offset from the
* pointer. */
getBigInt64(offset?: number): bigint;
/** Gets a signed 32-bit float at the specified byte offset from the
* pointer. */
getFloat32(offset?: number): number;
/** Gets a signed 64-bit float at the specified byte offset from the
* pointer. */
getFloat64(offset?: number): number;
/** Gets a pointer at the specified byte offset from the pointer */
getPointer<T = unknown>(offset?: number): PointerValue<T>;
/** Gets a C string (`null` terminated string) at the specified byte offset
* from the pointer. */
getCString(offset?: number): string;
/** Gets a C string (`null` terminated string) at the specified byte offset
* from the specified pointer. */
static getCString(
pointer: PointerObject,
offset?: number,
): string;
/** Gets an `ArrayBuffer` of length `byteLength` at the specified byte
* offset from the pointer. */
getArrayBuffer(byteLength: number, offset?: number): ArrayBuffer;
/** Gets an `ArrayBuffer` of length `byteLength` at the specified byte
* offset from the specified pointer. */
static getArrayBuffer(
pointer: PointerObject,
byteLength: number,
offset?: number,
): ArrayBuffer;
/** Copies the memory of the pointer into a typed array.
*
* Length is determined from the typed array's `byteLength`.
*
* Also takes optional byte offset from the pointer. */
copyInto(destination: BufferSource, offset?: number): void;
/** Copies the memory of the specified pointer into a typed array.
*
* Length is determined from the typed array's `byteLength`.
*
* Also takes optional byte offset from the pointer. */
static copyInto(
pointer: PointerObject,
destination: BufferSource,
offset?: number,
): void;
}
/** **UNSTABLE**: New API, yet to be vetted.
*
* An unsafe pointer to a function, for calling functions that are not present
* as symbols.
*
* @category FFI
* @experimental
*/
export class UnsafeFnPointer<const Fn extends ForeignFunction> {
/** The pointer to the function. */
pointer: PointerObject<Fn>;
/** The definition of the function. */
definition: Fn;
constructor(pointer: PointerObject<NoInfer<Fn>>, definition: Fn);
/** @deprecated Properly type {@linkcode pointer} using {@linkcode NativeTypedFunction} or {@linkcode UnsafeCallbackDefinition} types. */
constructor(pointer: PointerObject, definition: Fn);
/** Call the foreign function. */
call: FromForeignFunction<Fn>;
}
/** **UNSTABLE**: New API, yet to be vetted.
*
* Definition of a unsafe callback function.
*
* @category FFI
* @experimental
*/
export interface UnsafeCallbackDefinition<
Parameters extends readonly NativeType[] = readonly NativeType[],
Result extends NativeResultType = NativeResultType,
> {
/** The parameters of the callbacks. */
parameters: Parameters;
/** The current result of the callback. */
result: Result;
}
/** **UNSTABLE**: New API, yet to be vetted.
*
* An unsafe callback function.
*
* @category FFI
* @experimental
*/
export type UnsafeCallbackFunction<
Parameters extends readonly NativeType[] = readonly NativeType[],
Result extends NativeResultType = NativeResultType,
> = Parameters extends readonly [] ? () => ToNativeResultType<Result> : (
...args: FromNativeParameterTypes<Parameters>
) => ToNativeResultType<Result>;
/** **UNSTABLE**: New API, yet to be vetted.
*
* An unsafe function pointer for passing JavaScript functions as C function
* pointers to foreign function calls.
*
* The function pointer remains valid until the `close()` method is called.
*
* All `UnsafeCallback` are always thread safe in that they can be called from
* foreign threads without crashing. However, they do not wake up the Deno event
* loop by default.
*
* If a callback is to be called from foreign threads, use the `threadSafe()`
* static constructor or explicitly call `ref()` to have the callback wake up
* the Deno event loop when called from foreign threads. This also stops
* Deno's process from exiting while the callback still exists and is not
* unref'ed.
*
* Use `deref()` to then allow Deno's process to exit. Calling `deref()` on
* a ref'ed callback does not stop it from waking up the Deno event loop when
* called from foreign threads.
*
* @category FFI
* @experimental
*/
export class UnsafeCallback<
const Definition extends UnsafeCallbackDefinition =
UnsafeCallbackDefinition,
> {
constructor(
definition: Definition,
callback: UnsafeCallbackFunction<
Definition["parameters"],
Definition["result"]
>,
);
/** The pointer to the unsafe callback. */
readonly pointer: PointerObject<Definition>;
/** The definition of the unsafe callback. */
readonly definition: Definition;
/** The callback function. */
readonly callback: UnsafeCallbackFunction<
Definition["parameters"],
Definition["result"]
>;
/**
* Creates an {@linkcode UnsafeCallback} and calls `ref()` once to allow it to
* wake up the Deno event loop when called from foreign threads.
*
* This also stops Deno's process from exiting while the callback still
* exists and is not unref'ed.
*/
static threadSafe<
Definition extends UnsafeCallbackDefinition = UnsafeCallbackDefinition,
>(
definition: Definition,
callback: UnsafeCallbackFunction<
Definition["parameters"],
Definition["result"]
>,
): UnsafeCallback<Definition>;
/**
* Increments the callback's reference counting and returns the new
* reference count.
*
* After `ref()` has been called, the callback always wakes up the
* Deno event loop when called from foreign threads.
*
* If the callback's reference count is non-zero, it keeps Deno's
* process from exiting.
*/
ref(): number;
/**
* Decrements the callback's reference counting and returns the new
* reference count.
*
* Calling `unref()` does not stop a callback from waking up the Deno
* event loop when called from foreign threads.
*
* If the callback's reference counter is zero, it no longer keeps
* Deno's process from exiting.
*/
unref(): number;
/**
* Removes the C function pointer associated with this instance.
*
* Continuing to use the instance or the C function pointer after closing
* the `UnsafeCallback` will lead to errors and crashes.
*
* Calling this method sets the callback's reference counting to zero,
* stops the callback from waking up the Deno event loop when called from
* foreign threads and no longer keeps Deno's process from exiting.
*/
close(): void;
}
/** **UNSTABLE**: New API, yet to be vetted.
*
* A dynamic library resource. Use {@linkcode Deno.dlopen} to load a dynamic
* library and return this interface.
*
* @category FFI
* @experimental
*/
export interface DynamicLibrary<S extends ForeignLibraryInterface> {
/** All of the registered library along with functions for calling them. */
symbols: StaticForeignLibraryInterface<S>;
/** Removes the pointers associated with the library symbols.
*
* Continuing to use symbols that are part of the library will lead to
* errors and crashes.
*
* Calling this method will also immediately set any references to zero and
* will no longer keep Deno's process from exiting.
*/
close(): void;
}
/** **UNSTABLE**: New API, yet to be vetted.
*
* Opens an external dynamic library and registers symbols, making foreign
* functions available to be called.
*
* Requires `allow-ffi` permission. Loading foreign dynamic libraries can in
* theory bypass all of the sandbox permissions. While it is a separate
* permission users should acknowledge in practice that is effectively the
* same as running with the `allow-all` permission.
*
* @example Given a C library which exports a foreign function named `add()`
*
* ```ts
* // Determine library extension based on
* // your OS.
* let libSuffix = "";
* switch (Deno.build.os) {
* case "windows":
* libSuffix = "dll";
* break;
* case "darwin":
* libSuffix = "dylib";
* break;
* default:
* libSuffix = "so";
* break;
* }
*
* const libName = `./libadd.${libSuffix}`;
* // Open library and define exported symbols
* const dylib = Deno.dlopen(
* libName,
* {
* "add": { parameters: ["isize", "isize"], result: "isize" },
* } as const,
* );
*
* // Call the symbol `add`
* const result = dylib.symbols.add(35n, 34n); // 69n
*
* console.log(`Result from external addition of 35 and 34: ${result}`);
* ```
*
* @tags allow-ffi
* @category FFI
* @experimental
*/
export function dlopen<const S extends ForeignLibraryInterface>(
filename: string | URL,
symbols: S,
): DynamicLibrary<S>;
/** **UNSTABLE**: New API, yet to be vetted.
*
* Creates a presentable WebGPU surface from given window and

691
cli/tsc/dts/lib.deno_webgpu.d.ts vendored
View file

File diff suppressed because it is too large Load diff

20
tests/integration/lsp_tests.rs
View file

@ -2143,7 +2143,7 @@ fn lsp_hover_unstable_always_enabled() {
"version": 1,
// IMPORTANT: If you change this API due to stabilization, also change it
// in the enabled test below.
"text": "type _ = Deno.ForeignLibraryInterface;\n"
"text": "type _ = Deno.DatagramConn;\n"
}
}));
let res = client.write_request(
@ -2161,14 +2161,14 @@ fn lsp_hover_unstable_always_enabled() {
"contents":[
{
"language":"typescript",
"value":"interface Deno.ForeignLibraryInterface"
"value":"interface Deno.DatagramConn"
},
"**UNSTABLE**: New API, yet to be vetted.\n\nA foreign library interface descriptor.",
"\n\n*@category* - FFI \n\n*@experimental*",
"**UNSTABLE**: New API, yet to be vetted.\n\nA generic transport listener for message-oriented protocols.",
"\n\n*@category* - Network \n\n*@experimental*",
],
"range":{
"start":{ "line":0, "character":14 },
"end":{ "line":0, "character":37 }
"end":{ "line":0, "character":26 }
}
})
);
@ -2188,7 +2188,7 @@ fn lsp_hover_unstable_enabled() {
"uri": "file:///a/file.ts",
"languageId": "typescript",
"version": 1,
"text": "type _ = Deno.ForeignLibraryInterface;\n"
"text": "type _ = Deno.DatagramConn;\n"
}
}));
let res = client.write_request(
@ -2206,14 +2206,14 @@ fn lsp_hover_unstable_enabled() {
"contents":[
{
"language":"typescript",
"value":"interface Deno.ForeignLibraryInterface"
"value":"interface Deno.DatagramConn"
},
"**UNSTABLE**: New API, yet to be vetted.\n\nA foreign library interface descriptor.",
"\n\n*@category* - FFI \n\n*@experimental*",
"**UNSTABLE**: New API, yet to be vetted.\n\nA generic transport listener for message-oriented protocols.",
"\n\n*@category* - Network \n\n*@experimental*",
],
"range":{
"start":{ "line":0, "character":14 },
"end":{ "line":0, "character":37 }
"end":{ "line":0, "character":26 }
}
})
);

11
tests/specs/check/unstable_suggestion/main.out
View file

@ -1,10 +1,5 @@
Check file:///[WILDLINE]main.ts
error: TS2551 [ERROR]: Property 'dlopen' does not exist on type 'typeof Deno'. Did you mean 'open'? 'Deno.dlopen' is an unstable API. Did you mean 'open'? If not, try changing the 'lib' compiler option to include 'deno.unstable' or add a triple-slash directive to the top of your entrypoint (main file): /// <reference lib="deno.unstable" />
Deno.dlopen("path/to/lib", {});
~~~~~~
error: TS2339 [ERROR]: Property 'listenDatagram' does not exist on type 'typeof Deno'. 'Deno.listenDatagram' is an unstable API. If not, try changing the 'lib' compiler option to include 'deno.unstable' or add a triple-slash directive to the top of your entrypoint (main file): /// <reference lib="deno.unstable" />
Deno.listenDatagram({
~~~~~~~~~~~~~~
at file:///[WILDLINE]/main.ts:5:6
'open' is declared here.
export function open(
~~~~
at asset:///lib.deno.ns.d.ts:[WILDLINE]

5
tests/specs/check/unstable_suggestion/main.ts
View file

@ -2,4 +2,7 @@
/// <reference lib="deno.ns" />
// unstable apis removed here, so should error
Deno.dlopen("path/to/lib", {});
Deno.listenDatagram({
port: 3000,
transport: "udp",
});

2
tools/jsdoc_checker.js
View file

@ -17,11 +17,11 @@ const libs = [
join(ROOT_PATH, "cli/tsc/dts/lib.deno.ns.d.ts"),
join(ROOT_PATH, "cli/tsc/dts/lib.deno.shared_globals.d.ts"),
join(ROOT_PATH, "cli/tsc/dts/lib.deno.window.d.ts"),
join(ROOT_PATH, "cli/tsc/dts/lib.deno_webgpu.d.ts"),
];
const unstableLibs = [
join(ROOT_PATH, "ext/broadcast_channel/lib.deno_broadcast_channel.d.ts"),
join(ROOT_PATH, "cli/tsc/dts/lib.deno_webgpu.d.ts"),
join(ROOT_PATH, "cli/tsc/dts/lib.deno.unstable.d.ts"),
];