refactor: Rename BufferShorthand to BufferBinding

apps/typegpu-docs/src/content/docs/advanced/naming-convention.mdx

@@ -41,25 +41,14 @@ const boidsBuffer = root
   .$usage('uniform');
 ```
 
-## Buffer usages
+## Buffer bindings
 
-We give buffer usages *camelCase* names with a suffix that corresponds to their usage.
+We give buffer bindings *camelCase* names with a suffix that corresponds to their usage.
 
 ```ts
-const boidsUniform = boidsBuffer.as('uniform');
-const boidsMutable = boidsBuffer.as('mutable');
-const boidsReadonly = boidsBuffer.as('readonly');
-```
-
-## Buffer shorthands
-
-We give buffer shorthands *camelCase* names with no special suffix, since they represent both
-the buffer, and the single permitted usage.
-
-```ts
-const cells1 = root.createUniform(Cells);
-const cells2 = root.createMutable(Cells);
-const cells3 = root.createReadonly(Cells);
+const cellsUniform = root.createUniform(Cells);
+const cellsMutable = root.createMutable(Cells);
+const cellsReadonly = root.createReadonly(Cells);
 ```
 
 ## Slots

apps/typegpu-docs/src/content/docs/apis/functions/index.mdx

@@ -399,7 +399,7 @@ const neighborhood = tgpu.fn([d.f32, d.f32], d.vec2f)/* wgsl */`(a, r) {
 ### Including external resources
 
 Shelled WGSL functions can use external resources passed via the `$uses` method.
-*Externals* can include anything that can be resolved to WGSL by TypeGPU (numbers, vectors, matrices, constants, TypeGPU functions, buffer usages, textures, samplers, slots, accessors etc.).
+*Externals* can include anything that can be resolved to WGSL by TypeGPU (numbers, vectors, matrices, constants, TypeGPU functions, buffer bindings, textures, samplers, slots, accessors etc.).
 
 ```ts twoslash
 import { tgpu, d } from 'typegpu';

apps/typegpu-docs/src/content/docs/apis/resolve.mdx

@@ -257,14 +257,14 @@ For example, a resource created in a function return statement will not be auto-
 Sometimes, it may not be clear which bind group layouts were used in a given resolution.
 This may occur especially when using:
 
-- Buffer usages/shorthands, which use a hidden, automatically created "catchall" bind group,
+- Buffer bindings, which use a hidden, automatically created "catchall" bind group,
 - TypeGPU functions implemented in JavaScript/TypeScript, which generate their externals automatically.
 
 For these cases, you can use `tgpu.resolveWithContext`, which has the same input API as `tgpu.resolve`, but in addition to the resolved code, it also returns information about the layouts used. `tgpu.resolveWithContext` returns an object with 3 props:
 
 - `code` - the resolved code,
 - `usedBindGroupLayouts` - a list of used `tgpu.bindGroupLayout`,
-- `catchall` - a two-element array containing the bind group constructed for buffer usages and buffer shorthands, preceded by its index.
+- `catchall` - a two-element array containing the bind group constructed for buffer bindings, preceded by its index.
 
 An example, where the "catchall" bind group is created:
 

apps/typegpu-docs/src/content/docs/fundamentals/compute-shaders.mdx

@@ -159,7 +159,7 @@ const bindGroupLayout = tgpu.bindGroupLayout({
 
 Each key in the bind group layout maps to a single resource. For the buffer resources we have explored so far, the equivalent layout entries look like this:
 
-| Fixed Resources shorthand | Laid Out Resources entry |
+| Buffer binding | Layout entry |
 | --- | --- |
 | `root.createUniform(d.u32)` | `{ uniform: d.u32 }` |
 | `root.createReadonly(d.u32)` | `{ storage: d.u32 }` |

packages/typegpu/src/core/buffer/buffer.ts

@@ -31,7 +31,7 @@ import {
   type TgpuMutable,
   type TgpuReadonly,
   type TgpuUniform,
-} from './bufferShorthand.ts';
+} from './bufferBinding.ts';
 
 // ----------
 // Public API
@@ -81,7 +81,7 @@ type ViewUsages<TBuffer extends TgpuBuffer<BaseData>> =
   | (boolean extends TBuffer['usableAsUniform'] ? never : 'uniform')
   | (boolean extends TBuffer['usableAsStorage'] ? never : 'readonly' | 'mutable');
 
-type UsageTypeToBufferShorthand<TData extends BaseData> = {
+type UsageTypeToBufferBinding<TData extends BaseData> = {
   uniform: TgpuUniform<TData>;
   mutable: TgpuMutable<TData>;
   readonly: TgpuReadonly<TData>;
@@ -140,7 +140,7 @@ export interface TgpuBuffer<TData extends BaseData> extends TgpuNamable {
   ): this & UnionToIntersection<LiteralToUsageType<T[number]>>;
   $addFlags(flags: GPUBufferUsageFlags): this;
 
-  as<T extends ViewUsages<this>>(usage: T): UsageTypeToBufferShorthand<TData>[T];
+  as<T extends ViewUsages<this>>(usage: T): UsageTypeToBufferBinding<TData>[T];
 
   compileWriter(): void;
   write(data: InferInput<TData>, options?: BufferWriteOptions): void;
@@ -432,8 +432,8 @@ class TgpuBufferImpl<TData extends BaseData> implements TgpuBuffer<TData> {
     return res;
   }
 
-  as<T extends ViewUsages<this>>(usage: T): UsageTypeToBufferShorthand<TData>[T] {
-    return usageToUsageConstructor[usage](this as never) as UsageTypeToBufferShorthand<TData>[T];
+  as<T extends ViewUsages<this>>(usage: T): UsageTypeToBufferBinding<TData>[T] {
+    return usageToUsageConstructor[usage](this as never) as UsageTypeToBufferBinding<TData>[T];
   }
 
   destroy() {

packages/typegpu/src/core/buffer/bufferShorthand.ts → packages/typegpu/src/core/buffer/bufferBinding.ts

@@ -24,7 +24,7 @@ import { isUsableAsStorage, isUsableAsUniform } from '../../types.ts';
 // Public API
 // ----------
 
-interface TgpuBufferShorthandBase<TData extends BaseData> extends TgpuNamable {
+interface TgpuBufferBindingBase<TData extends BaseData> extends TgpuNamable {
   readonly [$internal]: true;
 
   // Accessible on the CPU
@@ -43,7 +43,7 @@ interface TgpuBufferShorthandBase<TData extends BaseData> extends TgpuNamable {
   readonly [$repr]: Infer<TData>;
 }
 
-export interface TgpuMutable<out TData extends BaseData> extends TgpuBufferShorthandBase<TData> {
+export interface TgpuMutable<out TData extends BaseData> extends TgpuBufferBindingBase<TData> {
   readonly resourceType: 'mutable';
   readonly buffer: TgpuBuffer<TData> & StorageFlag;
 
@@ -59,7 +59,7 @@ export interface TgpuMutable<out TData extends BaseData> extends TgpuBufferShort
   readonly [$repr]: Infer<TData>;
 }
 
-export interface TgpuReadonly<out TData extends BaseData> extends TgpuBufferShorthandBase<TData> {
+export interface TgpuReadonly<out TData extends BaseData> extends TgpuBufferBindingBase<TData> {
   readonly resourceType: 'readonly';
   readonly buffer: TgpuBuffer<TData> & StorageFlag;
 
@@ -75,7 +75,7 @@ export interface TgpuReadonly<out TData extends BaseData> extends TgpuBufferShor
   readonly [$repr]: Infer<TData>;
 }
 
-export interface TgpuUniform<out TData extends BaseData> extends TgpuBufferShorthandBase<TData> {
+export interface TgpuUniform<out TData extends BaseData> extends TgpuBufferBindingBase<TData> {
   readonly resourceType: 'uniform';
   readonly buffer: TgpuBuffer<TData> & UniformFlag;
 
@@ -88,22 +88,26 @@ export interface TgpuUniform<out TData extends BaseData> extends TgpuBufferShort
   // ---
 }
 
-export type TgpuBufferShorthand<TData extends BaseData> =
+export type TgpuBufferBinding<TData extends BaseData> =
   | TgpuMutable<TData>
   | TgpuReadonly<TData>
   | TgpuUniform<TData>;
 
-export function isBufferShorthand<TData extends BaseData>(
+export function isBufferBinding<TData extends BaseData>(
   value: unknown,
-): value is TgpuBufferShorthand<TData> {
-  return value instanceof TgpuBufferShorthandImpl;
+): value is TgpuBufferBinding<TData> {
+  return value instanceof TgpuBufferBindingImpl;
 }
 
+// TODO(#2666) - remove this
+/** @deprecated Use 'isBufferBinding' instead. */
+export const isBufferShorthand = isBufferBinding;
+
 // --------------
 // Implementation
 // --------------
 
-export class TgpuBufferShorthandImpl<
+export class TgpuBufferBindingImpl<
   TType extends 'mutable' | 'readonly' | 'uniform',
   TData extends BaseData,
 > implements SelfResolvable {
@@ -190,7 +194,7 @@ export class TgpuBufferShorthandImpl<
       return mode.buffers.get(this.buffer) as InferGPU<TData>;
     }
 
-    return assertExhaustive(mode, 'bufferShorthand.ts#TgpuBufferShorthandImpl/$');
+    return assertExhaustive(mode, 'bufferBinding.ts#TgpuBufferBindingImpl/$');
   }
 
   set $(value: InferGPU<TData>) {
@@ -210,15 +214,15 @@ export class TgpuBufferShorthandImpl<
     if (mode.type === 'codegen') {
       // The WGSL generator handles buffer assignment, and does not defer to
       // whatever's being assigned to generate the WGSL.
-      throw new Error('Unreachable bufferShorthand.ts#TgpuBufferShorthandImpl/$');
+      throw new Error('Unreachable bufferBinding.ts#TgpuBufferBindingImpl/$');
     }
 
     if (mode.type === 'simulate') {
       mode.buffers.set(this.buffer, value);
       return;
     }
 
-    assertExhaustive(mode, 'bufferShorthand.ts#TgpuBufferShorthandImpl/$');
+    assertExhaustive(mode, 'bufferBinding.ts#TgpuBufferBindingImpl/$');
   }
 
   get value(): InferGPU<TData> {
@@ -230,7 +234,7 @@ export class TgpuBufferShorthandImpl<
   }
 
   toString(): string {
-    return `${this.resourceType}BufferShorthand:${getName(this) ?? '<unnamed>'}`;
+    return `${this.resourceType}BufferBinding:${getName(this) ?? '<unnamed>'}`;
   }
 
   [$resolve](ctx: ResolutionCtx): ResolvedSnippet {
@@ -260,7 +264,7 @@ export class TgpuBufferShorthandImpl<
 
 const mutableUsageMap = new WeakMap<
   TgpuBuffer<BaseData>,
-  TgpuBufferShorthandImpl<'mutable', BaseData>
+  TgpuBufferBindingImpl<'mutable', BaseData>
 >();
 
 export function mutable<TData extends AnyWgslData>(
@@ -274,15 +278,15 @@ export function mutable<TData extends AnyWgslData>(
 
   let usage = mutableUsageMap.get(buffer);
   if (!usage) {
-    usage = new TgpuBufferShorthandImpl('mutable', buffer);
+    usage = new TgpuBufferBindingImpl('mutable', buffer);
     mutableUsageMap.set(buffer, usage);
   }
   return usage as unknown as TgpuMutable<TData>;
 }
 
 const readonlyUsageMap = new WeakMap<
   TgpuBuffer<BaseData>,
-  TgpuBufferShorthandImpl<'readonly', BaseData>
+  TgpuBufferBindingImpl<'readonly', BaseData>
 >();
 
 export function readonly<TData extends AnyWgslData>(
@@ -296,15 +300,15 @@ export function readonly<TData extends AnyWgslData>(
 
   let usage = readonlyUsageMap.get(buffer);
   if (!usage) {
-    usage = new TgpuBufferShorthandImpl('readonly', buffer);
+    usage = new TgpuBufferBindingImpl('readonly', buffer);
     readonlyUsageMap.set(buffer, usage);
   }
   return usage as unknown as TgpuReadonly<TData>;
 }
 
 const uniformUsageMap = new WeakMap<
   TgpuBuffer<BaseData>,
-  TgpuBufferShorthandImpl<'uniform', BaseData>
+  TgpuBufferBindingImpl<'uniform', BaseData>
 >();
 
 export function uniform<TData extends AnyWgslData>(
@@ -318,7 +322,7 @@ export function uniform<TData extends AnyWgslData>(
 
   let usage = uniformUsageMap.get(buffer);
   if (!usage) {
-    usage = new TgpuBufferShorthandImpl('uniform', buffer);
+    usage = new TgpuBufferBindingImpl('uniform', buffer);
     uniformUsageMap.set(buffer, usage);
   }
   return usage as unknown as TgpuUniform<TData>;

packages/typegpu/src/core/buffer/bufferUsage.ts

@@ -1,5 +1,5 @@
 import { type BaseData } from '../../data/wgslTypes.ts';
-import type { TgpuMutable, TgpuReadonly, TgpuUniform } from './bufferShorthand.ts';
+import type { TgpuMutable, TgpuReadonly, TgpuUniform } from './bufferBinding.ts';
 
 // TODO(#2666) - remove this file
 

packages/typegpu/src/core/root/init.ts

@@ -18,11 +18,11 @@ import type { ShaderGenerator } from '../../tgsl/shaderGenerator.ts';
 import { INTERNAL_createBuffer, type TgpuBuffer, type VertexFlag } from '../buffer/buffer.ts';
 import { isBuffer } from '../../types.ts';
 import {
-  TgpuBufferShorthandImpl,
+  TgpuBufferBindingImpl,
   type TgpuMutable,
   type TgpuReadonly,
   type TgpuUniform,
-} from '../buffer/bufferShorthand.ts';
+} from '../buffer/bufferBinding.ts';
 import { computeFn } from '../function/tgpuComputeFn.ts';
 import { fn } from '../function/tgpuFn.ts';
 import {
@@ -345,7 +345,7 @@ class TgpuRootImpl extends WithBindingImpl implements TgpuRoot, ExperimentalTgpu
       // oxlint-disable-next-line typescript/no-explicit-any -- i'm sure it's fine
       .$usage('uniform' as any);
 
-    return new TgpuBufferShorthandImpl('uniform', buffer);
+    return new TgpuBufferBindingImpl('uniform', buffer);
   }
 
   createMutable<TData extends AnyWgslData>(
@@ -356,7 +356,7 @@ class TgpuRootImpl extends WithBindingImpl implements TgpuRoot, ExperimentalTgpu
       // oxlint-disable-next-line typescript/no-explicit-any -- i'm sure it's fine
       .$usage('storage' as any);
 
-    return new TgpuBufferShorthandImpl('mutable', buffer);
+    return new TgpuBufferBindingImpl('mutable', buffer);
   }
 
   createReadonly<TData extends AnyWgslData>(
@@ -367,7 +367,7 @@ class TgpuRootImpl extends WithBindingImpl implements TgpuRoot, ExperimentalTgpu
       // oxlint-disable-next-line typescript/no-explicit-any -- i'm sure it's fine
       .$usage('storage' as any);
 
-    return new TgpuBufferShorthandImpl('readonly', buffer);
+    return new TgpuBufferBindingImpl('readonly', buffer);
   }
 
   createQuerySet<T extends GPUQueryType>(

packages/typegpu/src/core/root/rootTypes.ts

@@ -25,7 +25,7 @@ import type { LogGeneratorOptions } from '../../tgsl/consoleLog/types.ts';
 import type { ShaderGenerator } from '../../tgsl/shaderGenerator.ts';
 import type { Unwrapper } from '../../unwrapper.ts';
 import type { TgpuBuffer, VertexFlag } from '../buffer/buffer.ts';
-import type { TgpuMutable, TgpuReadonly, TgpuUniform } from '../buffer/bufferShorthand.ts';
+import type { TgpuMutable, TgpuReadonly, TgpuUniform } from '../buffer/bufferBinding.ts';
 import type {
   AnyAutoCustoms,
   AutoFragmentIn,

packages/typegpu/src/core/slot/slotTypes.ts

@@ -4,7 +4,7 @@ import type { TgpuNamable } from '../../shared/meta.ts';
 import type { GPUValueOf, Infer, InferGPU } from '../../shared/repr.ts';
 import { $gpuValueOf, $internal, $providing } from '../../shared/symbols.ts';
 import type { UnwrapRuntimeConstructor } from '../../tgpuBindGroupLayout.ts';
-import type { TgpuBufferShorthand } from '../buffer/bufferShorthand.ts';
+import type { TgpuBufferBinding } from '../buffer/bufferBinding.ts';
 import type { TgpuConst } from '../constant/tgpuConstant.ts';
 import type { Withable } from '../root/rootTypes.ts';
 import type { TgpuTextureView } from '../texture/texture.ts';
@@ -69,7 +69,7 @@ export interface TgpuAccessor<T extends BaseData = BaseData> extends TgpuNamable
 
 type DataAccessorIn<T extends BaseData> =
   | (() => DataAccessorIn<T>)
-  | TgpuBufferShorthand<T>
+  | TgpuBufferBinding<T>
   | TgpuVar<VariableScope, T>
   | TgpuConst<T>
   | Infer<T>;
@@ -101,7 +101,7 @@ export interface TgpuMutableAccessor<T extends BaseData = BaseData> extends Tgpu
 
 type MutableDataAccessorIn<T extends BaseData> =
   | (() => Infer<T> | MutableDataAccessorIn<T>)
-  | TgpuBufferShorthand<T>
+  | TgpuBufferBinding<T>
   | TgpuVar<VariableScope, T>;
 
 type MutableTextureAccessorIn<T extends WgslTexture | WgslStorageTexture> =

packages/typegpu/src/indexNamedExports.ts

@@ -22,7 +22,7 @@ export {
   isUsableAsIndex,
   isUsableAsStorage,
 } from './types.ts';
-export { isBufferShorthand } from './core/buffer/bufferShorthand.ts';
+export { isBufferBinding, isBufferShorthand } from './core/buffer/bufferBinding.ts';
 export { isTgpuFn } from './core/function/tgpuFn.ts';
 export { isTgpuFragmentFn } from './core/function/tgpuFragmentFn.ts';
 export { isTgpuVertexFn } from './core/function/tgpuVertexFn.ts';
@@ -74,7 +74,7 @@ export type {
   TgpuBufferReadonly,
   TgpuBufferUniform,
 } from './core/buffer/bufferUsage.ts';
-export type { TgpuMutable, TgpuReadonly, TgpuUniform } from './core/buffer/bufferShorthand.ts';
+export type { TgpuMutable, TgpuReadonly, TgpuUniform } from './core/buffer/bufferBinding.ts';
 export type {
   Eventual,
   TgpuAccessor,

packages/typegpu/src/resolutionCtx.ts

@@ -1076,7 +1076,7 @@ export class ResolutionCtxImpl implements ResolutionCtx {
  *
  * @param code - The resolved code.
  * @param usedBindGroupLayouts - List of used `tgpu.bindGroupLayout`s.
- * @param catchall - Automatically constructed bind group for buffer usages and buffer shorthands, preceded by its index.
+ * @param catchall - Automatically constructed bind group for buffer usages and buffer bindings, preceded by its index.
  * @param logResources - Buffers and information about used console.logs needed to decode the raw data.
  */
 export interface ResolutionResult {

packages/typegpu/src/tgsl/consoleLog/logGenerator.ts

@@ -1,4 +1,4 @@
-import type { TgpuMutable } from '../../core/buffer/bufferShorthand.ts';
+import type { TgpuMutable } from '../../core/buffer/bufferBinding.ts';
 import { stitch } from '../../core/resolve/stitch.ts';
 import type { TgpuRoot } from '../../core/root/rootTypes.ts';
 import { shaderStageSlot } from '../../core/slot/internalSlots.ts';

packages/typegpu/src/tgsl/consoleLog/serializers.ts

@@ -1,4 +1,4 @@
-import type { TgpuMutable } from '../../core/buffer/bufferShorthand.ts';
+import type { TgpuMutable } from '../../core/buffer/bufferBinding.ts';
 import { fn, type TgpuFn } from '../../core/function/tgpuFn.ts';
 import { slot } from '../../core/slot/slot.ts';
 import { privateVar } from '../../core/variable/tgpuVariable.ts';

packages/typegpu/src/tgsl/consoleLog/types.ts

@@ -1,4 +1,4 @@
-import type { TgpuMutable } from '../../core/buffer/bufferShorthand.ts';
+import type { TgpuMutable } from '../../core/buffer/bufferBinding.ts';
 import type { Snippet } from '../../data/snippet.ts';
 import type { AnyWgslData, Atomic, U32, WgslArray, WgslStruct } from '../../data/wgslTypes.ts';
 import type { GenerationCtx } from '../generationHelpers.ts';