- Vals are the primitive of Val Town like Tweets are the primitive of Twitter.
- Vals are snippets JavaScript or TypeScript that defines a single, named value.
- Every change in a val is saved as a new version.
- There are two kinds of vals: JSON vals and Function Vals.
- The two kinds of Vals
- JSON Vals
- Function Vals
- Run Your First Val
- Val Names
- Publishing a Val
- Referencing a Val
- Referencing Private Vals
- Mutable State / Persistence
- Versions
- Deleting a Val
- Linking to a Val
- Embedding a Val
- Included environment
- Keyboard Shortcuts
- Limitations
The two kinds of Vals
JSON Vals
A JSON Val is created when you evaluate some JavaScript or TypeScript. The result is saved as JSON and can be referenced in other Vals. JSON Vals are evaluated at a point in time. Their value is only recomputed when you re-evaluate them manually. JSON vals can also display logs and errors.
Function Vals
A function val is created when you save a JavaScript/TypeScript function. All calls to function vals are tracked and can be viewed by the caller of the function by clicking the ▶️ button in the bottom-right corner of a Val.
Run Your First Val
- Press Inspiration to cycle through a list of example expressions you can run.
- Press Run example to run that example.
- Feel free to edit any of the examples or run any JavaScript code you want.
Val Names
Vals are named like a variable let myName = ...
. If you don’t supply a name, one will be assigned.
You can only have a single-top level binding in a Val. If you have more than one statement in your code at the top-level, we will automatically wrap your code in an IIFE. For example, when you run this:
It becomes this:
You can then reference @me.untitled_RfqtWbJz
in other Vals and it will refer to 3
.
Publishing a Val
All Vals default to private. You can publish a Val by clicking the 🔒 next to its name. Anyone can see and run public Vals. Nobody will be able to inspect any of your private state (either a private Val or a secret) in a public Val. Publishing your Val makes it accessible via API, inside and outside of Val Town.
Referencing a Val
A val can reference other vals, much like a tweet can reference other tweets. For example, this val references the the prior example:
Once you type @
you will get helpful autocomplete on handles and then val names.
Referencing Private Vals
Anyone can reference any public val. Private vals can only be accessed by their authors. For example, I created a private val, example3
. You won’t be able to see or reference example3
but I can! I can even export a val that uses example3
, still without making example3
public as shown below.
Mutable State / Persistence
You can edit vals under your @username namespace inside other vals. Mutable state / persistence is just another kind of val.
At the end of a val’s execution any of state under the author’s namespace that has been edited will be saved as a new version of that val. For example, I have a public val @stevekrouse.exampleState
:
I can mutate this state from another val:
If you call this @stevekrouse.exampleStatePlusPlus()
, it will fail to mutate my state. You don’t have the permissions for that. However because I exported this function, you can call it via the API and that will mutate my state:
Versions
Vals are immutable but you can publish new versions of vals. Versions start at v0
and go up from there. When you reference a val, you always get the most recent version. You can toggle which version you’re looking at via the drop down menu next to the val’s name.
In the future, we will allow you to specifically reference a version, such as @stevekrouse.example3_v2
.
Deleting a Val
You can delete a val you created via the 🗑️ button. You can either delete a specific version or all versions. You can restore any deleted val version at /settings/versions.
Linking to a Val
You can get a link to a val in the Share menu or via val.town/v/@username.valName
.
Embedding a Val
You can get an embed link to a val in the Share menu or via val.town/embed/@username.valName
. You can paste that link into a tool like Notion and it’ll just work. For other context, you may need to use an iframe
.
Included environment
Vals are evaluated on a limited subset of deno. It includes:
fetch
to make HTTP requestsBuffer
- to encode/decode strings- dynamic
import
from npm and https
You can view the entire environment we support here.
Keyboard Shortcuts
- ctrl/cmd-enter to run a val
- ctrl/cmd-k to search for a val
- ctrl/cmd-click to go to a val reference or URL
Limitations
The limitations on vals can be found on our pricing page.