2d:null 2e:["$","title",null,{"children":"Session 1.3b - Advanced Javascript | Carlos Sandoval Olascoaga | Observable"}] 33:T42d,md`For larger datasets, you’ll need to host your data somewhere. A good choice is [GitHub Gist](https://gist.github.com). Simply drag-and-drop a file from your desktop onto the browser to upload it to GitHub:

Click the button to create the gist. Then on the next page, right-click the “Raw” button for your file, and select “Copy Link Address”.

Now you have a link to your file like this: https://gist.github.com/mbostock/4063570/raw/11847750012dfe5351ee1eb290d2a254a67051d0/flare.csv Unfortunately, this link doesn’t support [CORS](https://enable-cors.org/), so you’ll need to replace the “gist.github.com” domain with “gist.githubusercontent.com”: https://gist.githubusercontent.com/mbostock/4063570/raw/11847750012dfe5351ee1eb290d2a254a67051d0/flare.csv At last! You have a publicly-accessible data URL.`34:T544,md`## Introduction to Promises A promise represents a value that is not yet known, but that *will* be known in the future. For example, when you load a file from a web server into a browser, the file’s contents aren’t available right away: the file must first be transferred over the network. Rather than locking up while the file is downloading, browsers download asynchronously. This asynchronous design, essential for fluid interaction and parallel downloads, introduces complexity: code that depends on promised values must wait until the values are resolved rather than running immediately. Fortunately, JavaScript’s [Promise API](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Using_promises) (and its companion \`await\` operator), make it easier to work with asynchronous values. Promises are often not created by you. Instead, an asynchronous library method might return a promise, and you need to wait for the promise to resolve (or reject). D3’s [d3.csv](https://github.com/d3/d3-fetch/blob/master/README.md#csv) is just such a function: it [fetches](https://fetch.spec.whatwg.org/) a file from another server, parsing [comma-separated values](https://en.wikipedia.org/wiki/Comma-separated_values) into a structured array of objects. d3.csv can’t return the array right away, so it instead returns a Promise.`35:T500,viewof point = { const height = width / 2; const context = DOM.context2d(width, height); const projection = d3.geoEqualEarth().fitSize([width, height], {type: "Sphere"}); const path = d3.geoPath(projection, context); let mousedown = false; context.beginPath(), path(graticule), context.strokeStyle = "#ccc", context.stroke(); context.beginPath(), path(land), context.fill(); context.beginPath(), path(sphere), context.strokeStyle = "#000", context.stroke(); context.lineWidth = 2, context.strokeStyle = "#f00"; const image = context.getImageData(0, 0, context.canvas.width, context.canvas.height); function render(coordinates) { context.canvas.value = coordinates; context.clearRect(0, 0, width, height); context.putImageData(image, 0, 0); context.beginPath(), path({type: "Point", coordinates}), context.stroke(); } context.canvas.onmousedown = event => { mousedown = true; context.canvas.onmousemove(event); }; context.canvas.onmousemove = ({layerX, layerY}) => { if (!mousedown) return; render(projection.invert([layerX, layerY])); context.canvas.dispatchEvent(new CustomEvent("input")); }; context.canvas.onmouseup = event => { mousedown = false; }; render([0, 0]); return context.canvas; }36:[{"id":"0fab0237a166024cc8de73fd5d3a80f8b9dbbe16297e265b6b06b5437eee4fc1f5b5ff81baedd1a8eddb5a278b199a9e80046d66114eeef68cac2898fe188b07","href":"https://static.observableusercontent.com/files/0fab0237a166024cc8de73fd5d3a80f8b9dbbe16297e265b6b06b5437eee4fc1f5b5ff81baedd1a8eddb5a278b199a9e80046d66114eeef68cac2898fe188b07","name":"qr_codes.csv","type":"text/csv","lastModified":1706285172670.98,"size":2223}] 31:{"id":"5a13ef5132921419","slug":"session-1-3b-advanced-javascript","title":"Session 1.3b - Advanced Javascript","thumbnail":"3f3516d9514331a83211504353e5edaed58b1c04c464d3152d0467db80be42c8","access_level":"public","create_time":"$D2024-01-26T16:06:12.670Z","update_time":"$D2024-01-26T16:12:36.209Z","view_time":null,"first_public_time":"$D2024-01-26T16:06:12.670Z","has_unpublished_edits":null,"fork":{"id":"8b7e71b3cb0c6439","slug":"4-182-week-2b-advanced-javascript","title":"Week 2b - Advanced Javascript","owner":{"id":"7be24cbfb3203dab","login":"cesandoval","name":"Carlos Sandoval Olascoaga"}},"stars":0,"starred":false,"owner":{"type":"team","id":"7be24cbfb3203dab","login":"cesandoval","name":"Carlos Sandoval Olascoaga","avatar_url":"https://avatars-next.observableusercontent.com/932dec7ee5c2e52477e2a80482b05fdab063507b7c3029a5f6bc1ff0e03bbc36","tier":"starter_2024"},"version":564,"publish_version":null,"role":null,"authored":false,"authors":[{"type":"individual","id":"7750258d506a87a9","login":"cesandoval","name":"Carlos Sandoval Olascoaga","avatar_url":"https://avatars-next.observableusercontent.com/932dec7ee5c2e52477e2a80482b05fdab063507b7c3029a5f6bc1ff0e03bbc36","tier":null}],"members":[{"type":"individual","id":"7750258d506a87a9","login":"cesandoval","name":"Carlos Sandoval Olascoaga","avatar_url":"https://avatars-next.observableusercontent.com/932dec7ee5c2e52477e2a80482b05fdab063507b7c3029a5f6bc1ff0e03bbc36","tier":null,"role":"editor"}],"comments":[],"custom_thumbnail":false,"trashed":false,"lapsed":null,"subscribed":null,"forks":0,"collection":{"id":"d895c4b27c4da933","slug":"inam5983-design-urban-tech-and-community-participation","title":"INAM5983: Design, Urban Tech and Community Participation","owner":{"id":"7be24cbfb3203dab","login":"cesandoval","name":"Carlos Sandoval Olascoaga"}},"type":"notebook","body":{"title":"Session 1.3b - Advanced Javascript","cells":[{"id":141,"value":"md`# Session 1.3b - Advanced Javascript`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":189,"value":"md`## Introduction to Imports\n\nObservable lets you quickly reuse code by importing cells from any public notebook.\n\nTo demonstrate, take Mike Bostock's notebook of color scales used to visualize quantitative data. This notebook defines a *ramp* function that returns a canvas for a given *color* function, where the *color* function returns a color for a given ${tex`t \\in [0,1]`} from left to right. To create the dreaded angry rainbow, import and call *ramp*:`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":190,"value":"import {ramp} from \"@mbostock/color-ramp\"","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":483,"value":"myColor = d3.interpolateLab(\"red\", \"blue\")","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":462,"value":"ramp(d3.interpolateLab(\"red\", \"blue\"))","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":194,"value":"ramp(t => `hsl(${t * 360}, 100%, 50%)`)","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":469,"value":"import { multiply_this } from \"@cesandoval/session-1-3a-introduction-to-javascript-part3\"","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":471,"value":"multiply_this(1,2)","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":197,"value":"md`You could instead copy-paste the *ramp* function from that notebook into this one—it’s only a few lines of code. But imports have a few advantages.\n\nFirst, the cell you want to reuse may depend on other cells. If you copy-paste, you have to copy-paste those other cells too, and make sure that they don’t conflict with existing cells in your notebook. If you import, the dependencies are loaded automatically, so you don’t have to think about it.\n\nFor example, consider a notebook on an interrupted Sinu–Mollweide map projection that requires the D3 and TopoJSON libraries, along with geometry representing the Earth’s landmasses. You can import the map and display it without worrying about how the sausage is made.`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":198,"value":"import { map } from \"@mbostock/interrupted-sinu-mollweide\"","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":202,"value":"map","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":205,"value":"md`Second, by importing, it’s easier to keep the reused code up-to-date. Imports target the latest published version, so if Mike improves his map notebook, the new map will automatically appear here.\n\n(The risk of importing the latest version is that your notebook may break if the imported notebook changes in a non-backwards-compatible way. Observable also supports versioned imports, however version numbers aren’t currently exposed in the user interface, so for now you must specify the version manually. In the future, imports will be pinned to the latest published version at the time you write the import statement, and can be re-pinned on-demand.)`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":209,"value":"md`Third, and most excitingly, Observable imports let you inject dependencies using import-with! This lets you “rewrite” imported code as you might do when copy-pasting, without the problems of code duplication.\n\n`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":225,"value":"md`\nBest of all, because [Observable is reactive](/@mbostock/how-observable-runs), you can even inject dynamic definitions into code that was previously static!\n`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":227,"value":"md`Here are a few additional nuances of imports:\n\nLike [ES imports](http://exploringjs.com/es6/ch_modules.html), Observable imports are live bindings. If you import a value that changes over time ([a generator cell](/@mbostock/generator-cells-functions-and-objects)), such as a countdown to a certain date in the future, the imported value will change over time, too.`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":230,"value":"import {interval} from \"@mbostock/countdown\"","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":233,"value":"interval","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":236,"value":"md`You can only import named cells. No anonymous cells allowed! If a notebook uses side effects, as is sometimes common with anonymous cells, you must name and import the cells with side effects, too.\n\nImported cells are lazily evaluated: if you import a cell but you don’t reference it anywhere, the code won’t run. Try uncommenting the cell below and then hit Shift-Enter. Notice that the generator *i* begins at zero—it doesn’t start until referenced.`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":239,"value":"// i","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":252,"value":"import {i} from \"@mbostock/generator-cells-functions-and-objects\"","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":259,"value":"md`Also like ES imports, only the cells you import are available (*bound*) in the local notebook, even if those cells depend on other cells. Those dependent cells are *run*—they’re just not exposed in the scope of the local notebook.\n\nYou can import the same notebook multiple times and references will resolve exactly. Note, however, that the versions of the imported notebooks must also match, or they are considered different notebooks. (You can also have import cycles, but this is only temporary as in the future all imports will be versioned. And you still can’t have circular cell definitions.)`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":260,"value":"import { map as map2 } from \"@mbostock/interrupted-sinu-mollweide\"","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":264,"value":"map === map2","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":267,"value":"md`You can only import from published notebooks; you can’t import from draft notebooks, even your own. \n\nLastly, imports aren’t intended to replace libraries (like [lodash](https://lodash.com) or [D3](https://d3js.org)); if you want to design, build and support a reusable library, go for it and publish to npm! But if you want a lightweight way to reuse code across notebooks without resorting to copy-paste, reach for import.\n\n---`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":0,"value":"md`## Loading Data into a Notebook\n\nHow do you get data into Observable for analysis and visualization?\n\nFor tiny datasets, you can inline JSON:`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":3,"value":"primes = [2, 3, 5, 7, 11, 13]","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":488,"value":"array1 = [0,1,2,3]","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":7,"value":"md`You can also inline tiny CSV files, if you parse them:`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":9,"value":"mtcars = d3.csvParse(`name,mpg,cyl,disp,hp,drat,wt,qsec,vs,am,gear,carb\nMazda RX4,21,6,160,110,3.9,2.62,16.46,0,1,4,4\nMazda RX4 Wag,21,6,160,110,3.9,2.875,17.02,0,1,4,4\nDatsun 710,22.8,4,108,93,3.85,2.32,18.61,1,1,4,1\nHornet 4 Drive,21.4,6,258,110,3.08,3.215,19.44,1,0,3,1\nHornet Sportabout,18.7,8,360,175,3.15,3.44,17.02,0,0,3,2\nValiant,18.1,6,225,105,2.76,3.46,20.22,1,0,3,1\nDuster 360,14.3,8,360,245,3.21,3.57,15.84,0,0,3,4\nMerc 240D,24.4,4,146.7,62,3.69,3.19,20,1,0,4,2\n`)","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":109,"value":"md`Once you’ve defined a dataset, you can reference it like a normal value:`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":112,"value":"The first prime is ${primes[0]}.","pinned":true,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","output":"","database":"$undefined"},{"id":118,"value":"The first car is a ${mtcars[0].name} with ${mtcars[0].hp} horsepower.","pinned":true,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","output":"","database":"$undefined"},{"id":122,"value":"d3.median(mtcars, d => d.mpg) // The median miles per gallon.","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":15,"value":"$33","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":492,"value":"myPath = 'https://gist.githubusercontent.com/cesandoval/4c20520455b90ec8416c2c18747cc899/raw/b5b9c347ff0fdc4dc09214804a87b09ee9deb3e1/qr_codes.csv'","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":495,"value":"myCSV = d3.csv(myPath)","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":37,"value":"flare = d3.csv(\"https://gist.githubusercontent.com/mbostock/4063570/raw/11847750012dfe5351ee1eb290d2a254a67051d0/flare.csv\")","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":30,"value":"md`There are also many public APIs available on the web. For example, [CryptoCompare](https://www.cryptocompare.com/api/) provides a free API for cryptocurrency price data. Todd Motto maintains a nice list of [free public APIs](https://github.com/toddmotto/public-apis) you can peruse. Don’t forget: you can also use [WebSockets](https://developer.mozilla.org/docs/Web/API/WebSockets_API) to connect to realtime data streams!\n\nObservable also provides a handful of [“toy” datasets](https://github.com/observablehq/datasets) which you can load via \\`require\\`. These can be useful if your goal is to experiment with visualization or analysis techniques, rather than to look at a specific dataset. For example, here is a table of Apple’s stock price from 2007 to 2012:`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":77,"value":"aapl = require(\"@observablehq/aapl@0\")","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":85,"value":"md`If you transform your data within a notebook, you can use DOM.download to save a local copy of your file. This lets you load the already-transformed data in the future, rather than needing to transform it again on every load, which is particularly useful if your transformed data is much smaller than the original. For example, you can download the Flare data (loaded above) as CSV by clicking the button below:`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":88,"value":"DOM.download(\n new Blob([d3.csvFormat(flare)], {type: \"text/csv\"}),\n \"flare.csv\"\n)","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":131,"value":"md`Lastly, you can **read local files** in your notebooks too, without hosting! But the downside of local files is that you’re only able to read a local file if you have it… well, locally, whereas hosted files will also be available to your readers.`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":150,"value":"md`### Reading Local Files\n\nYou can read files from your local file system in Observable using file cell:`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":547,"value":"qr_codes = await FileAttachment(\"qr_codes.csv\").csv({typed: \"auto\"})","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"qr_codes","database":"$undefined"},{"id":152,"value":"viewof image = html``","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":157,"value":"md`A [File](https://developer.mozilla.org/docs/Web/API/File) is a [Blob](https://developer.mozilla.org/docs/Web/API/Blob), so one way to read a file is to use [URL.createObjectURL](https://developer.mozilla.org/docs/Web/API/URL/createObjectURL). This is useful, for example, with images. (Don’t forget to [revoke](https://developer.mozilla.org/docs/Web/API/URL/revokeObjectURL) your URLs, though, say using [Generators.disposable](https://github.com/observablehq/notebook-stdlib/blob/master/README.md#Generators_disposable).)`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":159,"value":"html`

`","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":161,"value":"md`You can also read a file using a [FileReader](https://developer.mozilla.org/docs/Web/API/FileReader). Observable’s [standard library](https://github.com/observablehq/notebook-stdlib/blob/master/README.md) includes several convenience methods for reading files.`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":164,"value":"Files","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":167,"value":"md`If the file is text, use Files.text to obtain a promise to a String.`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":169,"value":"viewof text = html``","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":172,"value":"Files.text(text)","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":175,"value":"md`For a binary file, use Files.buffer for a promise to an ArrayBuffer.`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":177,"value":"viewof binary = html``","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":180,"value":"Files.buffer(binary)","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":269,"value":"$34","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":270,"value":"data = d3.csv(\"https://gist.githubusercontent.com/mbostock/ddc6d50c313ebe6edb45519f43358c6c/raw/c443ed14c34c5c1b544949a546dd9d0acd05bad3/temperatures.csv\")","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":274,"value":"md`Did you see the promise? Observable implicitly awaits promises across cell boundaries, so you often don’t need to deal with a promise directly. Cells can return promises, and other cells can simply refer to the values and they’ll run when the promise resolves.`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":275,"value":"data.map(d => +d.Year)","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":279,"value":"md`Observable’s standard library has few built-in methods related to Promises.`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":281,"value":"Promises","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":284,"value":"md`Promises.delay returns a promise that resolves to a given value after a given duration. The promise below resolves to a greeting after three seconds.`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":285,"value":"Promises.delay(3000, \"Hello, world!\")","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":289,"value":"md`Promises.tick is similar, except it returns a promise that resolves at the next given interval. Here’s how to make a counter that increments every second:`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":293,"value":"{\n let i = 0;\n while (true) {\n yield Promises.tick(1000, ++i);\n }\n}","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":297,"value":"md`You can use the \\`await\\` operator to pause the execution of code in the current cell while you wait for a promise to resolve:`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":298,"value":"{\n let greeting = await Promises.delay(3000, \"Hello, \");\n return greeting + \"world!\";\n}","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":302,"value":"md`Equivalently, you can use *promise*.then to chain promises:`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":303,"value":"Promises.delay(3000, \"Hello, \").then(greeting => greeting + \"world!\")","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":309,"value":"md`## Introduction to Generators`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":313,"value":"md`Observable uses [generators](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Generator) to represent values that change over time. Generators enable interaction, animation, realtime data streaming, and all the other exciting, dynamic capabilities of Observable notebooks.\n\nThe simplest generator is a cell that [yields](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Operators/yield) a single value.`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":317,"value":"yield 13","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":503,"value":"yield 'yielding text'","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":320,"value":"md`This behaves no differently than a plain expression cell.`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":321,"value":"13","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":325,"value":"md`A more interesting case is a cell that repeatedly yields [promises](/@mbostock/introduction-to-promises) to control when each new value resolves. (That is, to specify *when* the cell’s value changes.) For example, to define a value that starts at zero and increments once per second, use a while-true loop and [Promises.delay](https://github.com/observablehq/notebook-stdlib/blob/master/README.md#Promises_delay).`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":326,"value":"{\n let i = 0;\n while (true) {\n yield Promises.delay(10, ++i);\n }\n}","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":330,"value":"md`Or, use an [async generator](/@mbostock/introduction-to-asynchronous-iteration) cell by combining [await](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Operators/await) and yield.`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":331,"value":"{\n let i = 0;\n while (true) {\n await Promises.delay(1000);\n yield ++i;\n }\n}","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":339,"value":"md`Observable waits until the yielded value resolves before pulling the next value from the generator. The generator cell is magically suspended (paused) until Observable requests the the next value, at which point the cell resumes exactly where it left off. In effect, there’s an implicit await when you yield a promise.`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":335,"value":"{\n const div = html`

`;\n yield div;\n while (true) {\n div.style.background = \"red\";\n yield Promises.delay(1000, div);\n div.style.background = \"green\";\n yield Promises.delay(1000, div);\n div.style.background = \"blue\";\n yield Promises.delay(1000, div);\n }\n}","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":342,"value":"md`When using an infinite loop, don’t forget to yield! If you never yield, the page will hang and you’ll need safe mode to repair your notebook.\n\nPer the [iterator protocol](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Iteration_protocols#The_iterator_protocol), the return value of a generator is not considered part of the sequence of values; it is ignored.`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":343,"value":"{\n yield 1;\n yield 2;\n yield 3;\n return \"ignored\"; // It’s ignored!\n}","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":347,"value":"md`Generators that yield promises are the basis for [interactive views](/@mbostock/a-brief-introduction-to-viewof) in Observable. [Generators.observe](https://github.com/observablehq/notebook-stdlib/blob/master/README.md#Generators_observe) takes a push-based data source—code that invokes a callback function whenever there is new data—and converts it to a pull-based generator that yields promises. These promises resolve with the passed value when *next* is called.`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":348,"value":"input = html``","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":508,"value":"viewof input2 = html``","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":513,"value":"input2","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":352,"value":"Generators.observe(next => {\n // Yield the input’s initial value.\n next(input.value);\n\n // Define an event listener to yield the input’s next value.\n const inputted = () => next(input.value);\n\n // Attach the event listener.\n input.addEventListener(\"input\", inputted);\n\n // When the generator is disposed, detach the event listener.\n return () => input.removeEventListener(\"input\", inputted);\n})","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":355,"value":"md`(This pattern is based on JavaScript’s proposed [Observable type](https://github.com/tc39/proposal-observable/blob/master/README.md).)\n\nIt’s tedious to add and remove event listeners to observe an input’s value, so the standard library provides [Generators.input](https://github.com/observablehq/notebook-stdlib/blob/master/README.md#Generators_input) as a convenience method on top of Generators.observe for observing inputs. This method has various smarts for dealing with different input types, such as ranges, checkboxes, and textareas.`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":356,"value":"Generators.input(input)","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":360,"value":"md`Yet you rarely need to use Generators.input directly: Observable’s [viewof operator](/@mbostock/a-brief-introduction-to-viewof) will do it for you! If you name a cell *viewof value*, Observable implicitly creates a second (hidden) cell named *value* using Generators.input.`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":361,"value":"viewof value = html``","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":519,"value":"width","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":365,"value":"md`In addition to generator functions, the Observable standard library has several built-in reactive variables that are implemented with generators. There’s *width*, which represents the current page width and updates when the window resizes.`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":368,"value":"width","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":379,"value":"md`And *now* represents the current time as elapsed milliseconds since UNIX epoch, updating sixty times a second.`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":375,"value":"now","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":383,"value":"md`## Introduction to Views\n\nIf *generators* are how you express values that change over time in Observable, then *views* are a special type of generator that is controlled by the user interface.\n\nA view consists of two parts:\n\n1. The *view*, which is typically a DOM element.\n\n2. The *value*, which is any JavaScript value.\n\nFor example, a view could be an HTML range input whose value is a number:`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":384,"value":"viewof x = html``","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":526,"value":"viewof y = html``","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":529,"value":"y","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":388,"value":"x","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":391,"value":"md`A view could be a text input whose value is a string:`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":392,"value":"viewof message = html``","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":396,"value":"message","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":399,"value":"md`A view could be a dropdown menu to choose from a set of options:`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":400,"value":"viewof color = html``","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":404,"value":"color","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":409,"value":"md`But views aren’t limited to built-in HTML input types! A view can have any visual representation you desire, and any value, too. For example, a view could be a map that lets you specify any point on Earth:`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":407,"value":"$35","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":427,"value":"point","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":430,"value":"md`If there is some value that you would like the user to control in your notebook, then usually the right way to represent that value is as a view. By defining your interactive values using views, you don’t need to manage event listeners and mutable state—you can simply refer to dynamic values, and whenever these values change (for whatever reason), your code will be re-evaluated by the runtime. For example, you have chosen ${color} as your color in the menu above; change it and watch this cell update.\n\nA view’s value is exposed as *element*.value. For example, here I’ll define a static view (one whose value never changes), for the purposes of illustration:`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":432,"value":"viewof silly = {\n const element = html`

I am a silly view!

`;\n element.value = \"I am a silly value.\";\n return element;\n}","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":435,"value":"silly","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":438,"value":"md`To trigger the re-evaluation of any cell that references a view’s value, the view must emit an *input* event. For example, here’s another silly view that counts how many times you click on it:`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":439,"value":"viewof count = {\n const element = html`

🤪

`;\n element.value = 0;\n element.onclick = () => {\n ++element.value;\n element.dispatchEvent(new CustomEvent(\"input\"));\n };\n return element;\n}","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":445,"value":"count","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":424,"value":"md`---\n\n## Appendix`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":411,"value":"sphere = ({type: \"Sphere\"})","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":413,"value":"graticule = d3.geoGraticule10()","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":415,"value":"land = topojson.feature(world, world.objects.land)","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":417,"value":"world = d3.json(await require.resolve(\"world-atlas@1/world/50m.json\"))","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":419,"value":"topojson = require(\"topojson-client@3\")","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"}],"files":"$W36","stdlib":"1","titling":"auto"}} 32:"$31:body"