TS errors when consuming butterfloat with `noUncheckedIndexedAccess` compiler option enabled.

[achou11]

I have a vite-based project that has the following tsconfig, which I consider to be pretty standard/reasonable for such apps:

{
	"compilerOptions": {
		"allowJs": true,
		"allowImportingTsExtensions": true,
		"erasableSyntaxOnly": true,
		"esModuleInterop": true,
		"incremental": true,
		"isolatedModules": true,
		"lib": ["es2022", "dom", "dom.iterable"],
		"module": "preserve",
		"moduleDetection": "force",
		"noEmit": true,
		"noImplicitOverride": true,
		"noUncheckedIndexedAccess": true,
		"resolveJsonModule": true,
		"skipLibCheck": true,
		"strict": true,
		"target": "es2022",
		"verbatimModuleSyntax": true,
		// Butterfloat-specific
		"jsx": "react",
		"jsxFactory": "jsx",
		"jsxFragmentFactory": "Fragment"
	},
	"include": ["**/*.js", "**/*.jsx", "**/*.ts", "**/*.tsx"],
	"exclude": ["node_modules", "dist"]
}

The only source code I have is this, which is extracted from the getting started page:

import { jsx, run } from 'butterfloat'

interface HelloProps {
  to: string
}

function Hello({ to }: HelloProps) {
  return <p className="hello">Hello {to}</p>
}

function Main() {
  return <Hello to="World" />
}

const container = document.getElementById('container')!
run(container, Main)

When running type checks i.e. tsc, I get the following errors:

node_modules/.pnpm/butterfloat@1.6.4/node_modules/butterfloat/static-dom.ts:28:36 - error TS2538: Type 'undefined' cannot be used as an index type.

28     let ns = context?.namespaceMap[nsAbbrev]
                                      ~~~~~~~~

node_modules/.pnpm/butterfloat@1.6.4/node_modules/butterfloat/static-dom.ts:43:34 - error TS2538: Type 'undefined' cannot be used as an index type.

43       ns = context?.namespaceMap[nsAbbrev]
                                    ~~~~~~~~

node_modules/.pnpm/butterfloat@1.6.4/node_modules/butterfloat/static-dom.ts:48:44 - error TS2769: No overload matches this call.
  The last overload gave the following error.
    Argument of type 'string | undefined' is not assignable to parameter of type 'string'.
      Type 'undefined' is not assignable to type 'string'.

48     element = document.createElementNS(ns, elementName)
                                              ~~~~~~~~~~~

  node_modules/.pnpm/typescript@5.9.3/node_modules/typescript/lib/lib.dom.d.ts:10148:5
    10148     createElementNS(namespace: string | null, qualifiedName: string, options?: string | ElementCreationOptions): Element;
              ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    The last overload is declared here.

node_modules/.pnpm/butterfloat@1.6.4/node_modules/butterfloat/static-dom.ts:70:42 - error TS2538: Type 'undefined' cannot be used as an index type.

70       const ns = context?.namespaceMap?.[nsAbbrev]
                                            ~~~~~~~~

node_modules/.pnpm/butterfloat@1.6.4/node_modules/butterfloat/static-dom.ts:74:34 - error TS2345: Argument of type 'string | undefined' is not assignable to parameter of type 'string'.
  Type 'undefined' is not assignable to type 'string'.

74       element.setAttributeNS(ns, attributeName, (value ?? '').toString())
                                    ~~~~~~~~~~~~~

If I remove the noUncheckedIndexedAccess option from my tsconfig, the errors go away. The errors actually make sense to me, but I'm a little surprised that TS is even complaining about them in the first place, given it's code that lives in a dependency. I would think my excludes configuration and the usage of skipLibCheck would tell TS not to do that. However, from a brief investigation, using skipLibCheck won't necessarily disable typechecking deps code (docs). From what I gathered, the fact that it is complaining about code in a dep apparently suggests a potential misconfiguration of the dep, although I could be mistaken about that.

There's a chance that this isn't an issue with butterfloat but it's the first time I've come across something like this where a compiler option that ideally is only relevant to my source code is complaining about a dep, which is not ideal.

---

For extra context, here are the relevant parts of my package.json:

{
	"type": "module",
	"devEngines": {
		"packageManager": {
			"name": "pnpm",
			"version": "~10.18.3"
		},
		"runtime": {
			"name": "node",
			"version": "~22.20.0"
		}
	},
	"scripts": {
		"app:build": "vite build",
		"app:dev": "vite",
		"check:eslint": "eslint . --cache",
		"check:format": "prettier . --check --cache",
		"check:types": "tsc",
		"check": "pnpm run \"/^check:.*/\""
	},
	"dependencies": {
		"butterfloat": "1.6.4",
		"rxjs": "7.8.2"
	},
	"devDependencies": {
		"@eslint/compat": "1.4.0",
		"@eslint/js": "9.38.0",
		"@ianvs/prettier-plugin-sort-imports": "4.7.0",
		"@types/node": "22.18.11",
		"eslint": "9.38.0",
		"globals": "16.4.0",
		"lint-staged": "16.2.4",
		"prettier": "3.6.2",
		"typescript": "5.9.3",
		"typescript-eslint": "8.46.1",
		"vite": "7.1.10"
	}
}

[WorldMaker]

Interesting find, thanks.

Yeah, Butterfloat bundles all the raw Typescript files (because I think that's useful and JSR suggest is the best library package) and Typescript wants to re-type-check them even though they are a dependency.

For that reason I do try to do all my checks with both Typescript's strict flag and Deno's strict linter.

You've found one of the extra strictness flags that isn't today enabled by Typescript's main strict flag. I appreciate your thoroughness on finding exactly which flag.

I'll look into enabling the flag in this repo's build and try to offer a patch quickly that builds with that flag.

[achou11]

Yeah, Butterfloat bundles all the raw Typescript files (because I think that's useful) and Typescript wants to re-type-check them even though they are a dependency.

Ah yeah that explains things a bit better for me. From my understanding, it's generally discouraged to publish the raw TS files (in a npm context). Usually you'd only publish the emitted JS and their declaration files, which probably would align with typical TS configurations and solve the issue.

I understand that this gets trickier when it comes to other runtimes like Deno and publishing to something like JSR. If you're publishing to both npm and JSR, might require notably distinct and isolated publishing approaches, although I'm not super informed.

You've found one of the extra strictness flags that isn't today enabled by Typescript's main strict flag. I appreciate your thoroughness on finding exactly which flag.

Yeah I wish TS documented these more thoroughly. There are definitely at least a couple of others (like noImplicitOverride).

I'll look into enabling the flag in this repo's build and try to offer a patch quickly that builds with that flag.

Much appreciated! Not super urgent but figured reporting this might provide insight about public usage of the module. Running into this issue at least made me a little more informed about how TS configuration works 😄

[achou11]

Ah yeah that explains things a bit better for me. From my understanding, it's generally discouraged to publish the raw TS files (in a npm context). Usually you'd only publish the emitted JS and their declaration files, which probably would align with typical TS configurations and solve the issue.

This explanation provides the rationale for what I mention in ^: microsoft/TypeScript#41883 (comment)

Basically, would strongly recommend not publishing the raw TS files because it'll be prone to issues with module consumption that shouldn't really be your concern

[WorldMaker]

1.6.5 is now on both JSR and NPM with the patch for this extra flag. This was a good test for me to switch to npm's Trusted Publishing (was already using something similar for JSR).

Yeah I wish TS documented these more thoroughly. There are definitely at least a couple of others (like noImplicitOverride).

The documentation for the strict option itself does list all the flags it turns on under the "Related" subheader (which moves to the sidebar on a wider screen).

When writing tsconfig files today, I'm a bit of a minimalist and like to keep to mostly just "strict": true. From what I read of them, the strictness flags that it doesn't turn on are often "bleeding edge" things that are expected to need another version or two to fully bake (and then they'll move under the the strict "family") or are otherwise considered "too harsh" and on that weird boundary between what should be compile errors and what should be linter warnings.

That said, as a library author I want to meet the strictest standards of the library's consumers, so I'm more than happy to add extra flags on request, as in this case.

I'll discuss the other topic in the other issue.