Simplify and document

Author: iwoplaza

packages/typegpu/src/data/ref.ts

@@ -41,7 +41,7 @@ export interface ref<T> {
 // TODO: Restrict calls to this function only from within TypeGPU functions
 export const ref: DualFn<<T>(value: T) => ref<T>> = (() => {
   const gpuImpl = (value: Snippet) => {
-    return snip(new RefOnGPU(value), UnknownData, /* origin */ 'runtime');
+    return snip(new RefOperator(value), UnknownData, /* origin */ 'runtime');
   };
 
   const jsImpl = <T>(value: T) => new refImpl(value);
@@ -99,66 +99,43 @@ class refImpl<T> implements ref<T> {
   }
 }
 
-export class RefOnGPU {
+export class RefOperator implements SelfResolvable {
   readonly [$internal]: true;
-
   readonly snippet: Snippet;
+
   /**
    * Pointer params only exist if the ref was created from a reference (buttery-butter).
+   *
+   * @example
+   * ```ts
+   * const life = ref(42); // created from a value
+   * const boid = ref(layout.$.boids[0]); // created from a reference
+   * ```
    */
   readonly ptrType: Ptr | undefined;
 
   constructor(snippet: Snippet) {
     this[$internal] = true;
     this.snippet = snippet;
-    this.ptrType = createPtrFromOrigin(
-      snippet.origin,
-      snippet.dataType as StorableData,
-    );
-  }
-
-  toString(): string {
-    return `ref:${this.snippet.value}`;
-  }
 
-  [$resolve](ctx: ResolutionCtx): ResolvedSnippet {
-    invariant(
-      !!this.ptrType,
-      'RefOnGPU must have a pointer type when resolved',
-    );
-    return snip(stitch`(&${this.snippet})`, this.ptrType, this.snippet.origin);
-  }
-}
-
-export class RefOperator implements SelfResolvable {
-  readonly [$internal]: true;
-  readonly snippet: Snippet;
-  readonly #ptrType: Ptr;
-
-  constructor(snippet: Snippet) {
-    this[$internal] = true;
-    this.snippet = snippet;
-
-    const ptrType = createPtrFromOrigin(
+    this.ptrType = createPtrFromOrigin(
       snippet.origin,
       snippet.dataType as StorableData,
     );
-
-    if (!ptrType) {
-      throw new Error(
-        `Cannot take a reference of a value with origin ${this.snippet.origin}`,
-      );
-    }
-
-    this.#ptrType = ptrType;
   }
 
   get [$ownSnippet](): Snippet {
-    return snip(this, this.#ptrType, this.snippet.origin);
+    if (!this.ptrType) {
+      throw new Error(stitch`Cannot take a reference of ${this.snippet}`);
+    }
+    return snip(this, this.ptrType, this.snippet.origin);
   }
 
   [$resolve](ctx: ResolutionCtx): ResolvedSnippet {
-    return snip(stitch`(&${this.snippet})`, this.#ptrType, this.snippet.origin);
+    if (!this.ptrType) {
+      throw new Error(stitch`Cannot take a reference of ${this.snippet}`);
+    }
+    return snip(stitch`(&${this.snippet})`, this.ptrType, this.snippet.origin);
   }
 }
 

packages/typegpu/src/tgsl/shellless.ts

@@ -3,7 +3,7 @@ import {
   type ShelllessImpl,
 } from '../core/function/shelllessImpl.ts';
 import type { AnyData } from '../data/dataTypes.ts';
-import { RefOnGPU } from '../data/ref.ts';
+import { RefOperator } from '../data/ref.ts';
 import type { Snippet } from '../data/snippet.ts';
 import { isPtr } from '../data/wgslTypes.ts';
 import { WgslTypeError } from '../errors.ts';
@@ -50,7 +50,7 @@ export class ShelllessRepository {
     }
 
     const argTypes = (argSnippets ?? []).map((s, index) => {
-      if (s.value instanceof RefOnGPU) {
+      if (s.value instanceof RefOperator) {
         if (!s.value.ptrType) {
           throw new WgslTypeError(
             `d.ref() created with primitive types must be stored in a variable before use`,

packages/typegpu/src/tgsl/wgslGenerator.ts

@@ -42,7 +42,7 @@ import {
 import type { ShaderGenerator } from './shaderGenerator.ts';
 import type { DualFn } from '../data/dualFn.ts';
 import { INTERNAL_createPtr, ptrFn } from '../data/ptr.ts';
-import { RefOnGPU, RefOperator } from '../data/ref.ts';
+import { RefOperator } from '../data/ref.ts';
 import { constant } from '../core/constant/tgpuConstant.ts';
 
 const { NodeTypeCatalog: NODE } = tinyest;
@@ -241,7 +241,7 @@ ${this.ctx.pre}}`;
       const lhsExpr = this.expression(lhs);
       const rhsExpr = this.expression(rhs);
 
-      if (rhsExpr.value instanceof RefOnGPU) {
+      if (rhsExpr.value instanceof RefOperator) {
         throw new WgslTypeError(
           stitch`Cannot assign a ref to an existing variable '${lhsExpr}', define a new variable instead.`,
         );
@@ -780,7 +780,7 @@ ${this.ctx.pre}else ${alternate}`;
         );
       }
 
-      if (eq.value instanceof RefOnGPU) {
+      if (eq.value instanceof RefOperator) {
         // We're assigning a newly created `d.ref()`
         if (eq.value.ptrType) {
           throw new WgslTypeError(