Repository: TypeScript
Issue: Design Meeting Notes, 8/27/2024
Labels: Design Notes


# Parameterizing `TypedArray`s

https://github.com/microsoft/TypeScript/pull/58573

* We didn't get the chance to add the es2024 target 
* `ArrayBuffer` got new members that `SharedArrayBuffer` does not have.
* Previously, `SharedArrayBuffer` just had two members apart from `byteLength` and `slice`, making them interchangeable.
* es2024 has new members for each of these.
    * Proposed changes make them no longer interchangeable.
    * `ArrayBufferLike` is the best type to describe both.
* Why?
    * The WebCrypto APIs only allow `ArrayBuffer`, and not `SharedArrayBuffer`,
        * e.g. `crypto.subtle.digest`
    * Also, `ArrayBuffer` is not a transferable object.
* Makes it hard when you try to get the underlying buffer via `someUint8Array.buffer`.
* What is the underlying idea of how these compose?
    * `ArrayBuffer` is a non-indexable span of memory. You use an "ArrayBuffer view" to access the memory.
        * They're not thread-safe. They're only meant to be read/written from within a single thread. If you want to share memory, you either copy the memory or transfer it entirely.
    * `SharedArrayBuffer` looks like an `ArrayBuffer` but operates over memory in a shared global heap and has has unordered but sequentially consistent writes.
* So the idea is to parameterize each of these views over the underlying buffer type.

  ```ts
  interface Uint8Array<Buffer extends ArrayBufferLike = ArrayBufferLike> {
    // ...
    readonly buffer: Buffer;


    // Most methods and constructors return a view with a local-only ArrayBuffer
    new (length: number): Uint8Array<ArrayBuffer>;

    // (not this one)
    new <T extends ArrayBufferLike>(buffer: T, byteOffset?: number, length?: number): Uint8Array<T>;
    
    new (array: ArrayLike<number> | ArrayBuffer): Uint8Array<ArrayBuffer>;
    // ...
    filter(predicate: /*...*/): Uint8Array<ArrayBuffer>;
  }
  ```
    * **Note the above code is roughly transcribed, don't look at this as precise.**
* Problems:
    * `Buffer` subtypes `Uint8Array`.
        * We say if you extend a base type, that base type has to have a consistent construct signature.
        * Would have to make `Buffer` generic - and to do that, we would have to start using `typesVersions` because old `UInt8Array` aren't generic.
            * Workaround: just change the returned type to `Buffer & WithArrayBufferLike<...>` in the retun types of `slice` and `subarray`.
            * Why not just forward-declare `UInt8Array` as generic with an option type parameter?
    * Also, return `this` in some cases.
* What if we fixed up stuff like `crypto.subtle.digest` etc. to accept `SharedArrayBuffer` even though they don't take those?
    * Fixes the DOM, but doesn't fix everything.
* Could say the underlying default should be `ArrayBuffer`, not `ArrayBufferLike`.
    * We created `ArrayBufferLike` and traditionally these have never had a noticeable difference.

# File Extension Rewriting, `--experimental-transform-types`/`--experimental-strip-types`, and Multi-Project Builds

https://github.com/microsoft/TypeScript/pull/59767

* Last week, we discussed rewriting relative file extensions. Had concerns, mainly around monorepo-style codebases.
* In the meantime, we have a prototype PR.
* Sample project

  ```ts
  // packages/lib/src/math.ts
  export function add(a: number, b: number) {
    return a + b;
  }

  // packages/lib/src/main.ts
  export * from "./math.ts";

  // packages/app/src/main.ts
  import { add } from "@typescript-node/lib";

  console.log(add(1, 2));
  ```
* By default doesn't, work, but...

  ```json5
  {
    // ...

    "exports": {
        ".": {
            "typescript": "./src/main.ts",
            "import": "./dist/main.js",
        }
    }
  }
  ```
    * Works when you run with `node --conditions typescript`.
* Almost right, but it's not safe to publish TypeScript - if this `exports` map was published to npm and run with `node --conditions typescript`, resolution would fail within the published package.
* One way is to erase here - but no built-in tooling to do this.
* @colinhacks suggested namespacing on a per-package basis for publishing.

  ```json5
  {
    // ...

    "exports": {
        ".": {
            "@my-special-namespace/source": "./src/main.ts",
            "import": "./dist/main.js",
        }
    }
  }
  ```
    * Can also erase these, but not sure what tools do that.
* `moduleSuffixes`
    * Nothing special needed there, but you can't really take advantage of extension rewriting in certain circumstances.
        * You can't name something `foo.ts.android.ts`, but you also can't write `foo.ts.ts` anyway.
        * Probably will be very rare - this is mainly for React Native, and frankly really unhinged to do this.
* Now what if projects don't take advantage of workspaces and just do a direct relative import?
* `import { add as _add } from "../../lib/src/main.ts`
    * Won't work if `outDir` is `dist` because it needs to be rewritten to `../../lib/dist/main.ts`.
    * It just doesn't work in some circumstances and we can give an error there.
* You still *can* use relative imports - everything just needs to end up in the same output folder. This is, for example, how TypeScript's build works! So even we could do this.
* For clarity: relative imports work for the following...

  ```
  root/
  ├── src/
  │   ├── projA/
  │   ├── projB/
  │   └── projC/
  └── dist/
      ├── projA/
      ├── projB/
      └── projC/
  ```

  but relative imports *do not* work for the following.

  ```
  projects/
  ├── projA/
  │   ├── src/
  │   └── dist/
  ├── projB/
  │   ├── src/
  │   └── dist/
  └── projC/
      ├── src/
      └── dist/
  ```
* Sample PR to arethetypeswrong that makes everything work with `--experimental-transform-types`: https://github.com/arethetypeswrong/arethetypeswrong.github.io/pull/194
    * Notable interesting details:
        * Tests that can work against both the TS source and JS output! One just passes a specific `--conditions`.
        * Thought you needed tsconfig custom `conditions`- but you don't. TypeScript's project references are smart enough to map output files to input files.
        * Did a regex replace on relative paths - got one wrong in `#internal/getProbableExports.js` to `#internal/getProbableExports`.
            * Reinforced the need for good errors.
* What would all this look like without project references?
    * Like one big `tsconfig.json`?
        * Not necessarily.
    * *Probably* works, just need to break things apart by packages and can't use relative paths.
* Should Node automatically have a condition?
    * Interesting long-term, but maybe it's good for people to have a specific level of control.
* Boilerplate-y to have to write `--conditions @my-namespace/source` and `@my-namespace/source` throughout `exports`/`imports`, but probably worth the control.
    * It's not just boilerplate though, it's more about not having all these conditions published, and not exposing this to users. Really would be ideal if these conditions could be automatically erased before publishing.
* otherwise, we feel good about this. It's not 0-config throughout, but it feels like there is a story between the "I can start a Node server fast" and "I can break my projects apart into multiple pieces"/"I want to publish stuff to npm" that we feel good about.