Skip to content

Values and borrows ​

This page is the one idea that makes Weft different from TypeScript. Read it before the rest.

Every value is a copy ​

Assigning, passing, storing, returning and capturing a value all give the receiver its own value. Changing one never changes another:

weft
type Point = { x: number, y: number }

export fn demo(): boolean {
  let a = Point { x: 1, y: 2 }
  let mut b = a
  b.x = 10
  return a.x == 1
}

demo() returns true. In JavaScript, a and b would be one object and a.x would be 10.

The same holds inside collections. Putting a list into another list puts in a copy:

weft
export fn nested(): number[] {
  let row: number[] = [1, 2, 3]
  let mut grid = [row]
  grid[0].push(4)
  return row
}

nested() returns [1, 2, 3].

Copies are cheap. A copy shares the original's storage until one side writes, and then only the level that changes is copied. A value that only one place holds is changed in place, so a loop of push calls stays fast.

What this guarantees ​

weft
type Cart = { items: string[] }

export fn checkout(cart: Cart): number {
  let snapshot = cart
  // Nothing below can change `snapshot`: it's a value, not a pointer into `cart`.
  return snapshot.items.length
}

export fn same(): boolean {
  return [1, [2, 3]] == [1, [2, 3]]
}
  • No aliasing. If you hold a value, nobody else can change it.
  • No identity. == compares contents, because there is nothing else to compare.
  • No cycles. A value can't contain itself, so memory is freed by reference counting, as soon as the last holder lets go. There is no garbage collector and no pauses.

Changing a caller's value: mut and & ​

A plain parameter is a read-only borrow: the function sees the caller's value without a copy, and can't change it.

rejected by the compiler (E3001)
weft
type Todo = { title: string, done: boolean }

export fn finish(t: Todo) {
  t.done = true
}

To change the caller's value, the parameter says mut, and the caller passes the place with &:

weft
type Todo = { title: string, done: boolean }

fn finish(mut t: Todo) {
  t.done = true
}

export fn demo(): Todo[] {
  let mut todos = [Todo { title: "Write the docs", done: false }]
  finish(&todos[0])
  return todos
}

The & is required, and it is the only way a call changes something you hold. Reading a call tells you what it can change:

rejected by the compiler (E3012)
weft
type Todo = { title: string, done: boolean }

fn finish(mut t: Todo) {
  t.done = true
}

export fn demo(): Todo {
  let mut todo = Todo { title: "Write the docs", done: false }
  finish(todo)
  return todo
}

& takes a place: a let mut binding, a mut parameter, component state, followed by any .field or [index] steps (&todos[i].title). A let, a plain parameter or the result of a call isn't a place.

Methods that change their receiver ​

Built-in methods that change a list, map or set (push, sort, set, delete…) borrow their receiver without a written &. The receiver must still be a place.

Your own functions can be called as methods too. x.f(args) calls a function f whose first parameter takes x. When that parameter is mut, the call borrows x:

weft
type Todo = { title: string, done: boolean }

fn toggle(mut t: Todo) {
  t.done = !t.done
}

export fn demo(): boolean {
  let mut todo = Todo { title: "Ship", done: false }
  todo.toggle()
  return todo.done
}

todo.toggle() is toggle(&todo).

One rule: borrows don't overlap ​

A borrow lives only for the call that takes it. It can't be stored, returned or kept by a closure. That leaves one rule to check: two & arguments of one call can't overlap.

rejected by the compiler (E3003)
weft
fn swap(mut a: number, mut b: number) {
  let t = a
  a = b
  b = t
}

export fn demo(): number {
  let mut n = 1
  swap(&n, &n)
  return n
}

Distinct constant indexes don't overlap, so swap(&xs[0], &xs[1]) is fine. For variable indexes the compiler can't tell, so use the list's own method:

weft
export fn demo(i: number, j: number): number[] {
  let mut xs = [1, 2, 3]
  xs.swap(i, j)
  return xs
}

There are no lifetimes to write and no borrow checker to satisfy beyond this.

Why Weft works this way ​

  • Writes are visible in the text. Only a let mut, a mut parameter or state can change at all, and it changes only where the code assigns to it, calls a changing method on it, or passes it with &. The compiler uses exactly this to know what each handler writes and what each piece of the screen reads (Components and reactivity).
  • Edits stay local. When a person or an AI edits one function, the only data it can change is what it was handed with &. There is no distant object that a change can reach through a shared reference. That is what makes it safe to let people, and agents working for them, edit a running app.
  • Fast without a collector. Reference counting frees memory deterministically, and unique values are changed in place.
RustWeft
&Ta plain parameter (the default)
&mut Ta mut parameter, passed with &x
an owned value, Cloneevery assignment, which costs nothing until one side writes

Weft is in development. The reference is the spec as it stands today.