diff --git a/cli/tsc/dts/lib.deno.unstable.d.ts b/cli/tsc/dts/lib.deno.unstable.d.ts index 70b346a2a7..6a6d6c8367 100644 --- a/cli/tsc/dts/lib.deno.unstable.d.ts +++ b/cli/tsc/dts/lib.deno.unstable.d.ts @@ -103,6 +103,31 @@ declare namespace Deno { */ type NativeStructType = { readonly struct: readonly NativeType[] }; + /** @category FFI */ + const brand: unique symbol; + + /** @category FFI */ + export type NativeU8Enum = "u8" & { [brand]: T }; + /** @category FFI */ + export type NativeI8Enum = "i8" & { [brand]: T }; + /** @category FFI */ + export type NativeU16Enum = "u16" & { [brand]: T }; + /** @category FFI */ + export type NativeI16Enum = "i16" & { [brand]: T }; + /** @category FFI */ + export type NativeU32Enum = "u32" & { [brand]: T }; + /** @category FFI */ + export type NativeI32Enum = "i32" & { [brand]: T }; + /** @category FFI */ + export type NativeTypedPointer = "pointer" & { + [brand]: T; + }; + export type NativeTypedFunction = + & "function" + & { + [brand]: T; + }; + /** **UNSTABLE**: New API, yet to be vetted. * * All supported types for interfacing with foreign functions. @@ -124,21 +149,6 @@ declare namespace Deno { */ export type NativeResultType = NativeType | NativeVoidType; - /** **UNSTABLE**: New API, yet to be vetted. - * - * A utility type conversion for foreign symbol parameters and unsafe callback - * return types. - * - * @category FFI - */ - type ToNativeTypeMap = - & Record - & Record - & Record - & Record - & Record - & Record; - /** **UNSTABLE**: New API, yet to be vetted. * * Type conversion for foreign symbol parameters and unsafe callback return @@ -148,15 +158,22 @@ declare namespace Deno { */ type ToNativeType = T extends NativeStructType ? BufferSource - : ToNativeTypeMap[Exclude]; - - /** **UNSTABLE**: New API, yet to be vetted. - * - * A utility type for conversion for unsafe callback return types. - * - * @category FFI - */ - type ToNativeResultTypeMap = ToNativeTypeMap & Record; + : T extends NativeNumberType ? T extends NativeU8Enum ? U + : T extends NativeI8Enum ? U + : T extends NativeU16Enum ? U + : T extends NativeI16Enum ? U + : T extends NativeU32Enum ? U + : T extends NativeI32Enum ? U + : number + : T extends NativeBigIntType ? number | bigint + : T extends NativeBooleanType ? boolean + : T extends NativePointerType + ? T extends NativeTypedPointer ? U | null : PointerValue + : T extends NativeFunctionType + ? T extends NativeTypedFunction ? PointerValue | null + : PointerValue + : T extends NativeBufferType ? BufferSource | null + : never; /** **UNSTABLE**: New API, yet to be vetted. * @@ -166,7 +183,23 @@ declare namespace Deno { */ type ToNativeResultType = T extends NativeStructType ? BufferSource - : ToNativeResultTypeMap[Exclude]; + : T extends NativeNumberType ? T extends NativeU8Enum ? U + : T extends NativeI8Enum ? U + : T extends NativeU16Enum ? U + : T extends NativeI16Enum ? U + : T extends NativeU32Enum ? U + : T extends NativeI32Enum ? U + : number + : T extends NativeBigIntType ? number | bigint + : T extends NativeBooleanType ? boolean + : T extends NativePointerType + ? T extends NativeTypedPointer ? U | null : PointerValue + : T extends NativeFunctionType + ? T extends NativeTypedFunction ? PointerObject | null + : PointerValue + : T extends NativeBufferType ? BufferSource | null + : T extends NativeVoidType ? void + : never; /** **UNSTABLE**: New API, yet to be vetted. * @@ -184,21 +217,6 @@ declare namespace Deno { } : never; - /** **UNSTABLE**: New API, yet to be vetted. - * - * A utility type for conversion of foreign symbol return types and unsafe - * callback parameters. - * - * @category FFI - */ - type FromNativeTypeMap = - & Record - & Record - & Record - & Record - & Record - & Record; - /** **UNSTABLE**: New API, yet to be vetted. * * Type conversion for foreign symbol return types and unsafe callback @@ -208,17 +226,22 @@ declare namespace Deno { */ type FromNativeType = T extends NativeStructType ? Uint8Array - : FromNativeTypeMap[Exclude]; - - /** **UNSTABLE**: New API, yet to be vetted. - * - * A utility type for conversion for foreign symbol return types. - * - * @category FFI - */ - type FromNativeResultTypeMap = - & FromNativeTypeMap - & Record; + : T extends NativeNumberType ? T extends NativeU8Enum ? U + : T extends NativeI8Enum ? U + : T extends NativeU16Enum ? U + : T extends NativeI16Enum ? U + : T extends NativeU32Enum ? U + : T extends NativeI32Enum ? U + : number + : T extends NativeBigIntType ? number | bigint + : T extends NativeBooleanType ? boolean + : T extends NativePointerType + ? T extends NativeTypedPointer ? U | null : PointerValue + : T extends NativeBufferType ? PointerValue + : T extends NativeFunctionType + ? T extends NativeTypedFunction ? PointerObject | null + : PointerValue + : never; /** **UNSTABLE**: New API, yet to be vetted. * @@ -228,7 +251,23 @@ declare namespace Deno { */ type FromNativeResultType = T extends NativeStructType ? Uint8Array - : FromNativeResultTypeMap[Exclude]; + : T extends NativeNumberType ? T extends NativeU8Enum ? U + : T extends NativeI8Enum ? U + : T extends NativeU16Enum ? U + : T extends NativeI16Enum ? U + : T extends NativeU32Enum ? U + : T extends NativeI32Enum ? U + : number + : T extends NativeBigIntType ? number | bigint + : T extends NativeBooleanType ? boolean + : T extends NativePointerType + ? T extends NativeTypedPointer ? U | null : PointerValue + : T extends NativeBufferType ? PointerValue + : T extends NativeFunctionType + ? T extends NativeTypedFunction ? PointerObject | null + : PointerValue + : T extends NativeVoidType ? void + : never; /** **UNSTABLE**: New API, yet to be vetted. * @@ -354,42 +393,52 @@ declare namespace Deno { : StaticForeignSymbol; }; - /** @category FFI */ - const brand: unique symbol; - /** @category FFI */ - type PointerObject = { [brand]: unknown }; - /** **UNSTABLE**: New API, yet to be vetted. * - * Pointer type depends on the architecture and actual pointer value. + * 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. * - * On a 32 bit host system all pointer values are plain numbers. On a 64 bit - * host system pointer values are represented as numbers if the value is below - * `Number.MAX_SAFE_INTEGER`, otherwise they are provided as bigints. + * 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 PointerValue = null | PointerObject; + export type PointerObject = { [brand]: T }; /** **UNSTABLE**: New API, yet to be vetted. * - * An unsafe pointer to a memory location for passing and returning pointers - * to and from the FFI. + * Pointers are represented either with a {@linkcode PointerObject} + * object or a `null` if the pointer is null. + * + * @category FFI + */ + export type PointerValue = null | PointerObject; + + /** **UNSTABLE**: New API, yet to be vetted. + * + * 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 really dangerous! */ - static create(value: number | bigint): PointerValue; + static create(value: number | bigint): PointerValue; /** Returns `true` if the two pointers point to the same address. */ - static equals(a: PointerValue, b: PointerValue): boolean; + static equals(a: PointerValue, b: PointerValue): boolean; /** Return the direct memory pointer to the typed array in memory. */ - static of(value: Deno.UnsafeCallback | BufferSource): PointerValue; + static of( + value: Deno.UnsafeCallback | BufferSource, + ): PointerValue; /** Return a new pointer offset from the original by `offset` bytes. */ - static offset( - value: NonNullable, + static offset( + value: PointerObject, offset: number, - ): PointerValue; + ): PointerValue; /** Get the numeric value of a pointer */ static value(value: PointerValue): number | bigint; } @@ -404,9 +453,9 @@ declare namespace Deno { * @category FFI */ export class UnsafePointerView { - constructor(pointer: NonNullable); + constructor(pointer: PointerObject); - pointer: NonNullable; + pointer: PointerObject; /** Gets a boolean at the specified byte offset from the pointer. */ getBool(offset?: number): boolean; @@ -441,14 +490,14 @@ declare namespace Deno { * pointer. */ getFloat64(offset?: number): number; /** Gets a pointer at the specified byte offset from the pointer */ - getPointer(offset?: number): PointerValue; + getPointer(offset?: number): PointerValue; /** 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: NonNullable, + pointer: PointerObject, offset?: number, ): string; /** Gets an `ArrayBuffer` of length `byteLength` at the specified byte @@ -457,7 +506,7 @@ declare namespace Deno { /** Gets an `ArrayBuffer` of length `byteLength` at the specified byte * offset from the specified pointer. */ static getArrayBuffer( - pointer: NonNullable, + pointer: PointerObject, byteLength: number, offset?: number, ): ArrayBuffer; @@ -473,7 +522,7 @@ declare namespace Deno { * * Also takes optional byte offset from the pointer. */ static copyInto( - pointer: NonNullable, + pointer: PointerObject, destination: BufferSource, offset?: number, ): void; @@ -488,11 +537,13 @@ declare namespace Deno { */ export class UnsafeFnPointer { /** The pointer to the function. */ - pointer: NonNullable; + pointer: PointerObject; /** The definition of the function. */ definition: Fn; - constructor(pointer: NonNullable, definition: Const); + constructor(pointer: PointerObject, definition: Const); + /** @deprecated Properly type {@linkcode pointer} using {@linkcode NativeTypedFunction} or {@linkcode UnsafeCallbackDefinition} types. */ + constructor(pointer: PointerObject, definition: Const); /** Call the foreign function. */ call: FromForeignFunction; @@ -562,7 +613,7 @@ declare namespace Deno { ); /** The pointer to the unsafe callback. */ - readonly pointer: NonNullable; + readonly pointer: PointerObject; /** The definition of the unsafe callback. */ readonly definition: Definition; /** The callback function. */ diff --git a/test_ffi/tests/ffi_types.ts b/test_ffi/tests/ffi_types.ts index ff2a4fd5dc..485224da32 100644 --- a/test_ffi/tests/ffi_types.ts +++ b/test_ffi/tests/ffi_types.ts @@ -173,7 +173,7 @@ result4.then((_0: Deno.BufferSource) => {}); result4.then((_1: null | Deno.UnsafePointer) => {}); const fnptr = new Deno.UnsafeFnPointer( - {} as NonNullable, + {} as Deno.PointerObject, { parameters: ["u32", "pointer"], result: "void", @@ -358,6 +358,24 @@ type AssertNotEqual< $ = [Equal] extends [true] ? never : Expected, > = never; +const enum FooEnum { + Foo, + Bar, +} +const foo = "u8" as Deno.NativeU8Enum; + +declare const brand: unique symbol; +class MyPointerClass {} +type MyPointer = Deno.PointerObject & { [brand]: MyPointerClass }; +const myPointer = "pointer" as Deno.NativeTypedPointer; +type MyFunctionDefinition = Deno.UnsafeCallbackDefinition< + [typeof foo, "u32"], + typeof myPointer +>; +const myFunction = "function" as Deno.NativeTypedFunction< + MyFunctionDefinition +>; + type __Tests__ = [ empty: AssertEqual< { symbols: Record; close(): void }, @@ -442,4 +460,70 @@ type __Tests__ = [ { foo: { parameters: []; result: "i32" } } > >, + enum_param: AssertEqual< + { + symbols: { + foo: (arg: FooEnum) => void; + }; + close(): void; + }, + Deno.DynamicLibrary< + { foo: { parameters: [typeof foo]; result: "void" } } + > + >, + enum_return: AssertEqual< + { + symbols: { + foo: () => FooEnum; + }; + close(): void; + }, + Deno.DynamicLibrary< + { foo: { parameters: []; result: typeof foo } } + > + >, + typed_pointer_param: AssertEqual< + { + symbols: { + foo: (arg: MyPointer | null) => void; + }; + close(): void; + }, + Deno.DynamicLibrary< + { foo: { parameters: [typeof myPointer]; result: "void" } } + > + >, + typed_pointer_return: AssertEqual< + { + symbols: { + foo: () => MyPointer | null; + }; + close(): void; + }, + Deno.DynamicLibrary< + { foo: { parameters: []; result: typeof myPointer } } + > + >, + typed_function_param: AssertEqual< + { + symbols: { + foo: (arg: Deno.PointerObject | null) => void; + }; + close(): void; + }, + Deno.DynamicLibrary< + { foo: { parameters: [typeof myFunction]; result: "void" } } + > + >, + typed_function_return: AssertEqual< + { + symbols: { + foo: () => Deno.PointerObject | null; + }; + close(): void; + }, + Deno.DynamicLibrary< + { foo: { parameters: []; result: typeof myFunction } } + > + >, ];