typegpu 0.10.0 → 0.10.2

package/resolutionCtx.js

@@ -0,0 +1,546 @@
+import { $internal, $providing, $resolve, isMarkedInternal } from "./shared/symbols.js";
+import { getName, hasTinyestMetadata, setName } from "./shared/meta.js";
+import { Void, isPtr, isWgslArray, isWgslStruct } from "./data/wgslTypes.js";
+import { UnknownData, isData } from "./data/dataTypes.js";
+import { snip } from "./data/snippet.js";
+import { MissingSlotValueError, ResolutionError, WgslTypeError, invariant } from "./errors.js";
+import { isLazy, isProviding, isSlot } from "./core/slot/slotTypes.js";
+import { CodegenState, NormalState, isSelfResolvable } from "./types.js";
+import { provideCtx, topLevelState } from "./execMode.js";
+import { stitch } from "./core/resolve/stitch.js";
+import { safeStringify } from "./shared/stringify.js";
+import { getBestConversion } from "./tgsl/conversion.js";
+import { bool } from "./data/numeric.js";
+import { getAttributesString } from "./data/attributes.js";
+import { createIoSchema } from "./core/function/ioSchema.js";
+import { AutoStruct } from "./data/autoStruct.js";
+import { coerceToSnippet, concretize, numericLiteralToSnippet } from "./tgsl/generationHelpers.js";
+import { accessProp } from "./tgsl/accessProp.js";
+import { isTgpuFn } from "./core/function/tgpuFn.js";
+import { getUniqueName } from "./core/resolve/namespace.js";
+import { resolveData } from "./core/resolve/resolveData.js";
+import { ConfigurableImpl } from "./core/root/configurableImpl.js";
+import { naturalsExcept } from "./shared/generators.js";
+import { TgpuBindGroupImpl, bindGroupLayout } from "./tgpuBindGroupLayout.js";
+import { LogGeneratorImpl, LogGeneratorNullImpl } from "./tgsl/consoleLog/logGenerator.js";
+import wgslGenerator from "./tgsl/wgslGenerator.js";
+import { FuncParameterType } from "tinyest";
+
+//#region src/resolutionCtx.ts
+/**
+* Inserted into bind group entry definitions that belong
+* to the automatically generated catch-all bind group.
+*
+* A non-occupied group index can only be determined after
+* every resource has been resolved, so this acts as a placeholder
+* to be replaced with an actual numeric index at the very end
+* of the resolution process.
+*/
+const CATCHALL_BIND_GROUP_IDX_MARKER = "#CATCHALL#";
+var ItemStateStackImpl = class {
+	_stack = [];
+	_itemDepth = 0;
+	get itemDepth() {
+		return this._itemDepth;
+	}
+	get topItem() {
+		const state = this._stack[this._stack.length - 1];
+		if (!state || state.type !== "item") throw new Error("Internal error, expected item layer to be on top.");
+		return state;
+	}
+	get topFunctionScope() {
+		return this._stack.findLast((e) => e.type === "functionScope");
+	}
+	pushItem() {
+		this._itemDepth++;
+		this._stack.push({
+			type: "item",
+			usedSlots: /* @__PURE__ */ new Set()
+		});
+	}
+	pushSlotBindings(pairs) {
+		this._stack.push({
+			type: "slotBinding",
+			bindingMap: new WeakMap(pairs)
+		});
+	}
+	pushFunctionScope(functionType, args, argAliases, returnType, externalMap) {
+		const scope = {
+			type: "functionScope",
+			functionType,
+			args,
+			argAliases,
+			returnType,
+			externalMap,
+			reportedReturnTypes: /* @__PURE__ */ new Set()
+		};
+		this._stack.push(scope);
+		return scope;
+	}
+	pushBlockScope() {
+		this._stack.push({
+			type: "blockScope",
+			declarations: /* @__PURE__ */ new Map(),
+			externals: /* @__PURE__ */ new Map()
+		});
+	}
+	pop(type) {
+		const layer = this._stack[this._stack.length - 1];
+		if (!layer || type && layer.type !== type) throw new Error(`Internal error, expected a ${type} layer to be on top.`);
+		const poppedValue = this._stack.pop();
+		if (type === "item") this._itemDepth--;
+		return poppedValue;
+	}
+	readSlot(slot) {
+		for (let i = this._stack.length - 1; i >= 0; --i) {
+			const layer = this._stack[i];
+			if (layer?.type === "item") layer.usedSlots.add(slot);
+			else if (layer?.type === "slotBinding") {
+				const boundValue = layer.bindingMap.get(slot);
+				if (boundValue !== void 0) return boundValue;
+			} else if (layer?.type === "functionScope" || layer?.type === "blockScope") {} else throw new Error("Unknown layer type.");
+		}
+		return slot.defaultValue;
+	}
+	getSnippetById(id) {
+		for (let i = this._stack.length - 1; i >= 0; --i) {
+			const layer = this._stack[i];
+			if (layer?.type === "functionScope") {
+				const arg = layer.args.find((a) => a.value === id);
+				if (arg !== void 0) return arg;
+				if (layer.argAliases[id]) return layer.argAliases[id];
+				const external = layer.externalMap[id];
+				if (external !== void 0 && external !== null) return coerceToSnippet(external);
+				return;
+			}
+			if (layer?.type === "blockScope") {
+				const snippet = layer.declarations.get(id) ?? layer.externals.get(id);
+				if (snippet !== void 0) return snippet;
+			}
+		}
+	}
+	defineBlockVariable(id, snippet) {
+		if (snippet.dataType === UnknownData) throw Error(`Tried to define variable '${id}' of unknown type`);
+		for (let i = this._stack.length - 1; i >= 0; --i) {
+			const layer = this._stack[i];
+			if (layer?.type === "blockScope") {
+				layer.declarations.set(id, snippet);
+				return;
+			}
+		}
+		throw new Error("No block scope found to define a variable in.");
+	}
+	setBlockExternals(externals) {
+		for (let i = this._stack.length - 1; i >= 0; --i) {
+			const layer = this._stack[i];
+			if (layer?.type === "blockScope") {
+				Object.entries(externals).forEach(([id, snippet]) => {
+					layer.externals.set(id, snippet);
+				});
+				return;
+			}
+		}
+		throw new Error("No block scope found to set externals in.");
+	}
+	clearBlockExternals() {
+		for (let i = this._stack.length - 1; i >= 0; --i) {
+			const layer = this._stack[i];
+			if (layer?.type === "blockScope") {
+				layer.externals.clear();
+				return;
+			}
+		}
+		throw new Error("No block scope found to clear externals in.");
+	}
+};
+const INDENT = [
+	"",
+	"  ",
+	"    ",
+	"      ",
+	"        ",
+	"          ",
+	"            ",
+	"              ",
+	"                "
+];
+const N = INDENT.length - 1;
+var IndentController = class {
+	identLevel = 0;
+	get pre() {
+		return INDENT[this.identLevel] ?? INDENT[N].repeat(this.identLevel / N) + INDENT[this.identLevel % N];
+	}
+	indent() {
+		const str = this.pre;
+		this.identLevel++;
+		return str;
+	}
+	dedent() {
+		this.identLevel--;
+		return this.pre;
+	}
+	withResetLevel(callback) {
+		const savedLevel = this.identLevel;
+		this.identLevel = 0;
+		try {
+			return callback();
+		} finally {
+			this.identLevel = savedLevel;
+		}
+	}
+};
+var ResolutionCtxImpl = class {
+	#namespaceInternal;
+	#shaderGenerator;
+	_indentController = new IndentController();
+	_itemStateStack = new ItemStateStackImpl();
+	#modeStack = [];
+	_declarations = [];
+	_varyingLocations;
+	#currentlyResolvedItems = /* @__PURE__ */ new WeakSet();
+	#logGenerator;
+	get varyingLocations() {
+		return this._varyingLocations;
+	}
+	[$internal] = { itemStateStack: this._itemStateStack };
+	/**
+	* A map from registered bind group layouts to random strings put in
+	* place of their group index. The whole tree has to be traversed to
+	* collect every use of a typed bind group layout, since they can be
+	* explicitly imposed group indices, and they cannot collide.
+	*/
+	bindGroupLayoutsToPlaceholderMap = /* @__PURE__ */ new Map();
+	_nextFreeLayoutPlaceholderIdx = 0;
+	fixedBindings = [];
+	enableExtensions;
+	expectedType;
+	constructor(opts) {
+		this.enableExtensions = opts.enableExtensions;
+		this.#shaderGenerator = opts.shaderGenerator ?? wgslGenerator;
+		this.#logGenerator = opts.root ? new LogGeneratorImpl(opts.root) : new LogGeneratorNullImpl();
+		this.#namespaceInternal = opts.namespace[$internal];
+	}
+	getUniqueName(resource) {
+		return getUniqueName(this.#namespaceInternal, resource);
+	}
+	makeNameValid(name) {
+		return this.#namespaceInternal.nameRegistry.makeValid(name);
+	}
+	get pre() {
+		return this._indentController.pre;
+	}
+	get topFunctionScope() {
+		return this._itemStateStack.topFunctionScope;
+	}
+	get topFunctionReturnType() {
+		const scope = this._itemStateStack.topFunctionScope;
+		invariant(scope, "Internal error, expected function scope to be present.");
+		return scope.returnType;
+	}
+	get shelllessRepo() {
+		return this.#namespaceInternal.shelllessRepo;
+	}
+	indent() {
+		return this._indentController.indent();
+	}
+	dedent() {
+		return this._indentController.dedent();
+	}
+	withResetIndentLevel(callback) {
+		return this._indentController.withResetLevel(callback);
+	}
+	getById(id) {
+		const item = this._itemStateStack.getSnippetById(id);
+		if (item === void 0) return null;
+		return item;
+	}
+	defineVariable(id, snippet) {
+		this._itemStateStack.defineBlockVariable(id, snippet);
+	}
+	reportReturnType(dataType) {
+		const scope = this._itemStateStack.topFunctionScope;
+		invariant(scope, "Internal error, expected function scope to be present.");
+		scope.reportedReturnTypes.add(dataType);
+	}
+	pushBlockScope() {
+		this.#namespaceInternal.nameRegistry.pushBlockScope();
+		this._itemStateStack.pushBlockScope();
+	}
+	popBlockScope() {
+		this.#namespaceInternal.nameRegistry.popBlockScope();
+		this._itemStateStack.pop("blockScope");
+	}
+	setBlockExternals(externals) {
+		this._itemStateStack.setBlockExternals(externals);
+	}
+	clearBlockExternals() {
+		this._itemStateStack.clearBlockExternals();
+	}
+	generateLog(op, args) {
+		return this.#logGenerator.generateLog(this, op, args);
+	}
+	get logResources() {
+		return this.#logGenerator.logResources;
+	}
+	fnToWgsl(options) {
+		let fnScopePushed = false;
+		try {
+			this.#namespaceInternal.nameRegistry.pushFunctionScope();
+			const args = [];
+			const argAliases = [];
+			for (const [i, argType] of options.argTypes.entries()) {
+				const astParam = options.params[i];
+				const origin = isPtr(argType) ? argType.addressSpace === "storage" ? argType.access === "read" ? "readonly" : "mutable" : argType.addressSpace : "argument";
+				switch (astParam?.type) {
+					case FuncParameterType.identifier: {
+						const rawName = astParam.name;
+						const snippet = snip(this.makeNameValid(rawName), argType, origin);
+						args.push(snippet);
+						if (snippet.value !== rawName) argAliases.push([rawName, snippet]);
+						break;
+					}
+					case FuncParameterType.destructuredObject: {
+						const objSnippet = snip(`_arg_${i}`, argType, origin);
+						args.push(objSnippet);
+						argAliases.push(...astParam.props.map(({ name, alias }) => [alias, accessProp(objSnippet, name)]));
+						break;
+					}
+					case void 0: if (!(argType instanceof AutoStruct)) args.push(snip(`_arg_${i}`, argType, origin));
+				}
+			}
+			const scope = this._itemStateStack.pushFunctionScope(options.functionType, args, Object.fromEntries(argAliases), options.returnType, options.externalMap);
+			fnScopePushed = true;
+			this.#shaderGenerator.initGenerator(this);
+			const body = this.#shaderGenerator.functionDefinition(options.body);
+			let returnType = options.returnType;
+			if (returnType instanceof AutoStruct) if (isWgslStruct(scope.reportedReturnTypes.values().next().value)) returnType = returnType.completeStruct;
+			else returnType = void 0;
+			if (!returnType) {
+				const returnTypes = [...scope.reportedReturnTypes];
+				if (returnTypes.length === 0) returnType = Void;
+				else {
+					const conversion = getBestConversion(returnTypes);
+					if (conversion && !conversion.hasImplicitConversions) returnType = conversion.targetType;
+				}
+				if (!returnType) throw new Error(`Expected function to have a single return type, got [${returnTypes.join(", ")}]. Cast explicitly to the desired type.`);
+				returnType = concretize(returnType);
+				if (options.functionType === "vertex" || options.functionType === "fragment") returnType = createIoSchema(returnType);
+			}
+			return {
+				head: resolveFunctionHeader(this, args, returnType),
+				body,
+				returnType
+			};
+		} finally {
+			if (fnScopePushed) this._itemStateStack.pop("functionScope");
+			this.#namespaceInternal.nameRegistry.popFunctionScope();
+		}
+	}
+	addDeclaration(declaration) {
+		this._declarations.push(declaration);
+	}
+	allocateLayoutEntry(layout) {
+		const memoMap = this.bindGroupLayoutsToPlaceholderMap;
+		let placeholderKey = memoMap.get(layout);
+		if (!placeholderKey) {
+			placeholderKey = `#BIND_GROUP_LAYOUT_${this._nextFreeLayoutPlaceholderIdx++}#`;
+			memoMap.set(layout, placeholderKey);
+		}
+		return placeholderKey;
+	}
+	allocateFixedEntry(layoutEntry, resource) {
+		const binding = this.fixedBindings.length;
+		this.fixedBindings.push({
+			layoutEntry,
+			resource
+		});
+		return {
+			group: CATCHALL_BIND_GROUP_IDX_MARKER,
+			binding
+		};
+	}
+	readSlot(slot) {
+		const value = this._itemStateStack.readSlot(slot);
+		if (value === void 0) throw new MissingSlotValueError(slot);
+		return value;
+	}
+	withSlots(pairs, callback) {
+		if (pairs.length === 0) return callback();
+		this._itemStateStack.pushSlotBindings(pairs);
+		try {
+			return callback();
+		} finally {
+			this._itemStateStack.pop("slotBinding");
+		}
+	}
+	withVaryingLocations(locations, callback) {
+		this._varyingLocations = locations;
+		try {
+			return callback();
+		} finally {
+			this._varyingLocations = void 0;
+		}
+	}
+	withRenamed(item, name, callback) {
+		if (!name) return callback();
+		const oldName = getName(item);
+		try {
+			setName(item, name);
+			return callback();
+		} finally {
+			setName(item, oldName);
+		}
+	}
+	unwrap(eventual) {
+		if (isProviding(eventual)) return this.withRenamed(eventual[$providing].inner, getName(eventual), () => this.withSlots(eventual[$providing].pairs, () => this.unwrap(eventual[$providing].inner)));
+		let maybeEventual = eventual;
+		while (true) if (isSlot(maybeEventual)) maybeEventual = this.readSlot(maybeEventual);
+		else if (isLazy(maybeEventual)) maybeEventual = this._getOrCompute(maybeEventual);
+		else break;
+		return maybeEventual;
+	}
+	_getOrCompute(lazy) {
+		const instances = this.#namespaceInternal.memoizedLazy.get(lazy) ?? [];
+		this._itemStateStack.pushItem();
+		try {
+			for (const instance of instances) if ([...instance.slotToValueMap.entries()].every(([slot, expectedValue]) => slot.areEqual(this._itemStateStack.readSlot(slot), expectedValue))) return instance.result;
+			this.pushMode(new NormalState());
+			let result;
+			try {
+				result = lazy[$internal].compute();
+			} finally {
+				this.popMode("normal");
+			}
+			const slotToValueMap = /* @__PURE__ */ new Map();
+			for (const usedSlot of this._itemStateStack.topItem.usedSlots) slotToValueMap.set(usedSlot, this._itemStateStack.readSlot(usedSlot));
+			instances.push({
+				slotToValueMap,
+				result
+			});
+			this.#namespaceInternal.memoizedLazy.set(lazy, instances);
+			return result;
+		} catch (err) {
+			if (err instanceof ResolutionError) throw err.appendToTrace(lazy);
+			throw new ResolutionError(err, [lazy]);
+		} finally {
+			this._itemStateStack.pop("item");
+		}
+	}
+	/**
+	* @param item The item whose resolution should be either retrieved from the cache (if there is a cache hit), or resolved.
+	*/
+	_getOrInstantiate(item) {
+		const instances = this.#namespaceInternal.memoizedResolves.get(item) ?? [];
+		this._itemStateStack.pushItem();
+		try {
+			for (const instance of instances) if ([...instance.slotToValueMap.entries()].every(([slot, expectedValue]) => slot.areEqual(this._itemStateStack.readSlot(slot), expectedValue))) return instance.result;
+			let result;
+			if (isData(item)) result = snip(resolveData(this, item), Void, "runtime");
+			else if (isLazy(item) || isSlot(item)) result = this.resolve(this.unwrap(item));
+			else if (isSelfResolvable(item)) result = item[$resolve](this);
+			else if (hasTinyestMetadata(item)) {
+				const shellless = this.#namespaceInternal.shelllessRepo.get(item, void 0);
+				if (!shellless) throw new Error(`Couldn't resolve ${item.name}. Make sure it's a function that accepts no arguments, or call it from another TypeGPU function.`);
+				return this.withResetIndentLevel(() => this.resolve(shellless));
+			} else throw new TypeError(`Unresolvable internal value: ${safeStringify(item)}`);
+			const slotToValueMap = /* @__PURE__ */ new Map();
+			for (const usedSlot of this._itemStateStack.topItem.usedSlots) slotToValueMap.set(usedSlot, this._itemStateStack.readSlot(usedSlot));
+			instances.push({
+				slotToValueMap,
+				result
+			});
+			this.#namespaceInternal.memoizedResolves.set(item, instances);
+			return result;
+		} catch (err) {
+			if (err instanceof ResolutionError) throw err.appendToTrace(item);
+			throw new ResolutionError(err, [item]);
+		} finally {
+			this._itemStateStack.pop("item");
+		}
+	}
+	resolve(item, schema) {
+		if (isTgpuFn(item) || hasTinyestMetadata(item)) {
+			if (this.#currentlyResolvedItems.has(item) && !this.#namespaceInternal.memoizedResolves.has(item)) throw new Error(`Recursive function ${item} detected. Recursion is not allowed on the GPU.`);
+			this.#currentlyResolvedItems.add(item);
+		}
+		if (isProviding(item)) return this.withRenamed(item[$providing].inner, getName(item), () => this.withSlots(item[$providing].pairs, () => this.resolve(item[$providing].inner, schema)));
+		if (isMarkedInternal(item) || hasTinyestMetadata(item)) {
+			if (this._itemStateStack.itemDepth === 0) try {
+				this.pushMode(new CodegenState());
+				const result = provideCtx(this, () => this._getOrInstantiate(item));
+				return snip(`${[...this._declarations].join("\n\n")}${result.value}`, Void, "runtime");
+			} finally {
+				this.popMode("codegen");
+			}
+			return this._getOrInstantiate(item);
+		}
+		if (typeof item === "number") {
+			const realSchema = schema ?? numericLiteralToSnippet(item).dataType;
+			invariant(realSchema !== UnknownData, "Schema has to be known for resolving numbers");
+			if (realSchema.type === "abstractInt") return snip(`${item}`, realSchema, "constant");
+			if (realSchema.type === "u32") return snip(`${item}u`, realSchema, "constant");
+			if (realSchema.type === "i32") return snip(`${item}i`, realSchema, "constant");
+			const exp = item.toExponential();
+			const decimal = realSchema.type === "abstractFloat" && Number.isInteger(item) ? `${item}.` : `${item}`;
+			const base = exp.length < decimal.length ? exp : decimal;
+			if (realSchema.type === "f32") return snip(`${base}f`, realSchema, "constant");
+			if (realSchema.type === "f16") return snip(`${base}h`, realSchema, "constant");
+			return snip(base, realSchema, "constant");
+		}
+		if (typeof item === "boolean") return snip(item ? "true" : "false", bool, "constant");
+		if (typeof item === "string") return snip(item, Void, "runtime");
+		if (schema && isWgslArray(schema)) {
+			if (!Array.isArray(item)) throw new WgslTypeError(`Cannot coerce ${item} into value of type '${schema}'`);
+			if (schema.elementCount !== item.length) throw new WgslTypeError(`Cannot create value of type '${schema}' from an array of length: ${item.length}`);
+			return snip(stitch`array<${this.resolve(schema.elementType)}, ${schema.elementCount}>(${item.map((element) => snip(element, schema.elementType, "runtime"))})`, schema, "runtime");
+		}
+		if (Array.isArray(item)) return snip(stitch`array(${item.map((element) => this.resolve(element))})`, UnknownData, "runtime");
+		if (schema && isWgslStruct(schema)) return snip(stitch`${this.resolve(schema)}(${Object.entries(schema.propTypes).map(([key, propType]) => snip(item[key], propType, "runtime"))})`, schema, "runtime");
+		throw new WgslTypeError(`Value ${item} (as json: ${safeStringify(item)}) is not resolvable${schema ? ` to type ${safeStringify(schema)}` : ""}`);
+	}
+	pushMode(mode) {
+		this.#modeStack.push(mode);
+	}
+	popMode(expected) {
+		const mode = this.#modeStack.pop();
+		if (expected !== void 0) invariant(mode?.type === expected, "Unexpected mode");
+	}
+	get mode() {
+		return this.#modeStack[this.#modeStack.length - 1] ?? topLevelState;
+	}
+};
+function resolve(item, options) {
+	const ctx = new ResolutionCtxImpl(options);
+	let code = (options.config ? ctx.withSlots(options.config(new ConfigurableImpl([])).bindings, () => ctx.resolve(item)) : ctx.resolve(item)).value;
+	const memoMap = ctx.bindGroupLayoutsToPlaceholderMap;
+	const usedBindGroupLayouts = [];
+	const automaticIds = naturalsExcept(new Set([...memoMap.keys()].map((layout) => layout.index).filter((v) => v !== void 0)));
+	const layoutEntries = ctx.fixedBindings.map((binding, idx) => [String(idx), binding.layoutEntry]);
+	const createCatchallGroup = () => {
+		const catchallIdx = automaticIds.next().value;
+		const catchallLayout = bindGroupLayout(Object.fromEntries(layoutEntries));
+		usedBindGroupLayouts[catchallIdx] = catchallLayout;
+		code = code.replaceAll(CATCHALL_BIND_GROUP_IDX_MARKER, String(catchallIdx));
+		return [catchallIdx, new TgpuBindGroupImpl(catchallLayout, Object.fromEntries(ctx.fixedBindings.map((binding, idx) => [String(idx), binding.resource])))];
+	};
+	const catchall = layoutEntries.length > 0 ? createCatchallGroup() : void 0;
+	for (const [layout, placeholder] of memoMap.entries()) {
+		const idx = layout.index ?? automaticIds.next().value;
+		usedBindGroupLayouts[idx] = layout;
+		code = code.replaceAll(placeholder, String(idx));
+	}
+	if (options.enableExtensions && options.enableExtensions.length > 0) code = `${options.enableExtensions.map((ext) => `enable ${ext};`).join("\n")}\n\n${code}`;
+	return {
+		code,
+		usedBindGroupLayouts,
+		catchall,
+		logResources: ctx.logResources
+	};
+}
+function resolveFunctionHeader(ctx, args, returnType) {
+	const argList = args.map((arg) => `${arg.value}: ${ctx.resolve(arg.dataType).value}`).join(", ");
+	return returnType.type !== "void" ? `(${argList}) -> ${getAttributesString(returnType)}${ctx.resolve(returnType).value} ` : `(${argList}) `;
+}
+
+//#endregion
+export { ResolutionCtxImpl, resolve };

package/shared/env.js

@@ -0,0 +1,13 @@
+//#region src/shared/env.ts
+/**
+* This can be used to branch functionality between "dev" and "prod" modes, so that our
+* library can omit doing unnecessary work once it's out in the wild
+*
+* Even though the value of this constant uses Node.js specific APIs, pretty much every
+* bundler replaces the expression below with either `development` or `production`
+*/
+const DEV = process.env.NODE_ENV === "development";
+const TEST = process.env.NODE_ENV === "test";
+
+//#endregion
+export { DEV, TEST };

package/shared/generators.js

@@ -0,0 +1,14 @@
+//#region src/shared/generators.ts
+/**
+* Yields values in the sequence 0,1,2..∞ except for the ones in the `excluded` set.
+*/
+function* naturalsExcept(excluded) {
+	let next = 0;
+	while (true) {
+		if (!excluded.has(next)) yield next;
+		next++;
+	}
+}
+
+//#endregion
+export { naturalsExcept };

package/shared/meta.d.ts

@@ -0,0 +1,39 @@
+import { Block, FuncParameter } from "tinyest";
+
+//#region src/shared/meta.d.ts
+interface MetaData {
+  v?: number;
+  name?: string | undefined;
+  ast?: {
+    params: FuncParameter[];
+    body: Block;
+    externalNames: string[];
+  } | undefined;
+  externals?: Record<string, unknown> | (() => Record<string, unknown>) | undefined;
+}
+/**
+ * Don't use or you WILL get fired from your job.
+ *
+ * The information that this type describes is additional
+ * properties that we add onto `globalThis`, used by tools
+ * like `unplugin-typegpu` or our test suite.
+ *
+ * @internal
+ */
+type INTERNAL_GlobalExt = typeof globalThis & {
+  __TYPEGPU_VERSION__: string | undefined;
+  __TYPEGPU_META__: WeakMap<object, MetaData>;
+  __TYPEGPU_AUTONAME__: <T>(exp: T, label: string) => T;
+  __TYPEGPU_MEASURE_PERF__?: boolean | undefined;
+  __TYPEGPU_PERF_RECORDS__?: Map<string, unknown[]> | undefined;
+};
+/**
+ * Can be assigned a name. Not to be confused with just having a name.
+ * The `$name` function should use `setName` to rename the object itself,
+ * even if `$getNameForward` symbol is present.
+ */
+interface TgpuNamable {
+  $name(label: string): this;
+}
+//#endregion
+export { INTERNAL_GlobalExt, TgpuNamable };

package/shared/meta.js

@@ -0,0 +1,63 @@
+import { version } from "../package.js";
+import { DEV, TEST } from "./env.js";
+import { $getNameForward, isMarkedInternal } from "./symbols.js";
+
+//#region src/shared/meta.ts
+const globalWithMeta = globalThis;
+if (globalWithMeta.__TYPEGPU_VERSION__ !== void 0) console.warn(`Found duplicate TypeGPU version. First was ${globalWithMeta.__TYPEGPU_VERSION__}, this one is ${version}. This may cause unexpected behavior.`);
+globalWithMeta.__TYPEGPU_VERSION__ = version;
+globalWithMeta.__TYPEGPU_AUTONAME__ = (exp, label) => isNamable(exp) && isMarkedInternal(exp) && !getName(exp) ? exp.$name(label) : exp;
+/**
+* Performance measurements are only enabled in dev & test environments for now
+*/
+const PERF = (DEV || TEST) && {
+	get enabled() {
+		return !!globalWithMeta.__TYPEGPU_MEASURE_PERF__;
+	},
+	record(name, data) {
+		const records = globalWithMeta.__TYPEGPU_PERF_RECORDS__ ??= /* @__PURE__ */ new Map();
+		let entries = records.get(name);
+		if (!entries) {
+			entries = [];
+			records.set(name, entries);
+		}
+		entries.push(data);
+	}
+} || void 0;
+function isForwarded(value) {
+	return !!value?.[$getNameForward];
+}
+function getName(definition) {
+	if (isForwarded(definition)) return getName(definition[$getNameForward]);
+	return getMetaData(definition)?.name;
+}
+function setName(definition, name) {
+	if (isForwarded(definition)) {
+		setName(definition[$getNameForward], name);
+		return;
+	}
+	setMetaData(definition, { name });
+}
+function isNamable(value) {
+	return !!value?.$name;
+}
+/**
+* AST's are given to functions with a 'use gpu' directive, which this function checks for.
+*/
+function hasTinyestMetadata(value) {
+	return !!getMetaData(value)?.ast;
+}
+function getMetaData(definition) {
+	return globalWithMeta.__TYPEGPU_META__.get(definition);
+}
+function setMetaData(definition, metaData) {
+	globalWithMeta.__TYPEGPU_META__ ??= /* @__PURE__ */ new WeakMap();
+	const map = globalWithMeta.__TYPEGPU_META__;
+	map.set(definition, {
+		...map.get(definition),
+		...metaData
+	});
+}
+
+//#endregion
+export { PERF, getMetaData, getName, hasTinyestMetadata, isNamable, setName };