http://localhost:8000 looks like this:\n![\"Fresh](\"https://deno-blog.com/img/blog/using_deno-puppeteer/fresh_starter_page.png\")
The fresh-testing-library is a\nnew unit testing utility for Deno Fresh. Until now testing a Fresh application\nused the built-in Deno test runner with Deno.test and std/testing utilities\nfor verifying low-level logic and the\nDeno-Puppeteer or\nAstral libs for end-to-end testing. The\nfresh-testing-library fills the niche between the other options to allow\nisolated testing of fresh components, middleware and route handlers.
fresh-testing-library creates a thin wrapper around the\nPreact Testing Library\nwhich is built upon the\nDOM Testing Library.\nAll of them including fresh-testing-library share an API under the\nTesting Library moniker.
The fresh-testing-library also adds utilities for testing Fresh route\nhandler's, route components and middleware. Those are under the server.ts\nmodule while the component testing library code is in the component.ts module.\nBoth can also be accessed via the mod.ts module.
The Testing Library philosophy is to create tests that interact with the\napplication the same way an app user would do. To do so, Testing Library tests\nhone in on verifying DOM elements.
\nTesting library also focusses on accessibility, offering a number of functions\nto find elements by accessible attributes.
\nThe fresh-testing-library is registered as a Deno third-party library under\nthe \"https://deno.land/x/fresh_testing_library\" URL.
This blog post will focus on how to use the fresh-testing-library. With that\nin mind, I have created example code in several repos. They are:
Using fresh-testing-library for a component test requires the Deno test runner\nand the testing/bdd.ts module of the Deno standard library. The bdd module\nadds functions that are familiar to testing in Node.js using libraries like\nJest or Mocha. They include\ndescribe, it, beforeAll, afterAll, beforeEach and afterEach.
Here is a simple annotated example of a fresh-testing-library component test\nthat illustrates test setup and code:
// Adapted from Todo.test.tsx in Fresh\n// signals blog post repo\nimport {\n cleanup,\n fireEvent,\n render,\n setup,\n} from \"https://deno.land/x/fresh_testing_library/component.ts\";\nimport {\n afterEach,\n beforeAll,\n describe,\n it,\n} from \"https://deno.land/std/testing/bdd.ts\";\nimport { assertEquals } from \"https://deno.land/std/assert/mod.ts\";\nimport Todo from \"../islands/Todo.tsx\";\n\ndescribe(\"Todo.tsx test\", () => {\n // setup the jsdom environment\n beforeAll(setup);\n // unmount rendered component after each test\n afterEach(cleanup);\n\n it(\"should display todo...\", () => {\n // assign the component's text content via a prop\n const text = \"Foo\";\n // render a component's DOM markup\n const { getByText } = render(<Todo text={text} index={1} />);\n // find an HTML element using the rendered component's text content\n const textElement = getByText(text);\n // verify element's text content\n assertEquals(textElement.textContent, text);\n });\n});Functions in the assert module of the Deno standard library works for fresh-testing-library verifications. Anyone who has done any Deno testing will be familiar with them. However, in version 0.10.0 of the fresh-testing-library the expect function was added to components.ts. Like others, this function comes from Preact Testing Library.
The expect function has a number of matcher functions attached to it that do the verification. They have a Jasmine-like API. Some of them behave similarly to the Deno-native assert functions.
Here are some expect function matchers and their Deno-native equivalent (if there is one):
| expect function matcher | \nDeno-native assert | \n
|---|---|
| toBeInTheDocument() | \nassertExists()/assertEquals() | \n
| toBe() | \nassertEquals() | \n
| not.toBe() | \nassertNotEquals() | \n
| toBeTruthy() | \nassert() | \n
| toBeFalsy() | \nassertFalse() | \n
| toBeEmptyDOMNode | \n[none] | \n
| toBeRequired | \n[none] | \n
Here's a simple example how to use expect with fresh-testing-library:
import { expect } from \"https://deno.land/x/fresh_testing_library/expect.ts\";\n it(\"should find 'Hello World' text in document\", () => {\n const { queryByText } = render(<div>Hello World</div>);\n expect(queryByText(\"Hello World\")).toBeInTheDocument();\n // using getByText will error out before matchers are called\n expect(queryByText(\"foobar\")).not.toBeInTheDocument();\n });Note that you can use the not matcher to negate a matcher that it calls.
The expect function contains a number of matcher functions that check on function calls (like expect(foo).toBeCalled()). To get them to work, you need to mock the functions. The jest-mock library's fn function was incorporated into the expect.ts module in v0.11.0. You can also use fn to mock return values. Here's a simple example how that works:
import { expect, fn } from \"https://deno.land/x/fresh_testing_library/expect.ts\";\n it(\"should be able to use mock functions\", () => {\n const add = (num1: number, num2: number): number => num1 + num2;\n expect(add(2,6)).toBe(8);\n // create mock impl of add\n const mockAdd = fn(add).mockImplementation((num1, num2) => num1 * num2);\n const sum = mockAdd(2, 2);\n expect(sum).toBe(4);\n expect(mockAdd).toBeCalled();\n expect(mockAdd).not.toBeCalledTimes(2);\n expect(mockAdd(3, 5)).toBe(15);\n expect(mockAdd).toBeCalledWith(3, 5);\n });If you need to mock a function that is a dependency of the component-under-test, send the mock function into the component as a prop. The real (non-mock) dependency would be sent in from the parent component so the component will work correctly at runtime.
\nThe expect.test.tsx file in this blog's repo has some examples of how to use expect and fn.
There are also other functions from the jest-mock library incorporated into the expect.ts module. They include mocked, replaceProperty, and spyOn.
Run fresh-testing-library tests with this command line:
deno test --allow-read --allow-envBoth permission flags are required because the jsdom library is used\ninternally in component tests. You might also need to add other permission flags\ndepending on the code you are testing.
The first thing you need in a fresh-testing-library test is a call to the\nlibrary's render function. It is used to instantiate the component-under-test.\nIts first argument is required and is the JSX representation of a component\nincluding its props.
import { render } from \"https:/deno.land/x/fresh_testing_library/component.ts\";\n// renders component DOM wrapped inside a document.body\nconst screen = render(<Counter count={1} />);The render function returns an object that contains functions for verifying a\ncomponent's content. Instead of returning that object ( screen in this case),\nyou can destructure the functions required to find the content. Here's an\nexample of a text search with getByText destructured from render:
import { render } from \"https:/deno.land/x/fresh_testing_library/component.ts\";\n// renders component DOM wrapped inside a document.body\nconst { getByText } = render(<Counter cont={1} />);\nconst text = getByText(\"Hello World!\");The render function has an optional second argument that is rarely used. For\nmore information, see the\nRenderOptions interface in the preact-testing-library type documentation.
As stated previously, Testing Library libs including fresh-testing-library\nfocus on verifying DOM elements generated by the component-under-test. These\nelements create the UI including interaction components.
Finder functions are found on the RenderResult object that is returned from a\ncall to render.
const screen: RenderResult = render(<Features />);\nconst text = screen.getByText(\"Hello World!\");Discovering DOM elements in a fresh-testing-library test requires use of a\nfinder. Finder function names have three parts:
Combined, the first two parts of a finder function name indicates what the\nfunction returns. Here's how that works:
\n| Finder function | \nMatch Found returns | \nMatch Not Found returns | \n
|---|---|---|
| getBy* | \nmatching element | \nthrows an error | \n
| getAllBy* | \nmatching element array | \nthrows an error | \n
| queryBy* | \nmatching element | \nnull | \n
| queryAllBy* | \nmatching element array | \nempty array | \n
| findBy* | \nresolved Promise (element) | \nrejected Promise | \n
| findAllBy* | \nresolved Promise (element array) | \nrejected Promise | \n
Also note that if you are using the singular 'getBy', 'queryBy' or 'findBy'\nfunctions and more than one element is returned, then an error is thrown.\nConversely, a getAllBy, queryAllBy and findAllBy function returns an array with\na single element if only one matching item exists.
\nI need to interject here that while the table above -- and other documentation -- points out that an element (HTMLElement) gets returned, if the element has child elements (like an HTML form), then the whole node gets returned. However, most of the time you'll want to fashion the finder function to find a single element.
\nThe full name of a finder function specifies how an element is located. Here's\nwhat they are with a 'getBy' prefix (the same functions exist using 'queryBy' or\n'findBy'):
\ngetByAltText - finds the element using the alt attributegetByDisplayValue - finds an input, textarea or select element using\nthe value attribute.getByLabelText - finds the element using the label attribute. Obviously, this is mostly used to locate form elements wrapped in a label.getByPlaceholderText - finds the element using the placeholder attribute\nfound in a text or textarea form element.getByRole - finds the element by its role attribute or implicit role\n(see below).getByTestId - finds an element using the data-testid attributegetByTitle - finds an element using the enclosed titleelement. This is\nbest used with an svg graphic that contains a title child element.All of the finder functions have the same first two arguments. The first one is\nan HTML element which would be obtained from a previous call to a finder\nfunction. Most of the time you will not need this argument.
\nThe second argument is used to match the the HTML element being searched for. It\nis either a number, string, regular expression or a function\n(see next section). The 'ByRole' method only takes specific\nstring values (see below).
\nFinder functions have an optional third argument which is an options object. The\nproperties of that argument is specific to the finder.
\nMost finder functions take a\nTextMatch which\ncan be:
The TextMatch function has optional string and HTMLElement arguments and\nreturns a boolean (true for a match; false for no match). Here's an example\nof a test with functional matching:
it(\"should show source code\", () => {\n const code = \"console.log('Hello World')\";\n const { getByRole, getByText } = render(<CodeBox code={code} />);\n // find code\n const codeElement = getByRole(\"code\");\n // get the text content\n const content = codeElement.textContent;\n // Prism library breaks up code for styling purposes\n assert(\n getByText((content) => content.includes(\"console\")),\n );\n assert(\n getByText((content) => content.includes(\"log\")),\n );\n assert(\n getByText((content) => content.includes(\"Hello World\")),\n );\n});A finder function that takes a TextMatch can contain an options object with an\nexact or normalization property that affects the precision of the match.\nThere is a\nsection in the Testing Library docs that explores these options in detail,\nbut here they are in a nutshell:
exact - (true by default) determines whether the match is case-sensitive or\nnot.normalization - By default whitespace is collapsed when doing a text match. This property\ncan be set to override that behavior.As shown above, the first part of a finder function name indicates what gets\nreturned when you call the function. For that reasons, each one of them has a\nfavored use
\nget* - use to find elements to be able to verify their attributes or\ncontent or invoke an event. You will probably use this most of the time in a\ncomponent test.
\nquery* - should only be used to verify the existence or non-existence of\nan element. Otherwise, a 'get*' finder should be used.
\nFor example, I have a test where I want to make sure that no Todo components\nwill be shown. Each Todo contains a button element. I use queryAllByRole to test for an empty array returned by that function. If I used getAllByRole, an error would be thrown\nif nothing was returned.
// TodoList.test.tsx in Fresh signals post code repo\nit(\"should not display list of todos...\", () => {\n const todos = [] as string[];\n state.todos.value = todos;\n const { queryAllByRole } = render(\n <AppState.Provider value={state}>\n <TodoList />\n </AppState.Provider>,\n );\n // queryAllBy returns an empty array; getAllBy just throws an error\n const buttons = queryAllByRole(\"button\");\n assertEquals(buttons.length, 0);\n});findBy is used:// MenuLink.test.tsx in this blog's repo\nit(\"Show About link\", async () => {\n // change the location, triggering a menu rerender\n globalThis.window.location = { href: \"/about\" };\n const { findByText } = render(<MenuLink />);\n // findByText returns a Promise\n const page = await findByText(\"Home\");\n const text = page.textContent;\n assertExists(text);\n assertNotEquals(text, \"About\");\n});waitFor is used under the\ncovers by the findBy* finder. However, it can be used standalone.The\nwaitFor function\nis used for verifying DOM elements that take a while to render due to an async\noperation. Here's how waitFor is used:
await waitFor(() => {\n assertEquals(counter.textContent, count.value.toString());\n});As shown, waitFor is an async function that takes a function argument and\noptionally an options argument. This function runs until the waited-for\noperation succeeds or times out. The timeout is 1000ms by default, but that can\nbe changed in the options argument's timeout property.
Kent C. Dodds, the creator of Testing Library, recommends to\nprefer the use of the 'ByRole' finder function to discover DOM nodes. This is a tough thing to do since role options are not well documented in Testing Library docs. Instead, a role used by Testing Library is documented in the WAI ARIA accessibility standard.
The 'ByRole' finder requires a string that is a valid WAI ARIA role name (see\nthis\nlist of WAI ARIA roles).
\nCertain HTML elements have\nan implicit role. Some of\nthese elements have the same role name as the element name. They include\nbutton, article, code and img.
Nearly all of the HTML form elements also have implicit roles. This includes\ninput elements with type=\"text\" (textbox role), type=\"radio\" (radio\nrole), type=\"range\" (slider role), type=\"number\" (spinbutton role) and\ntype=\"submit\" (button role). The textarea element's implicit role is\ntextbox while the select element's implicit role is listbox or combobox.
Another handy implicit role to use is link for an HTML anchor (a tag), but the anchor must have a href attribute. Here's an example of a component test to verify 3 links:
// Header.test.tsx in Fresh repo\ndescribe(\"components/gallery/Header.tsx\", () => {\n beforeAll(setup);\n afterEach(cleanup);\n\n it(\"should show 3 links\", () => {\n const { getAllByRole } = render(<Header active=\"\" />);\n const links = getAllByRole(\"link\");\n assertEquals(links.length, 3);\n });\n});When you want to use an implicit role, do not set an element's role attribute.
Sometimes you might have multiple elements with the same implicit role; multiple buttons, for instance. In that case use the options argument.
\nEach role has a different set of options. All of them have a name property,\nbut the property's value depends on the role. For the button role, the name\nproperty is the button's value. For the img role, the name property is the\nvalue of the element's alt attribute. Roles for HTML elements without an\nimplicit role must be specified using the role attribute.
Many IDEs like Visual Studio Code support discovery of valid roles using\nautocompletion. Just type getByRole(\"\") putting your cursor within the quotes. Then press ctrl/cmd-spacebar\nand a list of valid roles should appear.
If you use an argument to a 'ByRole' finder that is illegal, when the test is\nrun the error message will point out the available implicit roles. Alternately,\nyou can use the fresh-testing-library function logRole to find the implicit\nroles within your component-under-test.
Testing Library emphasizes accessibility by having a number of finder functions\nthat use accessibility attributes. The 'ByRole' finder is a big one, but\n'ByPlaceholderText', 'ByAltText', 'ByLabel' and 'ByTitle' are others.
\nHere is an example of using the title attribute with the 'ByTitle' finder:
// Background.test.tsx in Fresh repo\nit(\"should display background image\", () => {\n // Background takes any number of native attributes or Preact props\n const { getByTitle } = render(<Background title=\"background\" />);\n const bg = getByTitle(\"background\");\n const style = bg.getAttribute(\"style\");\n assertEquals(style, \"background-image: url(/gallery/grid.svg);\");\n});The fresh-testing-library contains two ways for simulating user interactions:\nfireEvent and userEvent.
The fireEvent function is used for simple interactions with the UI, while\nuserEvent simulated the subtile nature of the interactions. For instance when a\nbutton is pressed, fireEvent.click would cover the DOM click event, but\nuserEvent.click encompasses the hover, keydown and keyup events in addition to\nthe click event. In other words, userEvent more closely behaves the way users\nwould\n(see this article for more details).
fireEventThe fireEvent object includes function properties for almost 90 DOM events\nThey include:
fireEvent.click - to invoke an onClick handlerfireEvent.change - to invoke an onChange handlerfireEvent.submit - to invoke an onSubmit handlerfireEvent.keyDown - to invoke an onKeyDown handlerSee the EventType union type in the TypeScript docs for an enumeration of\nall events.
Each of the fireEvent function properties takes an argument that is the\nHTMLElement event target.
Here's an example of using a 'click' event to invoke a button click:
\n// Counter.test.tsx in Fresh signals blog post\nit(\"should display count and increment/decrement it correctly\", async () => {\n const count = signal<number>(9);\n const { queryByRole, queryByText } = render(<Counter count={count} />);\n const plusOne = queryByRole(\"button\", { name: \"+1\" });\n assertExists(plusOne);\n const minusOne = queryByRole(\"button\", { name: \"-1\" });\n assertExists(minusOne);\n\n await fireEvent.click(plusOne);\n assertFalse(queryByText(\"9\"));\n assertExists(queryByText(\"10\"));\n\n await fireEvent.click(minusOne);\n assertExists(queryByText(\"9\"));\n assertFalse(queryByText(\"10\"));\n});In this case, the event target are two button elements, one for incrementing the\ncount, the other for decrementing it.
\nuserEventThe userEvent object has 16 function properties. They include clear, click,\ncopy, cut, dblClick, deselectOptions, hover, keyboard, paste,\npointer, selectOptions, tab, tripleClick, type, unhover and\nupload. As you can surmise from the function names, these correspond to actual\nways that the user interacts with the UI rather than strict DOM events.
The arguments for these functions can be very different. Many take a DOM element like, click, dblClick and hover, while others have very different arguments. See the userEvent docs or use your IDE (hover over the function or right click and select \"Go to Definition\") to discover these args.
The userEvent object has a setup function that should be used to instantiate\nthe object before it is used. Here's what that looks like:
const user = userEvent.setup();The previous fireEvent example can be adapted to use userEvent. Here is what\nit looks like:
// Be sure to import userEvent from FTL component.ts\nit(\"should display count and increment/decrement it correctly\", async () => {\n const user = userEvent.setup();\n const count = signal<number>(9);\n const { queryByRole, queryByText } = render(<Counter count={count} />);\n const plusOne = queryByRole(\"button\", { name: \"+1\" });\n assertExists(plusOne);\n const minusOne = queryByRole(\"button\", { name: \"-1\" });\n assertExists(minusOne);\n\n await user.click(plusOne);\n assertFalse(queryByText(\"9\"));\n assertExists(queryByText(\"10\"));\n\n await user.click(minusOne);\n assertExists(queryByText(\"9\"));\n assertFalse(queryByText(\"10\"));\n});While userEvent seems like a more logical choice since it focuses on user\ninteractions, fireEvent covers more event types so it needs to be used in\ncertain circumstances. For instance, fireEvent has a change function for\nsimulating an onChange event, while userEvent does not have a similar\nfunction.
Preact signals provide a means to do local and global state management with\nsignals. A previous\nCraig's Deno Diary post\ndemonstrated how to use signals with Fresh.
\nCompared to useState, the signal function only returns a single value and\nnot an array with a setter function. Updating the signal involves assigning the\nvalue property of the signal a new value.
const count = signal<number>(0);\nconst newValue = count.value + 1;\ncount.value = newValue;The local state often changes when an event gets invoked which in turn updates\nthe UI. In a fresh-testing-library test, the fireEvent function would\ntrigger his kind of change.
const [getByRole, queryByText] = render(<Counter />);\nconst button = getByRole(\"button\");\nfireEvent.click(button);\nassertExists(queryByText(\"Count: 1\"));Global state management with Preact signals requires a module that holds that\nstate and using the Preact context to pass the state to child components. I will\nnot go over how this is coded in detail as you can refer the the\nCraig's Deno Diary post\non how it's done.
\nThe code used to illustrate the state management testing shown here is taken\nfrom the\nsignals blog post's repo.
\nTesting a component that uses global state requires that you wrap the component\nin a Preact context provider that passes the state into the component. The context is created in the parent component using the createContext function:
// App.tsx\nexport const AppState = createContext<AppStateType>({} as AppStateType);The AppState context has a provider field used to pass the state to child components.
The child components discover the state using the useContext hook. Here's a\ncomponent that displays a list obtained from the context:
// TodoList.tsx in Fresh signals blog post repo\nimport { useContext } from \"preact/hooks\";\nimport { AppState } from \"./App.tsx\";\nimport Todo from \"./Todo.tsx\";\n\nexport default function TodoList() {\n const { todos } = useContext(AppState);\n return (\n <div className=\"todos\">\n {/* todos are a signal that contain the todos value */}\n {todos.value?.map((item: string, i: number) => {\n return <Todo text={item} index={i} />;\n })}\n </div>\n );\n}To test a component in isolation, you need to wrap it in a context provider so\nthat state can be passed to the child component. Here's what that kind of test\nlooks like:
\n// TodoList.test.tsx in Fresh signals blog post repo\nit(\"should display list of todos...\", () => {\n const todos = [\"Foo\", \"Bar\", \"Baz\"];\n // state is imported from the module that holds it (state.ts)\n state.todos.value = todos;\n const { getAllByRole, queryByText } = render(\n <AppState.Provider value={state}>\n <TodoList />\n </AppState.Provider>,\n );\n // verify that all todos are displayed\n for (let i = 0; i < todos.length; i++) {\n assertExists(queryByText(todos[i]));\n }\n // Each todo has a delete button\n const buttons = getAllByRole(\"button\");\n assertEquals(buttons.length, 3);\n});Notice in the test that we assign the state's todos value before we attached it to the AppState.Provider context provider.
The\noriginal blog post on Fresh signals\nhas been updated with fresh-testing-library component tests including the test\nused in this section.
IS_BROWSER - This constant is used a lot in Fresh app code, but\ntesting it can be problematic. In order to set IS_BROWSER to false, you need\nto set the document object to undefined. Doing that will cause a\nfresh-testing-library test to fail because the jsdom library cannot\nfunction without a valid document object. Therefore, testing code that uses\nIS_BROWSER cannot be done with fresh-testing library.debug functions - used for printing out the DOM returned from calling\nrender or any of the finder functions. The former prints out the complete\nDOM that was rendered and the latter prints out the returned DOM from a finder\nfunction call. Here's how to use them:const { debug, queryByRole } = render(<MyComponent />);\n// print out all the component's DOM elements wrapped in a body element\ndebug();\nconst element = queryByRole(\"button\");\n// prints out the button element's DOM\nelement.debug();Testing middleware employs the createMiddlewareHandlerContext function to mock\nout the MiddlewareHandlerContext used in a middleware handler. Here's what the\ncode and a test would look like for the\nmiddleware in this repo;
// _middleware.ts in this blog's repo\nimport { MiddlewareHandlerContext } from \"$fresh/server.ts\";\n\nexport const handler = setCacheControlHeaders();\n\nexport function setCacheControlHeaders() {\n return async (_req: Request, ctx: MiddlewareHandlerContext) => {\n const resp = await ctx.next();\n resp.headers.set(\"Cache-Control\", \"public, max-age=21600, immutable\");\n return resp;\n };\n}\n\n// middleware.test.ts\nimport { assertEquals } from \"std/assert/assert_equals.ts\";\nimport { createMiddlewareHandlerContext } from \"$fresh-testing-library\";\nimport { setCacheControlHeaders } from \"../../routes/_middleware.ts\";\nimport manifest from \"../../fresh.gen.ts\";\n\nDeno.test(\"should set Cache-Control header\", async () => {\n const req = new Request(`http://localhost:3000/`);\n // @ts-ignore ignores \"type ... is not assignable to type Manifest\" error\n const ctx = createMiddlewareHandlerContext(req, { manifest });\n let resp = new Response();\n const middleware = await setCacheControlHeaders();\n await middleware(req, ctx);\n resp = await ctx.next();\n assertEquals(\n resp.headers.get(\"Cache-control\"),\n \"public, max-age=21600, immutable\",\n );\n});You can use Deno.test in this case since a middleware test does not require\nsetup or cleanup.
The Request object can be used to find out the current URL or request method\n(GET, POST, etc) for middleware with logic that is more sophisticated than my\nsimple example.
At this point, route testing using fresh-testing-library is confined to\ntesting handler logic and not the handler's Response including verifying\nresponse markup.
You use the createHandlerContext function in fresh-testing-library to test\nthe handler function of a route component.
// about.test.ts in this blog's repo\nDeno.test(\"routes/About.tsx handler tests...\", async (t) => {\n await t.step(\"should respond to GET request in DEV...\", async () => {\n assert(handler.GET);\n const req = new Request(\"http://localhost:8000/about\");\n // @ts-ignore manifest typing\n const ctx = createHandlerContext(req, { manifest });\n\n const res = await handler.GET(req, ctx);\n assertEquals(res.status, 200);\n });\n // ... other tests here\n});You do not need startup and cleanup functions for handler tests, so we use\nthe Deno.test runner function here instead of the bdd module functions.
Alternatively, the Fresh codebase includes the createHandler function for\ntesting a route handler. The createHandler function creates a mock handler\nfunction.\nSee the Fresh docs for more details on using this function.
Grouping routes was\nadded in Fresh v1.4. Version 0.8.0, of the fresh-testing-library added support\nfor testing route groups. fresh-testing-library route handler tests\ntransparently works if routes are grouped.
Fresh async route components\nare components where an async route handler function is inlined into the route\npage component. In that case, the route page component is declared as\nasynchronous (using the async keyword). Here's what that look likes (taken\nfrom the Fresh routes documentation):
export default async function MyPage(req: Request, ctx: RouteContext) {\n const value = await loadFooValue();\n return <p>foo is: {value}</p>;\n}Fresh also ships with a\ndefineRoute\nfunction to simplify the creation of async route components.
A fresh-testing-library test of an async route component uses the\ncreateRouteContext function in the server module. Here's how it is used in a\nfresh-testing-library\nexample:
import {\n cleanup,\n getByText,\n render,\n setup,\n} from \"$fresh-testing-library/components.ts\";\nimport { createRouteContext } from \"$fresh-testing-library/server.ts\";\nimport { assertExists } from \"$std/assert/assert_exists.ts\";\nimport { afterEach, beforeAll, describe, it } from \"$std/testing/bdd.ts\";\nimport { default as UserDetail } from \"./demo/routes/users/[id].tsx\";\nimport { default as manifest } from \"./demo/fresh.gen.ts\";\n\ndescribe(\"routes/users/[id].tsx\", () => {\n beforeAll(setup);\n afterEach(cleanup);\n\n it(\"should work\", async () => {\n const req = new Request(\"http://localhost:8000/users/2\");\n const ctx = createRouteContext<void>(req, { manifest });\n const screen = render(await UserDetail(req, ctx));\n const group = screen.getByRole(\"group\");\n assertExists(queryByText(group, \"bar\"));\n });\n});In this case, UserDetails is the async route component.
Use the example code given at the beginning of this blog post\nto guide you through the the core fresh-testing-library concepts introduced\nabove. There are over two dozen test files for you to peruse in those three\nrepos.
There are also examples in the\nfresh-testing-library repo.\nCheck out the components.test.tsx, server.test.tsx and routes.test.tsx\nfiles used to test code in the demo folder.
Also be aware that fresh-testing-library has not yet released version 1.0, so\nit will continue to evolve to include more features and bug fixes. In addition,\nI know by first-hand experience that the fresh-testing-library author is very\nresponsive to issues submitted to the library's repo.
Finally, since the component testing feature of fresh-testing-library wraps\nthe Preact Testing Library, you need to be familiar with that\nlibrary's documentation.\nIt provides a guide to the full component testing API.
Special thanks goes to fresh-testing-library author Yuki Tanaka (@uki00a) for\nanswering my many questions, promptly fixing bug reports that I submitted and\nreviewing a draft of this article. I would also like to thank Kyle June (@kylejune) for his help with understanding the limitations of mocking with expect.
list() & getMany())\natomic()\nDeno KV, a key-value based database, was built into the Deno runtime starting with Deno 1.32.0 as an unstable API. Deno Deploy now incorporates Deno KV (currently as an invite-only beta), and distributes KV data around the world. This means that when a web application is put on Deploy, there will now be a database close to each server instance. Deno KV also provides ACID transactions to maintain data consistency.
\nThis article will cover all aspects of Deno KV with simple, easy-to-understand examples. Since info on Deno KV is in multiple places in the Deno documentation, consider this post as a one-stop guide to KV.
\nNote that a dozen working code examples have been created to support this blog post. They can be found in this repository folder. You'll also find each example linked in the relevant section of this article.
\nAn index in Deno KV parlance are the units of data storage. In relational database (RDBMS) terms, they can be loosely thought of as a table, but they are more like a SQL index because they are ordered by key value for fast lookup.
\nA KV primary index is the index that stores a record using a unique key for each record, usually a UUID. We'll talk more about them in the next few sections. A secondary index stores additional information or is used for sorting. We'll talk about them later.
\nDeno KV have well-defined keys, values and a versionstamp that represents a value's version.
\nAs stated above, Deno KV is a key-value database. In it's simplest form, a database record's data is persisted and found using the key. In Deno KV, the key is a tuple, an array with a fixed length. Each of the members of the tuple is called a part. All parts are linked together into a kind of compound key. Key parts can be of types string, number, boolean, Uint8Array, or bigint.
Here are a couple of examples of a Deno KV key used to identify unique records:
\n// User key\nconst userKey = [\"user\", <userid>]; // Used for storing user objects\n// Address key for a particular User\nconst addressKey [\"address\", <userId>]; // Used for storing a user's addressAs stated above, when a unique key is used to persist values, the resulting index is know as a primary index. The Web platform provides crypto.getRandomUUID() to obtain a unique id.
An index is an ordered sequence of key parts so that [1, \"user\"] is not the same as [\"user\", 1].
When used in a primary index the first key part is usually a string constant identifying the model collection being persisted, \"user\" or \"address\" in the example. When used to add records to an index, the key parts are combined into a compound key.
The initial key part of an index can be expanded into multiple parts. For instance, if we have a user with roles, we might have the second part representing a role such as:
\nconst userAdminKey = [\"user\", \"admin\", <userId>];\nconst userCustomerKey = [\"user\", \"customer\", <userId>];\nconst userGuestKey = [\"user\", \"guest\", <userId>];If there is a role field on the model, the previous keys could be reduced to something like this (assuming each user has one role):
\nconst userRoleKey = [\"user_by_role\", <userRole>, <userId>];Indexes created with these keys are called secondary indexes. They need to be persisted in an atomic transaction with the primary index in order for the data to be is consistent between indexes (see the secondary index discussion below). Secondary indexes should have a first part name describing their function. In this case, the key is used to lookup a user and the first part is \"user_by_role\".
In order for Deno KV values to be persisted, a value must be a structured, serializable JavaScript type compatible with JavaScript's structured clone algorithm.
\nBasically, it is anything that can be passed as the first argument of structuredClone() except SharedArrayBuffer. The SharedArrayBuffer is an exception because is a shared memory data structure that cannot be passed across KV remote isolates.
See this discussion on MDN for more details on what does not conform to the structured clone algorithm.
\nDespite these limitations most common JavaScript types including undefined, null, boolean, number, string, Array, Map, Uint8Array and Object work as KV values (a full list).
The Deno Manual notes that objects with a non-primitive prototype such as class instances or Web API objects are not supported as KV values.
\nHere are examples of how the keys and values are used to persist to Deno KV (the set() method will be discussed later):
// persist an object with id, name and role fields\nkv.set([\"user\", \"a12345\"], {id: \"a12345\", name: \"Craig\", role: \"admin\"});\n// persist an environmental variable value\nkv.set([\"env\", \"IS_PROD\"], true);\n// persist a hit count by page and userId\nkv.set([\"hits\", \"account.tsx\", \"a12345\"], 254);Each time a new value is persisted to Deno KV, it is automatically given a 12-byte version value based on the timestamp when the record was saved. KV calls this a versionstamp. When a value is updated, a new versionstamp is created.
A new versionstamp will always be 'larger' than the previous one such that the second modification of a record will always be greater than the first in a boolean comparison (versionstamp2 > versionstamp1). This is important if you want to track and display a record's version history.
The versionstamp assures that transactions are done atomically thus making sure that affiliated relational records in different indexes are consistent. Atomic operations in Deno KV can be checked to make sure that the data is consistent between the last fetch (get()) and when the new data will be persisted. This check is done with the record's versionstamp (for details see below).
The main CRUD (create, read, update & delete) operations in KV are defined as methods on the Deno.Kv class: set()(create & update), get() (read) and delete() (delete). All these operations are asynchronous so a call needs to be preceded with the await keyword.
\n\n💡 Working code that demonstrates CRUD operations can be found in the repo affiliated with this blog.
\n
All CRUD operations on Deno KV start with a connection to the KV database which is done with a simple call to Deno.openKv():
// Open a KV connection returning a Deno.Kv instance\nconst kv: Deno.Kv = await Deno.openKv();We'll be using the kv KV connection object (Deno.Kv instance) throughout our examples below.
It's best to create a TypeScript type or interface to represent data models. For instance, a user model will look something like this:
\ninterface User {\n id: string;\n name: string;\n email: string;\n phone?: string;\n}Adding relations to the model, such as address and phone numbers would use Address and Phone interfaces. Both of them would have a userId field that would allow the lookup of an address and phone number for a particular user. For simplicity, we will focus on the User model here.
Deno KV CRUD operations for a User will persist data that often comes from an HTML registration form filled out by a user. In our case, we'll manually create a user with a unique id:
const userId = \"1\";\nconst user = {\n id: userId,\n name: \"John Doe\",\n email: \"john@doe.com\",\n phone: \"2071231234\"\n}The user id can be hard coded like I did here, but it's best that it is generated as a unique value. The crypto object built into the Web platform is an easy way to create a unique id:
const userId = crypto.randomUUID();set())Lets connect to the KV data store and insert the user data which requires two arguments, a Deno.KvKey and a value whose type is the method's TypeScript generic parameter (User in this example):
const result = await kv.set<User>([\"user\", userId], user);\nif (result.ok === false) {\n throw new Error(`There was a problem persisting user ${user.name}`)\n}In SQL database terms the data table would be called \"user\" and the user id would be the primary key.
\nThe return value of a set() call is a Promise<Deno.KvCommitResult>, The KvCommitResult object contains a boolean ok field and a versionstamp field. If the set() call fails, ok is set to false. The versionstamp would be the versionstamp of the persisted record.
get())The get() method is used to obtain a single record from Deno KV. For example:
// Assumes kv is a Deno.Kv object\nconst foundRecord: Deno.KvEntryMaybe<User> = await kv.get<User>([\"user\", userId]);\n// Get user value\nconst user = foundRecord.value;A call to get() returns a Deno.KvEntryMaybe object containing key, value and versionstamp properties (the Maybe part of KvEntryMaybe means that the result's value and versionstamp may be null). The key will always be the key you used in the the get() call. The value and timestamp values are those found in the KV store associated with the key.
Here's an example of an object returned from get():
// ids obtained from a call to crypto.getRandomUUID()\n{\"key\":[\"users\",\"4f18bbe6-1e0a-483f-9b89-556be297191c\"],\n\"value\":{\"id\":\"4f18bbe6-1e0a-483f-9b89-556be297191c\",\"name\":\"John Doe\",\"email\":\"john@doe.com\",\"phone\":\"2071239876\",\"age\":35},\n\"versionstamp\":\"0000000000001d960000\"}\n\n💡 Notice that value of a
\nget()call is found in thevalueproperty of the call's result. This can trip you up since you might expect that theget()call returns only the value. Also be aware that the return value is wrapped in aPromiseso make sure you prefix the call withawait.
If you call get() with a key that is not in the KV store, you will get back an object with both value and versionstamp equal to null.
set() OptionsThe get() method has an optional second argument called options. The options argument contains one field consistency. which has two values \"eventual\" or \"strong\"(see discussion below for details).
When running Deno KV locally, the consistency value is not relevant since the KV store is local. It is relevant when an application using Deno KV runs in the cloud on Deno Deploy since KV store instances are remotely distributed (see below).
set())Updating KV data would also use the set() method as is done for inserts:
user.phone = \"5182349876\"\n// Assumes kv is a Deno.Kv object\nconst result = await kv.set<User>([\"user\", userId], user);\nif (result.ok === false) {\n throw new Error(`There was a problem persisting user ${user.name}`)\n}The arguments and return value from an update is the same as a create/insert call to set().
delete())Deleting a record with the delete() method which requires a key (Deno.KvKey) argument.
// Assumes kv is a Deno.Kv object\nawait kv.delete([\"user\", userId]);The delete method returns a Promise<void> which resolves to an undefined value.
It is recommended that the mutation methods set() and delete() are done in a transaction which will return a result with an ok property to indicate if the transaction succeeded (ok: true) or failed (ok: false). See the transaction section below for more details.
list() & getMany())Reading multiple records involves the use of list() and getMany(), two methods on Deno.Kv.
list()The list() method obtains multiple records and produces an async iterator (Deno.KvListIterator). The easiest way to loop through this kind of iterator is to use a for-of loop with await loop. Here is a simple example:
// The iterator is returned from a call to list().\n// 'await' used with 'for' because the iterator is async\nfor await (const row of iterator) {\n const user = row.value;\n console.log(user.name); // do something with the user object\n}\n\n💡 Working code that dives deeply into the
\nlist()method can be found in the repo affiliated with this blog. Nearly all the code files in the repo uselist()in various ways.
The list() method takes two arguments selector and options:
list() argument: selectorThe selector argument is an object with three optional fields: prefix, start and end.
The prefix selector field
Unlike the key arguments for set(), get and delete(), CRUD methods, the prefix key is a key part subset. All the key parts are usually string literals.
Let's say you just wanted a list of users or user admins, your list() call would look like this:
// Assumes kv is a Deno.Kv object\n// Get and iterator with a list of users\nconst iterUser = kv.list<User>({prefix: [\"user\"]});\n// An iterator with a list of admins\nconst iterAdmin = kv.list<User>({prefix: [\"user\", \"admin\"]});\n\n💡 To avoid TypeScript errors, call
\nlist()with a generic parameter (Userin the previous example).
Besides its use in querying, index prefixes are important when data is stored in remote KV instances (like Deno Deploy) because indexes with the same prefix are persisted near each other which facilitates rapid retrieval.
\nSelector fields start and end
Besides prefix, start and end are selector field options. The list() method takes one or two of these fields. The first one can be either prefix or start and the second one can be either start or end.
The start or end options of list() define a range of KV records you want to select. But to be able to use start or end, you need to understand how key ordering is done (see the sorting with indexes section below).
While key ordering is instrumental for sorting, with start and end the order is used to define the beginning and ending of a range of ordered keys returned in the result set.
The start option starts with the first matching record while the end method includes all previous records, but not the record it points to.
// Assumes kv is a Deno.Kv object\nconst rows = kv.list({\n start: [\"user_by_name\", \"Dow\"],\n end: [\"user_by_name\", \"Zozos\"],\n});\nfor await (const row of rows) {\n const user = row.value as User;\n console.log(user.name);\n}\n\n💡 In order for the
\nstartoption to work correctly, you need to make sure that the index you are sorting with is unique. For instance if the \"user_by_name\" index shown in the example was created using only the last name and if there are records with the same last name, only one will be included in the results. To explore how this happens see this example code in the blog's repo.
You can pair either start or end with the prefix field. When prefix is paired with start, the end point is the last record in the index. Alternately, when prefix is paired with end, the start point is the first index record. Here is an example:
// Assumes kv is a Deno.Kv object\nconst rows = kv.list({\n prefix: [\"user_by_name\"], // points to first record\n end: [\"user_by_name\", \"Zozos\"],\n});\n// Loop through results\nfor await (const row of rows) {\n const user = row.value as User;\n console.log(user.name);\n}list() argument: optionsThe options list() argument is an object with a collection of fields:
limit: number - limits the size of a list() result set.cursor: string - the cursor to resume iteration. Recall the list() method returns a Deno.KvListIterator that contains a cursor field. This is important in the pagination use case.reverse: boolean - returns the list in reverse orderprefix, start or end can be used with reverse.batchSize: number - the size of the batches in which the list operation is performed. The default is equal to the 'limit' value or 100consistency: Deno.KvConsistencyLevel - the transactional consistency, either \"strong\" or \"eventual\"(see the consistency section below).list()The key to iterating a list in paged groups is the fact that list() returns a Deno.KvListIterator. That iterator has a cursor field and a next() method, a consequence of that fact that it implements the async iterator protocol.
To paginate, you pass the cursor from one list() call to the next via the iterator result. That result's iterator.cursor value becomes the value of the cursor option in the next list() call. Here's how it looks:
// Assumes kv is a Deno.Kv object\n// First call to list() returns iterator\nlet iterator = kv.list<User>({ prefix: [\"user_by_age\"] }, {limit: 25})\n// Second call sets the cursor using the iterator from the first call to set the second call's cursor\niterator = kv.list<User>({ prefix: [\"user_by_age\"] }, {limit: 25, cursor: iterator.cursor});When you don't know the number of items in an index you are querying with list() (\"user_by_age\" in this case), you can't just call until you get a null iterator, because list() always returns a KvListIterator object even if there are no results that can be obtained from the iterator.
Instead, you use the KvListIterator.next() method's done property. This is best shown with an example.
First, start with a list of users:
\n// start with a User interface\ninterface User {\n id: number;\n name: string;\n age: number;\n}\nconst users: User = [/* Multiple User objects here */];Next, we'll create a function to get an iterator. It will be called each time we want to display another group of users on a page. The first call to this method will set the cursor argument to an empty string which is used to determine whether cursor will be part of the second list() argument.
// Obtain a new User iterator\nfunction getIterator<T>(cursor: string, limit: number): Deno.KvListIterator<T> {\n const optionsArg = cursor !== \"\" ? { limit, cursor } : { limit };\n // Assumes kv is a Deno.Kv object\n const iterator = kv.list<User>({ prefix: [\"user_by_age\"] }, optionsArg);\n return iterator;\n}The processIterator<User>() function pulls out the iterated data (users in this case) and returns them with the cursor to be used in the next call to getIterator():
// Called with `User` generic param below (item=User; items=User{})\nasync function processIterator<T>(\n iterator: Deno.KvListIterator<T>,\n): Promise<{cursor: string, items: T[]}> {\n let cursor = \"\";\n let result = await iter.next();\n const items = [];\n while (!result.done) {\n cursor = iterator.cursor;\n // result.value returns full KvEntry object\n const item = result.value.value as T;\n items.push(item);\n result = await iter.next();\n }\n return {cursor, users};\n}While the previous functions are generic, printUsers is used to print out an array of User objects with the page number:
function printUsers(users: User[], pageNum: number) {\n console.log(`Page ${pageNum}`);\n for (const u of users) {\n console.log(`${u.name} ${u.age}`);\n }\n}Finally, initiate the pagination, printing out user data to the console:
\n// print out users in batches of USERS_PER_PAGE\nconst USERS_PER_PAGE = 3; // aka page size\nlet pageNumber = 1;\nlet cursor = \"\";\nlet iter = getIterator<User>(cursor, USERS_PER_PAGE);\nawait processIterator(iter, pageNumber);\nprintUsers(processedItems.items as User[], pageNum);\npageNumber++;\n// point the cursor to the next batch of data\ncursor = iter.cursor;\n// stop iteration when cursor is empty\nwhile (cursor !== \"\") {\n iter = getIterator<User>(cursor, USERS_PER_PAGE, keyPart);\n const iterRet = await processIterator<User>(iter);\n cursor = iterRet.cursor;\n // cast items to User[]\n const items: User[] = iterRet.items as User[];\n if (items.length > 0) {\n printUsers(items, pageNum);\n }\n pageNum++;\n}\n\n💡 The example snippets taken from code that demonstrates
\nlist()pagination can be found in the repo affiliated with this blog.
Paginating webapp results uses a lot of the previous code including getIterator and processIterator. You will also need to keep track of the cursor and pageNumber between requests for new pages, passing them into the next URL invocation via params in 'Next Page' and 'Previous Page' links in the footer.
This is a tough thing to explain in black and white without example code (and in the process prolonging this already-too-long post), so I'll leave this as an exercise for the reader. However, please stay tuned. I hope to cover this in detail in a future article.
\n\n\n💡 At this point, I'm prototyping a Deno Deploy playground that demonstrates KV pagination, but it's quite not ready for prime time yet.
\n
getMany()The getMany() method provides the opportunity to do a number of get() calls to separate indexes in one operation. The method accepts an array of keys and returns an array of Deno.KvEntryMaybe records, objects that include a key, value and timestamp fields.
\n\n💡 Working code that demonstrates the
\ngetMany()method can be found in the repo affiliated with this blog.
It is important to know that each one of the keys should return single KvEntryMaybe objects like they would in a get() call. So it follows that the number of keys in the getMany() argument will always equal the number of of results in the call return array.
For example, suppose we have three environmental variables stored in three separate indexes. Here's what that would look like:
\n// keys for storing env variables in KV\nconst githubSecretKey = [\"env_var\", \"GITHUB_ACCESS_KEY\"];\nconst googleSecretKey = [\"env_var\", \"GOOGLE_ACCESS_KEY\"];\nconst discordSecretKey: Deno.KvKey = [\"env_var\", \"DISCORD_ACCESS_KEY\"];\n\n// Assumes kv is a Deno.Kv object\n// store env vars in separate indexes\nawait kv.set(discordSecretKey, \"password1\");\nawait kv.set(githubSecretKey, \"password2\");\nawait kv.set(googleSecretKey, \"password3\");\n\n// get all env var entries in one call to separate indexes\nconst envVars = await kv.getMany([\n githubSecretKey,\n googleSecretKey,\n discordSecretKey,\n]);\n// the 'enVars' result array would contain these values:\n//\n// enVars[0] = {key: [\"env_var\", \"GITHUB_ACCESS_KEY\"], value: \"password2\", versionstamp: \"001234\" }\n// enVars[1] = {key: [\"env_var\", \"GOOGLE_ACCESS_KEY\"], value: \"password3\", versionstamp: \"001235\" }\n// enVars[2] = {key: [\"env_var\", \"DISCORD_ACCESS_KEY\"], value: \"password1\", versionstamp: \"001236\" }\nThe getMany() method takes a second argument, options which is optional. The option argument has one property consistency which can be \"strong\" or \"eventual\". See the data consistency section for more details on this topic.
atomic()The atomic() method on Deno.Kv is used to do a transaction with KV. It returns a Deno.AtomicOperation class instance. Transactional operations are chained to atomic(). The chain must be terminated with a call to commit() in order for the transactional operations to be completed and the data persisted.
\n\n💡 Working code that demonstrates atomic transactions can be found in the repo affiliated with this blog
\n
check() to validate transactionsA transactional chain off of atomic() should first call the check() method for each persistent operation. The check() method ensures that the versionstamp of data already in the KV store matches the versionstamp of the data being persisted. This feature is called optimistic concurrency control and assures data consistency and integrity within the KV store.
A get() call must be done prior to check() to provide the key and versionstamp arguments of check(). For a new data insert the get() call will return null for the versionstamp (and value). If check() fails, then the transaction will fail and the data will not be committed.
After check(), a series of set() and/or delete() calls are done to persist or delete KV data based on the provided key. These two methods behave the same way they do when called outside an atomic() chain (see CRUD section above).
An example will clarify how check() is used. Here we are trying to persist a user object with a changed phone number.
// Assumes kv is a Deno.Kv object\nconst user = await kv.get([\"user\", 123])\nconst result = await kv.atomic()\n // Make sure versionstamp has not changed after last get()..\n // This method requires both a key and versionstamp\n .check({key: user.key, versionstamp: user.versionstamp})\n // update phone number\n .set([\"user\", user.id], {...user.value, phone: \"2070987654\" })\n .commit();If check() fails, then any persistent operation in the chain will be bypassed and the commit() call returns a Deno.KvCommitError.
set() and delete() for transactional persistanceIn the previous example, set() is used to create or update data in a transactional chain. It is a method of Deno.AtomicOperation and works the same way as Deno.Kv.set() taking a key and value as arguments. It persists the value in a KV store with the key as the primary key (the record also contains a versionstamp).
Likewise, delete(), also an Deno.AtomicOperation method, works the same way as its Deno.Kv counterpart. It takes a key argument and is used to remove records from a Deno KV store.
Both set() and delete() can be chained to atomic() multiple times, but there cannot be more than 10 writes in a single persistent chain.
The full power of KV transactional persistence is revealed when you need to store related objects. For instance, if you have a user who has an address and phone numbers. You should start with Typescript types defining the model:
\n// userId added prior to persistence\ninterface User {\n id?: string;\n name: string;\n email: string;\n}\ninterface Address {\n userId?: string;\n street: string;\n city: string\n state: string;\n country: string;\n postalCode: string;\n}\ninterface Phone {\n userId?: string;\n cell: string;\n work?: string;\n home?: string;\n}Each one of the entities will be persisted into a separate KV index within an atomic transaction. Let's assume that this information has been collected from an HTML user-registration form and processed into User, Address and Phone model objects. Here's a function to insert or update that data within a KV transaction:
function persistUser(user: User, address: Address, phone: Phone) {\n if (!user.id) {\n const userId = crypto.randomUUID();\n address.userId = userId;\n phone.userId = userId;\n }\n // Assumes kv is a Deno.Kv object\n // get current records\n const userRecord = await kv.get([\"user\", userId]);\n const addressRecord = await kv.get([\"address\", userId]);\n const phoneRecord = await kv.get([\"phone\", userId]);\n await kv.atomic()\n // check that data has not changed\n .check({key: userRecord.key, versionstamp: userRecord.versionstamp})\n .check({key: addressRecord.key, versionstamp: addressRecord.versionstamp})\n .check({key: phoneRecord.key, versionstamp: phoneRecord.versionstamp})\n .set(userKey, user)\n .set(addressKey, address)\n .set(phoneKey, phone)\n .commit();\n}The return value of a kv.atomic()....commit() call chain is a Promise<Deno.KvCommitResult> if the transaction succeeds. That object contains two fields: ok and versionstamp. The ok value will be true in a successful transaction.
If a KV transaction fails within an atomic() call chain either by a failed check() or another transactional error, a Deno.KvCommitError is returned. In that case, the transaction is not persisted. The KvCommitError object has one field ok that is set to false when a failure happens.
Here's what happens if you try to insert data that has already been inserted causing check() to fail:
// Assumes that User 1 has already been added to the KV index\nconst id = 1; // user id\n// Assumes kv is a Deno.Kv object\nconst result = kv.atomic()\n // Initial insert has null versionstamp\n .check({key: [\n \"user\", id], versionstamp: null})\n .set([\"user\", id], `User ${id}`)\n .commit();\n\nif (result.ok === false) {\n throw new Error(`Data insert failed for User ${id} because it already exists`);\n}The versionstamp returned in a successful atomic() transaction is the versionstamp given to all operations within the atomic() call chain. This can be used to construct a version history of a record. In order to do this, you need to persist the versionstamp to a separate index. Here's what that would look like:
\n\n💡 Working code that demonstrates how to track a record's history can be found in the repo affiliated with this blog.
\n
const userId = crypto.randomUUID();\n// Assumes kv is a Deno.Kv object\nconst user = await kv.get([\"user\", userId])\nconst result = await kv.atomic()\n .check(user)\n .set([\"user\", userId], {id: userId, name: \"Joan Smith\", email: \"jsmith@example.com\"})\n .commit();\nif (result.ok) {\n// add the result versionstamp to a separate \"user_versionstamp\" index with a timestamp\n await kv.set([\"user_versionstamp\", userId, result.versionstamp ], {version: result.versionstamp, date: new Date().getTime()});\n}Since the versionstamp is part of the key, records will be ordered by versionstamp for each user.
You can then use list() to display the history of a particular user's record.
// display version in reverse chronological order\nconst iter = kv.list({ prefix: [\"user_versionstamp\", userId] },\n {reverse: true});\nfor await (const version of iter) {\n // display to stdout here; I'm sure you can do better\n console.log(`Version: ${version.value.version} Date: ${version.value.date}`);\n}You usually begin a Deno KV implementation by creating a primary index. The primary index will contain a model identifier part and a part unique to the value being persisted, like a user id for a \"user\" model. In that case, a particular \"user\" record will be found using the id.
\n\n\n💡 Working code that demonstrates how to create and use secondary indexes can be found in the repo affiliated with this blog.
\n
A secondary index is used to find a KV record or multiple records beyond the find-by-id search you can do with a primary index.
\nFor instance, if you want to search for a user by an email address you could have an index that uses the email address as the search criteria. These indexes usually have a name part that describes the index such as \"user_by_email\".
\nWhen you have secondary indexes, you need to create them in a transactional context with the primary index to maintain data consistency.
\nconst userId = crypto.randomUUID();\nconst user = {id: userId, name:\"Joan Smith\", email: \"joan.smith@example.com\"};\nconst userKey = [\"user\", userId];\nconst userEmailLookupKey = [\"user_by_email\", user.email];\n// Assumes kv is a Deno.Kv object\nconst result = kv.atomic()\n .check({key: userKey, versionstamp: null})\n .check({key: userEmailLookupKey, versionstamp: null})\n .set(userKey, user) // primary index\n .set(userEmailLookup, user.id) // secondary index\n .commit();\nif (!result.ok) {\n throw new Error(\"Problem persisting user & user_by_email\");\n}A get() call to \"user_by_email\" index returns the user's id. This will be used to find the record in the \"user\" primary index.
// The \"user_by_email\" record's value is the userId (see previous code)\nconst userByEmailRecord = await kv.get<User>([\"user_by_email\", userEmail]);\n// The value is the user Id\nconst userByIdRecord = await kv.get<User>([\"user\", userByEmailRecord.value]);\nconst user: User = userByIdRecord.value;When the data is updated or deleted, you need to do that for both primary and secondary indexes
\nSecondary indexes can be created with multiple lookup criteria such name and id. In a case like this, you should include the id because multiple users could have the same name. Here's an example:
\n// Assumes kv is a Deno.Kv object\n// A secondary index by name and id\nkv.set([\"user_by_name\", \"John Smith\", 1], {id: 1, name: \"John Smith\", email: \"jsmith@example.com\"})A secondary index can also be structured to store records by a group or category. For instance you might want to group football/soccer players by their position on the pitch. That might look like this:
\ntype Position = \"Goalkeeper\" | \"Defender\" | \"Midfielder\" | \"Forward\";\ninterface Player {\n id?: string; // id added later\n name: string;\n position: Position;\n}\nconst players: Player[] = [/* player data goes here */]\n// persist players to KV\nfor (const player of players) {\n player.id = crypto.RandomUUID();\n // Assumes kv is a Deno.Kv object\n await kv.atomic()\n // skip check() calls here;\n .set([\"players\", player.id], player);\n .set([\"players_by_position\", player.position, player.id], player);\n .commit();\n}\n// lookup players by a position\nconst findPlayersByPosition = async (position: Position) => {\n const iter = kv.list({prefix: [\"players_by_position\", position]});\n console.log(`Players in ${position} position:`);\n for await (const player of iter) {\n const playerPosition = await kv.get<Player>([\n \"players_by_position\",\n player.value.position,\n player.value.id ?? \"\",\n ]);\n console.log(playerPosition.value?.name);\n }\n}\n// Lookup midfielders\nawait findPlayersByPosition(\"Midfielder\");In KV, key parts are ordered lexicographically (roughly dictionary order) by their type, and within a given type, they are ordered by their value. Type ordering follows that Uint8Array > string > number > bigint > boolean. Within each type, there is a defined ordering too.
\n\n💡 Code that shows an example of index ordering can be found in the repo affiliated with this blog.
\n
The significance of the key ordering is it can be used to sort values. You do that by creating an secondary index using the desired sorting criteria as key parts.
\nFor instance, if you wanted to order user by their last name, you would have primary index and a secondary sorting index created like this:
\n// Assumes kv is a Deno.Kv object\n// create indexes within a transaction\nawait kv.atomic()\n // check() calls omitted for brevity\n .set([\"user\", <userId>], <user object>) // primary index\n // sorting by name\n .set([\"user_by_name\", <lastName>, <firstName>, <userId>], <user object>)\n .commit();You'll noticed that I added userId to the secondary index. Otherwise duplicate records with the same first and last name will be ignored when the index is created. You could also use email (or another unique identifier) instead of userId.
\n\n💡 A further exploration of duplicate record sorting behavior can be found in the repo affiliated with this blog.
\n
To display the sorted values you use the list() method. If you want to sort the list in reverse order (largest value to smallest) set reverse: true. A good example of that is sorting by date with most recent dates ordered at the top:
// create user and user_create_date indexes\n// Assumes kv is a Deno.Kv object\nawait kv.atomic()\n // check() calls omitted\n .set([\"user\", <userId>], <user object>) // primary index\n .set([\"user_by_create_date\", <createDate>, <userId>], <user object>)\n .commit();\n// print out the index previously created in reverse chronological order\nconst iter = kv.list({prefix: [\"user_by_create_date\"]}, {reverse: true});\nfor await (const user of iter) {\n console.log(user.value);\n}\n\n💡 Working code that demonstrates KV sorting can be found in the repo affiliated with this blog.
\n
sum, min & maxThere are three aggregate operations that can be used to keep track of a sum, a minimum and a maximum of a series of values that are stored in another index. A method exists for each one of the operations and a mutate() method that can alternatively used to collate those stats.
\n\n💡 Working code that demonstrates the
\nmin(),max()andsum()methods can be found in the repo affiliated with this blog.
All of these operations are Deno.AtomicOperations methods so they must be chained to atomic() with commit() as the chain terminator.
sum(), min() and max() methodsTo keep track of aggregate sum, minimal and maximum values, you can use the sum(), min() and max() methods. All of these methods take a key and a value that is a bigint type. Here is an example
//shopping cart item\ninterface CartItem {\n userId: string;\n itemDesc: string;\n price: number;\n}\n// cart data\nconst cart: CartItem[] = [\n { userId: \"100\", itemDesc: \"Arduino Uno kit\", price: 60 },\n { userId: \"100\", itemDesc: \"Temp sensor\", price: 10 },\n { userId: \"100\", itemDesc: \"Humidity sensor\", price: 15 },\n { userId: \"100\", itemDesc: \"Power cord with 5V regulator\", price: 18 },\n { userId: \"100\", itemDesc: \"Servo\", price: 8 },\n];\n\n// add data to indexes\nfor (const item of cart) {\n// Assumes kv is a Deno.Kv object\n kv.atomic()\n .set([\"cart\", item.userId], item) // primary index\n .min([\"cart_min\"], BigInt(item.price))\n .max([\"cart_max\"], BigInt(item.price))\n .sum([\"cart_sum\"], BigInt(item.price))\n .commit();\n}\n// get stats\nconst cartMin = await kv.get([\"cart_min\"]);\nconst cartMax = await kv.get([\"cart_max\"]);\nconst cartSum = await kv.get([\"cart_sum\"]);\n// print out cart stats\nconsole.log(\"Shopping cart data\");\nconsole.log(`Min price: ${(cartMin as Deno.KvEntry<bigint>).value}`);\nconsole.log(`Max price: ${(cartMax as Deno.KvEntry<bigint>).value}`);\nconsole.log(`Total price: ${(cartSum as Deno.KvEntry<bigint>).value}`);mutate() methodThe mutate() method is an alternate way to get aggregate stats. It takes an object with type, key and value properties. The type value can be either \"sum\", \"min\", or \"kax.
// Assumes kv is a Deno.Kv object\n// keep track of website visits\nawait kv.atomic()\n .mutate({\n type: \"sum\", // valid types are 'sum', 'min' & 'max'\n key: [\"hit_counter\"],\n value: new Deno.KvU64(1n),\n })\n .commit();The Deno.KvU64() constructor function is a wrapper around an unsigned bigint value. The value is set via the constructor argument and is retrieved using the value field on a Deno.KvU64() instance. The mutate() value argument is always a Deno.KvU64.
A queue was been added to Deno KV in Deno v1.34.3. If you recall from your data structures class (if you took one or picked it up on-th-fly like me), a queue is a linear sequence where operations are performed in first-in, first-out (FIFO) order. Enqueueing is the operation that adds items to a queue and dequeueing removes items from the queue.
\n\n\n💡 Working code that demonstrates queueing can be found in the repo affiliated with this blog.
\n
The KV queue implementation is done using the Deno.Kv.enqueue() and the Deno.Kv.queueListen() methods. The enqueue() method adds items to the database queue while the queueListen() method's callback function argument gets called when the item is dequeued.
Besides being called as a standalone method, enqueue() can also be chained to Deno.Kv.atomic() and be part of an atomic transaction.
There are two arguments to Deno.Kv.enqueue(). The first one is the value to be queued, which is a valid KV value. It returns a Promise<Deno.KvCommitResult> which resolves with a boolean ok value.
The second enqueue() argument is optional. It is an object that contains two properties (both of them optional):
delay - the time in milliseconds to delay the delivery of an enqueued object. The default is zero.keysIfUndelivered - an array of Deno.Kv.Key[] keys used to store a value if the value delivery to a queue listener is not successful after it has been retried several times.The Deno.Kv.queueListen() method has one argument which is a callback handler function. It takes an argument which is the queue value.
// Assumes kv is a Deno.Kv object\n// Listen to enqueued objects\nkv.listenQueue(async (msg: unknown) => {\n // Do a operation on the queued object\n await kv.set(msg.key, msg.value);\n console.log(\"Value delivered: \", msg);\n});\n\nconst res = await kv.enqueue(\n { key: [\"test1\"], value: \"testing 1,2,3\" },\n {\n delay: 1000, // delay delivery for 1 second\n keysIfUndelivered: [[\"queue_failed\", \"test1`\"]],\n },\n);\nconsole.log(\"Queue result: \", res);\n\n// Output:\n// Queue result: { ok: true, versionstamp: \"0000000000001d100000\" }\n// Value delivered: { key: [ \"test1\" ], value: \"testing 1,2,3\" }Like the atomic() method, the enqueue() method returns a result that contains ok and versionstamp fields. If the enqueueing fails, ok will be false; otherwise true.
The Deno runtime has an implementation of Deno KV using sqlite for persistence. This implementation is compatible with the Deno Deploy KV database (based on Foundation DB) so that code developed locally will seamlessly work when deployed to DD.
\nIf you do not have access to KV on Deno Deploy during its beta period, you can request it here.
\nAt this time Deno KV databases are replicated across at least 6 data centers, spanning 3 regions (US, Europe, and Asia).
\nData consistency refers to the assurance that all data centers maintain the same data even after new data is persisted.
\nThere are two kinds of data consistency in Deno Deploy. They can be configured using the consistency option when data is read from Deno KV. There are two options:
consistency: \"strong\" (default) - data reads from KV will come from the nearest region. Strong consistency implies:
consistency: \"eventual\" - uses global replica's and caches for data reads and writes to maximize performance. In most cases the difference between strong and eventual consistency speed ranges from zero to about 100 milliseconds, which depends on how close the deployed app region is to North Virginia, USA which holds the primary write database for KV (at this point).
See the Deno KV consistency section of the Deno Deploy docs for more information.
\nData access is quicker with eventual consistency, but the data possibly will not be consistent between different replicated KV instances if a query is done shortly after one or more KV writes.
\nFor more details see https://deno.com/blog/kv#consistency-and-performance
\nWhen data is written to a Deno KV store, the following things happen:
\nDeno Deploy docs state that the full asynchronous replication of data should occur withing 10 seconds.
\nOne issue with working with KV on Deno Deploy is how to seed the database before an app is started. The team recommends that you create an API route to handle the data loading and call the API route from a local command-line application sending the data with the command line calls.
\nLoading of large data sets should be done using batch calls to the API to avoid overloading the system and minimize server CPU usage. In any case, you should make sure the API returns an OK (202) response if persistence succeeded or a failure response (500) enumerating which records were not persisted into KV.
\nAn alternative for a small amount of is to have the data loaded once when the application starts. This could be done in a useEffect hook with an empty array argument that would set an \"is_loaded\" index with a true value when the initial load is completed and have that value checked before loading to make sure that they are not loaded multiple times.
Deno KV is not finished, so you should expect it to evolve. Here are some expectations:
\nIt remains to be seen whether these items will come from the Deno team or outside contributors.
\nSince the technology is young, there is still some hesitancy to use KV. Another issue holding people back from using it is that the only deployment option is Deno Deploy at this time. KV pricing has not been set and whether the price will be based on Deno Deploy storage and/or throughput. Currently it is free to use locally and on Deploy.
\nThe fact that the mental model of KV is different from a relational database is also a drawback for some. KV has no tools like SQL available for easy persistence and querying.
\nStill, KV has generated a lot of interest within the Deno community and there are a number of app examples and tools under development.
\nApplication content data is not the only thing you could store in KV. Other examples are configuration data, logical flags and system-wide properties. Its use is only a matter of a developer's imagination.
\nIf this article piques your interest in Deno KV, make sure you check out the Deno Manual and API docs as outlined below. The best place to stay on top of recent news on Deno KV development and application is the kv channel on the Deno Discord instance.
\nFinally, check out the code affiliated with this post for simple command-line examples of the things detailed in this article.
\nThe author would like to thank members on the kv channel of the Deno Discord server for their direct and indirect help. In particular, I would like to point out the aid from N.D. Hrones, Andreu Botella, Lino Le Van and Heyang Zhou. Thank you.
\nDeno KV is in its infancy, so there are no mature tools for working with it. The following is a list of some promising utilities to use with KV:
\nThe Deno third-party registry is a place for Deno developers to publish their Deno-compatible ESM modules. It is in essence the Deno equivalent of the npm package manager.
\nThe data in the third-party registry is used as content for the Deno Third Party Modules page. Each module on that page's list links to a page providing module details including documentation, version information and source code.
\nBoth developers who create Deno libraries and users of those libraries should know how the third-party registry works and this post will fill in that gap.
\nRegistered modules can be accessed under the https://deno.land/x/ URL for ESM imports, so, for instance, the Fresh web framework would be accessed using the https://deno.land/x/fresh URL. Module authors are urged to published new versions of their module to a sequentially numbered tagged branch (most authors use semantic version or semver numbering). In that case, the version number would be added to the end of the URL (e.g. https://deno.land/x/fresh@1.1.4).
The original module list was ranked by Github stars, but it was discovered that a lot of the highest ranked entries were npm modules that did not work in Deno using an https://deno.land/x/ import URL. A change to that ranking was first proposed by then Deno team member Kitson Kelly in May 2022. He suggested a sorting algorithm based on metrics of popularity, quality and maintenance (see the proposal for details).
The first implementation of the new ranking algorithm -- deployed in early October 2022 -- uses popularity only. This metric was produced using Google Analytics to track the number of requests to a given third-party library import URL, so that a popularity score of 100 means that 100 requests were made to that module over 30 days. There are no immediate plans to update the ranking algorithm to include quality and maintenance metrics.
\nOnce a module is published in the third-party registry, it cannot be changed or deleted. This makes sure that anyone using a https://deno.land/x/* import URL can be assured that the module will always be there. Module Git tags are also immutable. Any code changes must me published as a new tag.
There is a warning on the third-party module page that name squatting will not be tolerated. It suggests that if a module has not been under active development, it can be taken over by another developer and invites a proposal to do so.
\nThe third-party registry does not support private Github repositories or another Git provider at this point.
\nWhen a module is published the source code in the module's repository is scanned. Each source code file is checked for TSDoc/JSDoc comments for public functions, classes and TypeScript interfaces. If found, the content of the comment is used to create module documentation. If not found, only the signatures of public variables, classes, functions, TS interfaces and type aliases will be displayed with no additional documentation, so it is a good idea to make sure your public module exports are well-documented and include example usage in the TSDoc/JSDoc comments.
\nPublishing a new third-party module is accomplished by clicking on the button on the third-party modules page labelled \"Publish a module\". When that is done, the \"Adding a module\" page will be displayed. It asks for a module name and optionally a subdirectory. It then instructs the module author on how to create a Github webhook so the module can be picked up by the third-party registry automation.
\nThe module list for the Deno Third Party Modules page was pulled from a database via an API. Last October, version 2 of the API was published which coencided with the unvieling of a new ranking algorithm used on the page.
\nThe third party API is hosted at https://apiland.deno.dev. An OpenAPI specification for the API exists in additon to human-readable documentation for the new API spec.
\nThe third-party API has endpoints for module details, module metrics and module documentation (pages). Each endpoint URL begins with https://apiland.deno.dev.
\nThe modules API provides basic information on every third-party Deno module.
\n/v2/modules - Provide a list of all modules in the registry (Link).Here's what the results look like with data from one of the 5,800+ (at the time of this writing) modules shown:
\n{\n \"items\":[ // items module array\n {\n \"latest_version\": \"v0.1.8\",\n \"versions\": [\n \"v0.1.8\",\n \"v0.1.7\",\n \"v0.1.6\",\n \"v0.1.5\",\n \"v0.1.4\",\n \"v0.1.3\",\n \"v0.1.2\",\n \"v0.1.1\"\n ],\n \"name\": \"install\",\n \"description\": \"Deno Binary Installer\",\n \"star_count\": 898,\n \"popularity_score\": 47981,\n \"tags\": [\n {\n \"kind\": \"popularity\",\n \"value\": \"top_1_percent\"\n }\n ]\n }\n // other module data here ...\n ]\n}The following query parameters are available for this endpoint:
\nSo if you wanted to get a list of 10 results on the third page of the modules endpoint, your URL would be https://apiland.deno.dev/v2/modules?limit=10&page=3.
\nLeo Kettmeir from the Deno teams says that you currently cannot request more than 1,000 records (or 100 rows of ten records each) using this endpoint.
\n/v2/modules/:module - Provide information about a specific moduleThis data is the same as an individual record in the v2/modules endpoint. For instance, the data for the Fresh module looks like this:
{\n \"latest_version\": \"1.1.4\",\n \"versions\": [\n \"1.1.4\",\n \"1.1.3\",\n \"1.1.2\",\n \"1.1.1\",\n \"1.1.0\",\n // ... other versions here\n \"v1.0.0\"\n ],\n \"name\": \"fresh\",\n \"description\": \"The next-gen web framework.\",\n \"star_count\": 10133,\n \"tags\": [{ \"kind\": \"popularity\", \"value\": \"top_1_percent\" }],\n \"popularity_score\": 8499\n}/v2/modules/:module/:version - Provide information about a specific module version (Link for Fresh version 1.1.4).Here's what the data looks like for Fresh version 1.1.4:
\n{\n \"upload_options\": {\n \"ref\": \"1.1.4\",\n \"type\": \"github\",\n \"repository\": \"denoland/fresh\"\n },\n \"uploaded_at\": \"2023-03-08T09:48:46.820Z\",\n \"analysis_version\": \"1\",\n \"name\": \"fresh\",\n \"description\": \"The next-gen web framework.\",\n \"version\": \"1.1.4\"\n}/v2/metrics/modules - All module's metrics (Link)The \"metrics\" returned by this endpoint is much more than just metrics. Then include basic data on the module including dependencies, versions and uploaded_at datetime when a new module version github tag was created.
\nThis endpoint supports the query parameters limit and page that is used to determine result set size and page number like the modules endpoint.
\nIf also supports an order_by query parameter which ranks the query results by a particular field value.
\nThe results set for this endpoint puts data in an items array like was done for the modules endpoint above.
\n/v2/metrics/modules/:module - Metrics for a specific third-party moduleHere's what metrics for the Deno web framework Ultra looks like:
\n{\n \"metrics\": {\n \"popularity\": {\n \"prev_sessions_30_day\": 256,\n \"score\": 241,\n \"prev_score\": 266,\n \"sessions_30_day\": 233,\n \"prev_users_30_day\": 283,\n \"users_30_day\": 254\n },\n \"name\": \"ultra\",\n \"updated\": \"2023-04-02T00:24:44.476Z\",\n \"maintenance\": {},\n \"quality\": {}\n },\n \"info\": {\n \"kind\": \"modinfo\",\n \"module\": \"ultra\",\n \"description\": \"Zero-Legacy Deno/React Suspense SSR Framework\",\n \"readme\": {\n \"path\": \"/README.md\",\n \"size\": 4086,\n \"type\": \"file\"\n },\n \"version\": \"v2.2.1\",\n \"tags\": [],\n \"dependencies\": [\n {\n \"ver\": \"\",\n \"src\": \"deno.land/x\",\n \"pkg\": \"color\"\n },\n {\n \"ver\": \"3.3.2\",\n \"src\": \"deno.land/x\",\n \"pkg\": \"crayon\"\n },\n {\n \"ver\": \"v2.5.1\",\n \"src\": \"deno.land/x\",\n \"pkg\": \"hono\"\n },\n {\n \"ver\": \"v1.3.2\",\n \"src\": \"deno.land/x\",\n \"pkg\": \"mesozoic\"\n },\n {\n \"ver\": \"v0.8.0\",\n \"src\": \"deno.land/x\",\n \"pkg\": \"outdent\"\n },\n {\n \"ver\": \"0.1.12\",\n \"src\": \"deno.land/x\",\n \"pkg\": \"wait\"\n },\n {\n \"ver\": \"18.2.0\",\n \"org\": \"\",\n \"src\": \"esm.sh\",\n \"pkg\": \"react-dom\"\n },\n {\n \"ver\": \"18.2.0\",\n \"src\": \"esm.sh\",\n \"org\": \"\",\n \"pkg\": \"react\"\n },\n {\n \"ver\": \"0.176.0\",\n \"src\": \"std\",\n \"pkg\": \"std\"\n }\n ],\n \"upload_options\": {\n \"ref\": \"v2.2.1\",\n \"repository\": \"exhibitionist-digital/ultra\",\n \"type\": \"github\"\n },\n \"latest_version\": \"v2.2.1\",\n \"dependency_errors\": [],\n \"versions\": [\n \"v2.2.1\",\n \"v2.2.0\",\n \"v2.1.7\",\n \"v2.1.7\",\n \"v2.1.6\",\n \"v2.1.5\",\n \"v2.1.4\",\n \"v2.1.3\",\n \"v2.1.2\",\n \"v2.1.1\",\n \"v2.1.0\",\n \"v2.0.1\",\n \"v2.0.0\",\n \"v2.0.0-beta.19\",\n // ... other beta versions\n \"v2.0.0-alpha.19\",\n // ... other alpha versions\n \"v1.0.1\",\n \"v1.0.0\",\n \"v0.8.2\",\n \"v0.8.1\",\n \"v0.8.0\",\n \"v0.7.6\",\n \"v0.7.5\",\n \"v0.7.4\",\n \"v0.7.3\",\n \"v0.7.2\",\n \"v0.7.1\",\n \"v0.7.0\",\n \"v0.7.0\",\n \"v0.6\",\n \"v0.5\",\n \"v0.4\",\n \"v0.3\",\n \"v0.2\",\n \"v0.1\",\n \"v0.0\"\n ],\n \"uploaded_at\": \"2023-02-06T08:34:08.756Z\",\n \"config\": {\n \"path\": \"/deno.json\",\n \"size\": 867,\n \"type\": \"file\"\n }\n }\n}Under the popularity field, a \"session\" is defined by Google analytics as a visit to a page for 30 minutes or less.\nThe users field value also comes from GA.
\nNote that there is are quality and maintenance metric fields which were part of the original page ranking proposal, but they are unused right now.
\nThe pages API focuses on data for the module documentation pages. Third party API routes that begin with v2/pages are used to display API documentation for a particular Deno module.
/v2/pages/mod/doc/:module/:version/:path* - Provides data to render a documentation page for a moduleFor instance, to pull up the types.ts file documentation data, you would use the URL: https://apiland.deno.dev/v2/pages/mod/doc/std/0.182.0/testing/types.ts which is the data that is rendered in this page.
Obviously, the third-module registry API provides a lot of data to work with. You could essentially create your own version of https://deno.land/x. This version could be supercharged with information in the API not found on the Deno Third Party Modules pages. Ranking the results by a different characteristic would be interesting or you could create your own popularity score algorithm.
I have create a simple prototype that displays the Deno Third Party Modules page data showing the top 500 modules and adding the Github star count to each module record. You can see it in action here.
\nThis page includes a drop-down to sort the top 500 results by popularity score, Github star count or a combination of popularity score (weighted 75%) and GH star count (weighted 25%).
\nThis demo shows one of the many ways the API data could be displayed. Graphical renditions would be an interesting option, for instance.
\nThe code for my API demo is found at this github repository.
\nThis article focused on the Deno third party modules list and the API used to create that list.
\nThe API was used to revise the way modules are sorted on the Deno Third Party Modules page. Still, this new ranking is just an initial implementation of the original algorithm proposed by Kitson Kelly who no longer works for Deno. If you are interested in improvements to the ranking system, you should post comments to that proposal.
\nFinally, take a look at my demo app that used the third party API to show different module ranking views. There are numerous other ways to display and analyze data coming from the API and I urge you to use your imagination and technical skill to improve on my humble prototype.
\nThe author would like to thank former Deno team member Kitson Kelly for answering some questions on the API last fall, and current Deno team member Leo Kettmeir for recently filling in my third-party module API knowledge gaps. Leo also reviewed this article before it was published and I thank him for his thoughtful comments.
\nSQLite is a lightweight database available on most platforms. It is designed to exist in memory or persist to a local file system. This post will discuss how to interact with a SQLite database in Deno.
\nAt this point Deno-native[1] libraries are the only Deno SQLite client options since the npm sqlite3 client does not work when run in Deno using the npm: prefix because postinstall scripts are not supported by Deno yet when importing with the npm: prefix (it is on the roadmap).
There are two Deno-native third-party libraries that are SQLite clients (aka drivers). Both of them work with SQLite version 3, the current version. They are deno-sqlite and sqlite3.
The deno-sqlite third-party library contains both a SQLite client and a SQLite implementation compiled as a Web Assembly Module (WASM). This allows SQLite to be used in a Deno program without need for an external SQLite engine. This library is named sqlite in the Deno third-party module registry while the Github repository is called deno-sqlite which is the name I will use in this post.
The sqlite3 library is just a SQLite client. But it is designed with performance in mind as it uses the Deno Foreign Function Interface (FFI) to allow access to native file reading and writing functionality rather than going through a JavaScript wrapper around native I/O access built into Deno.
This post will explore how to do CRUD operations with each library using code snippets. There is a corresponding repo folder that contains full working examples of the code in this post.
\nPersistence using deno-sqlite revolves around the DB class. The constructor can be used to point to a file-based database or one held in memory using the default constructor (or the \":memory:\" token as a constructor argument).
import { DB } from \"https://deno.land/x/sqlite@v3.7.0/mod.ts\";\n\n // Open a database to be held in memory\n const db = new DB(\":memory:\"); // or new DB()\n // Use new DB(\"file.db\"); for a file-based database\n db.execute(`\n CREATE TABLE IF NOT EXISTS people (\n id INTEGER PRIMARY KEY AUTOINCREMENT,\n name TEXT\n )`);\n\n // Insert data within a transaction\n db.transaction(() => {\n for (const name of [\"Peter Parker\", \"Clark Kent\", \"Bruce Wayne\"]) {\n db.query(\"INSERT INTO people (name) VALUES (?)\", [name]);\n }\n });\n\n // Todo: Other CRUD operations here...\n\n // Close database to clean up resources\n db.close()The DB.transaction method is used for transactional control. If the function argument throws an error, the transaction is rolled back; otherwise it is committed. This transaction method can also be used for updates and deletes.
The sqlite3 library uses a Database class to initiate persistence. It's constructor takes a file path or \":memory:\" token for an in-memory database. The constructor also takes an options argument with a number of fields that are detailed in the documentation.
import { Database } from \"https://deno.land/x/sqlite3@0.8.0/mod.ts\";\n\n const db = new Database(\":memory:\"); // or a file name/path\n db.exec(`\n CREATE TABLE IF NOT EXISTS people (\n id INTEGER PRIMARY KEY AUTOINCREMENT,\n name TEXT\n )`);\n // insert data in a transaction\n const inserts = db.transaction((data: string[]) => {\n for (const name of data) {\n db.exec(\"INSERT INTO people (name) VALUES (?)\", [name]);\n }\n });\n inserts([\"Peter Parker\", \"Clark Kent\", \"Bruce Wayne\"]);\n\n // Todo: Other CRUD operations here...\n\n // Close database to clean up resources\n db.close();The Database.transaction method is used to modify SQLite data in a transactional context. Unlike deno-sqlite, the transaction method returns a function that needs to be called with the SQL operation's data in order to run the transaction. But like deno-sqlite, the sqlite3 transaction behavior depends on whether an error is thrown in the function (rollback) or it cleanly returns (commit).
The deno-sqlite lib has two ways of running a query. The first uses the DB.query method.
// Todo: create a table and fill with data as above.\n const results = db.query<[number, string]>(\n \"SELECT id, name FROM people\",\n );\n\n for (const [id, name] of results) {\n console.log(`${id}: ${name}`);\n }The second way of running a query in deno-sqlite is with a prepared statement which uses the DB.prepareQuery method which returns an object that conforms to the PreparedStatement interface.
// Todo: create a table and fill with data as above.\n\n const query = db.prepareQuery<[number, string]>(\n \"SELECT id, name FROM people\",\n );\n\n for (const [id, name] of query.iter()) {\n console.log(`${id}: ${name}`);\n }\n\n query.finalize();In this example, preparedQuery returned the query object as a PreparedQuery interface type. There are three ways to bind parameters and get results from a Prepared query:
The iter method binds the parameters to the query and returns an iterator over rows. Use this if there are multiple rows in a result set because it avoids loading all returned rows into memory at once allowing a large number of rows to be processed sequentially.
The all method binds the data and returns a full result set in an array.
The first method returns the first item of a result set returned by the query.
You also need to run the finalize method on the PreparedQuery or you will get an error message:
Uncaught SqliteError: unable to close due to unfinalized statements or unfinished backups\n throw new SqliteError(this.#wasm);While you can dynamically create a SQL string and run a query on the resulting string using the DB.query method, it can easily cause a SQL Injection attack on your database. To avoid that problem always use prepared statements with parameterized queries (i.e the DB.prepareQuery method).
The sqlite3 library only uses prepared statement to do queries. A Statement object is returned from the call to Database.prepare.
// Todo: create a table and fill with data as above.\n\n // Create a prepared statement\n const stmt = db.prepare(\"SELECT id, name FROM people where id=:id\");\n // Bind the parameter to the statement\n const row = stmt.bind({ id: 1 });\n console.log(`Row for id 1: `, row.get(1));\n stmt.finalize(); // not required, otherwise finalization is automaticThe Statement.bind method is one of may ways to bind parameters to prepared statements. Other Statement methods used to bind data are
all - Run the query and return the resulting rows in objects with column name mapped to their corresponding values.values - Run the query and return the resulting rows where rows are array of columns.run - Run the query with it returning the number of rows in the result set. To get the resulting rows, you must then call Statement.get() with the row number (starting with 1) to get the individual data rows.Updating the database with both SQLite libraries uses prepared statements (i.e. the same methods) like when running a query (db.prepareQuery or Database.prepare).
// Todo: create a table and fill with data as above.\n const id = 1;\n const newName = \"Wade Winston Wilson\";\n const query = db.prepareQuery<[number, string], { name: string; id: number }>(\n `UPDATE people set name=? where id=:id`,\n );\n query.all([newName, 1]);\n query.finalize();\n // Todo: Verify that data has been updated and close the databaseAs with querying, a PreparedStatement object needs to be finalized when the update has been completed or a SqliteError will be thrown.
// Todo: create a table and fill with data as above.\n const id = 1;\n const newName = \"Wade Winston Wilson\";\n const stmt = db.prepare(`UPDATE people set name=? where id=?`);\n stmt.run(newName, id);\n // Todo: Verify that data has been updated and close the databaseLike updating, data deletion using both SQLite libraries follows the same pattern as querying by using the db.prepareQuery or Database.prepare methods.
// Todo: create a table and fill with data as above.\n const id = 1;\n const query = db.prepareQuery<[number, string], { name: string; id: number }>(\n `DELETE from people where id=:id`,\n );\n query.all([1]);\n query.finalize();\n // Todo: Verify that data has been deleted and close the database // Todo: create a table and fill with data as above.\n const id = 1;\n const stmt = db.prepare(`DELETE from people where id=?`);\n stmt.run(id);\n console.log(`Deleted record for id ${id}`);\n stmt.finalize();\n // Todo: Verify that data has been deleted and close the databaseWhen verifying that a record has been deleted you need to note that a query containing no results returns an empty array with deno-sqlite while the sqlite3 lib returns undefined.
SQLite was originally designed to be a lightweight database with data stored in a single file. As a consequence of that fact many web developers used it to do local development or to run integration and end-to-end tests.
\nModern web applications run in the cloud and all the major cloud platforms including Amazon Web Services, Azure and Google Cloud Platform support SQLite on their platform. Besides the big three, other cloud providers with SQLite support include fly.io and Digital Ocean.
\nDistributed SQLite implementations are also available including LiteFS from fly.io RQLite, DqLite by Canonical, mvSQLite and DBHub.
\nAn interesting article on migrating from PostgreSQL to SQLite using LiteFS shows what is involved with using a distributed SQLite implementation.
\nI have tried to provide an objective comparison in this post between the Deno-native SQLite libraries deno-sqlite (sqlite) and sqlite3 and not play favorites. It is up to you to try each of them out and decide which one works for your use case.
This post covers a subset of the deno-sqlite and sqlite3 APIs, so it is a good idea to check the documentation for more details.
Documentation for the deno-sqlite lib is found in the third-party registry pages for sqlite where you need to drill-down though the hyperlinks for function and TypeScript interface documentation. This documentation is generated from the jsdoc source-code comments for each TS interface and JavaScript public function and class.
Documentation for the sqlite3 library is more centralized in the repo's doc.md file.
Finally, make sure you check out the companion Github Repository to this article to see working examples of all the CRUD operations for both libraries discussed here.
\nDeno-native is used here to indicate that the module is a Deno third-party library compatible with Deno and not an npm module requiring the use of the npm: prefix in the import URL.
Ultra is a full stack framework for building Deno webapps\nusing React. Ultra recently released version 2.0 that is more customizable than v1.
\nUltra works by streaming React-generated HTML markup from the server. Version 2 of the app is designed to run under React 18+ which supports React Suspense. Suspense allows asynchronous loading of components that need to do some time-intensive work on the server -- such as data fetching -- before they are rendered. The React.Suspense component provides a fallback prop to display a loading indicator component before the suspended child component is rendered.
This article will demonstrate how to use Ultra to create and deploy a React app. Source code can be found in this Github repo and the application is deployed on Deno Deploy here.
\nThe best way to create a Ultra project is to use the create CLI script\n(create.ts). You run it by invoking:
deno run -A -r https://deno.land/x/ultra/create.tsThe script will then ask for the project name and whether you want to use TypeScript or JavaScript. The project name will become the folder name where the project exists under the folder where you ran the script, so it's best not to have any spaces in the project name.
\nThe script will then request what libraries you would like to use with your Ultra app. The options are for:
\nstyle.css file.App component inside app.tsx with HEAD and BODY elements.Other React libraries still can be used in a an Ultra app, These libraries and other options are demonstrated in the examples folder of the Ultra repo.
The key files and folders in an Ultra app include code to compile and run the app, and setup code for many libraries so it is important to know what is going on with them.
\nThey include:
\nimportMap.json: The HTML-standard import map that allows an alias to be used in place of a JavaScript/TypeScript url in an ECMAScript import statement.
deno.json: The Deno config file used for various things including command line scripts (like the scripts section of package.json) under the \"tasks\" property. Invoke a task using the deno task <task name> command. Make sure you reference the path to the app's import map as the value of the \"importMap\" property. Also, with the \"lint\" and \"fmt\" properties you'll want to exclude the .ultra folder.
server.ts: This is the app's entry point as it is invoked on the Deno command line when the \"dev\" and \"start\" tasks are run. It works with the Hono server library. React Router and other libraries need to have setup code put in this file. This can be tricky which is why I suggest using the create.ts app to add libraries.
client.ts: This is the client's entry point that hydrates the app when it is rendered in the browser. The ClientApp function returns the home page with components and should be wrapped in context providers needed for the app to function.
build.ts: Used to build the app and dependencies into a .ultra folder. Add any files you do not want to be deployed to the builder.ignore call in that file. Also put code into this file for any additional build compilation or transformations. For instance, an MDX compile step is done in the with-mdx example. Also note build options detailed in the lib/build/types.ts file in the Ultra repo.
src/app.tsx: The React app's entry point. The create.ts script will generate an App component in this file that returns example content wrapped in an HTML tag that includes HEAD and BODY elements.
public folder: This app holds the app's assets including images, CSS files and other static content.
.ultra folder: Holds the result of an Ultra build that will get deployed to production.
I created a TypeScript app that used Tailwind, React Router and React Query. I employed the create script to scaffold out the app which adds context providers for React Router and React Query to server.ts and/or client.ts.
My app uses the jsonplaceholder API with React Query to display fake users and blog posts. You can see it in action here. To run the app locally invoke deno task dev from the command line. Find the app's code in this repo.
The React Router (v6) context provider was setup in both server.ts and client.ts. Note that the StaticRouter is used for server-side rendering while the client file uses BrowserRouter.
The routes for both server and client are configured in app.tsx. Here's what that looks like:
<Routes>\n <Route path=\"/\" element={<Layout />}>\n <Route index element={<HomePage />} />\n <Route path=\"about\" element={<AboutPage />} />\n <Route path=\"user_details/:userId\" element={<UserDetailsPage />} />\n <Route path=\"*\" element={<RouteNotFound />} />\n </Route>\n </Routes>Each of the routes point to a page component that wraps the page's content. The Layout component defines a Layout Route which forms a shell around other components containing the app's header and footer. Routes defined inside the Layout Route hold the content (HomePage, AboutPage, UserDetailsPage and RouteNotFound page in this case).
The Layout component uses an Outlet component to defined where the child components go as the children prop did previously. This is what that component's return value looks like (styling removed):
<>\n <header>\n <nav>\n <NavLink to=\"/\">Home</NavLink>\n <NavLink to=\"/about\">About</NavLink>\n </nav>\n <div>\n <h1>Ultra Demo App</h1>\n </div>\n </header>\n <main>\n <Outlet/> {/* Child components here */}\n </main>\n <footer>\n <div>\n <a href=\"https://ultrajs.dev\">\n Built with Ultra\n </a>💎\n </div>\n </footer>\n </>See the React Router docs for more details on version 6 of the library.
\nReactQuery is a data management API used in the app to make API calls for user data. It provides intelligent caching, prefetching and pagination features among others. Version 4 also supports React suspense for asynchronous data fetching.
React Query setup in Ultra is somewhat complicated, so it is advised that you bring it in when running the create.ts project-creation script. You'll noticed that a src/react-query folder has been created. The query-client.ts file inside that folder initializes a QueryClient class containing a suspense: true option for React suspense support.
The useDehydrateReactQuery.tsx file in the react-query folder uses the helper hook useServerInsertedHTML included in the Ultra distribution. The useDehydrateReactQuery function serializes the query client's fetched data on the server side storing it in a window property called __REACT_QUERY_DEHYDRATED_STATE. This is all done when server.tsx is invoked at app startup.
Query data rehydration is done in client.tsx using the Hydrate component from React Query.
// client.ts\nimport { Hydrate } from \"@tanstack/react-query\";This component is added to the JSX returned from the ClientApp() function:
// Other code is missing\n <Hydrate state={__REACT_QUERY_DEHYDRATED_STATE}>\n <BrowserRouter>\n <App />\n </BrowserRouter>\n </Hydrate>Recall that __REACT_QUERY_DEHYDRATED_STATE was populated in server.tsx.
QueryClientProvider, react query's context provider, is added to both the client (client.ts) and server (server.ts) file. It is imported from @tanstack/react-query.
The popular Tailwind CSS class collection is supported by the twind library. Twin compiles Tailwind CSS classes into generic CSS on the fly so it is ideal for Ultra's streaming server.
Tailwind classes are expressed using the tw function. Here is an example how it is used:
import { tw } from \"./twind/twind.ts\";\n// other code here\n <h2 className={tw(`text-3xl font-bold`)}>\n About this Site\n </h2>Check the Tailwind docs for details on the available Tailwind classes. Support for Twind 1.0 was recently added to Ultra which is compatible with Tailwind version 3.
Ultra version 2 works with React v18. A big feature of this new React version is suspense. React suspense allows a component to be asynchronously rendered. This means that part of the UI can be displayed while suspended components are still being rendered.
\nSetting up suspense involves wrapping a component with the Suspense component. This is what that looks like:
// Home.tsx\nimport { Suspense } from \"react\";\n// other code here...\n <Suspense fallback=\n {<div>Page is Loading...</div>}\n >\n <UserList />\n </Suspense>In this case the UserList component is being suspended. Note the fallback prop that is used to define a component that will be displayed while the suspended component is still being rendered. Once that is completed, the suspended component will replace the fallback component.
When a Suspense component is used in an application page, the page needs to be lazy loaded with a dynamic import:
// app.tsx\nconst HomePage = lazy(() => import(\"./pages/Home.tsx\"));As noted above Ultra uses the Hono Deno server under the covers. Hono's Deno server is based on the http server in the Deno standard library. But Hono adds value that can be used in an Ultra app. A big one is middleware.
\nThe createServer call in server.tsx returns a Hono server object in a variable called server. Middleware is added with a call to server.get. The first argument is a string representing an http path. The second argument is a handler function with a Context first argument and next function as the second argument.
The handler function can either return a Response or Promise<Response | undefined | void> or invoke the next function using an await since next returns a Promise. The next function passes the request flow onto the next server.get located in server.tsx (see the definition of Handler in src/types.ts in the Hono repo and the Middleware docs).
Here is an example of middleware that adds a header to the response called \"Server\" with a value of \"Ultra Hono\":
\nserver.use('*', async (c, next) => {\n c.res.headers.set(\"Server\", \"Ultra Hono\");\n await next();\n});Hono provides a bunch of built-in middleware functions including ones for authentication, CORS support and serving static files.
\nHono can also be used for server-side routing. If authentication middleware is used, then server-side routing is required.
\nYou can create an API route using Hono too. See the with-api-routes Ultra example to learn how this is done in addition to the Hono routing docs.
\nNote that the Hono API supports Node and Cloudfare Workers in addition to Deno. See the Hono Deno docs for more details on the Hono Deno server.
\nThere are over 20 examples in the Ultra repo's examples folder. Most of them show how to use React libraries with Ultra. They include (besides libs detailed above):
\nexamples/bogus-marketing-or-blog folder. Note the generateStaticHTML and disableHydration properties added to the server.render function call in server.tsxWhen adapting one of these examples to your application, pay particular attention to changes in server.tsx, client.tsx and sometimes build.ts that allows the example to work with Ultra.
There are two main options for deployment an Ultra app, using Docker to deploy to cloud hosts that support it like fly.io and Deno Deploy. Instructions are found in the Ultra deployment docs.
\nWhen using Deno Deploy, you need to set inlineServerDynamicImports: true as a createBuilder option in build.ts since Deploy does not support dynamic imports. Also note the Github Action needed to use Deno Deploy with Ultra.
Production deployment requires that all the images and other assets are wrapped in a useAsset hook from Ultra like this:
import useAsset from \"ultra/hooks/use-asset.js\";\n// other code here\n <link rel=\"shortcut icon\" href={useAsset(\"/favicon.ico\")} />The useAsset hook is used to version the asset during a production build.
To build and dry-run the app before production deployment, invoke the build task locally and then run the start task inside the .ultra folder.
Ultra is the third most popular Deno web framework next to Fresh and Aleph which are both supported by the Deno team. It is the only one of the three that focusses on React and does a good job at supporting React libraries and modern practices.
\nUltra evolved dramatically between version 1 and 2 and its development continues to accelerate. When this post was published Ultra's current version was v2.1.4, so be aware that there might be some changes at a future date.
\nAt any rate, Ultra is a good option for creating React apps because it eliminates the build step with it's headache-inducing configurations therefore allowing you to focus on application development.
\nFinally, make sure you check out my Ultra demo app repo and the examples folder in the Ultra repo for more ideas on how to use Ultra to create a Deno/React app.
\n", "url": "https://deno-blog.com/Building_Fullstack_React_Apps_with_Ultra.2022-12-04", "title": "Building Fullstack React Apps with Ultra", "summary": "Building Fullstack React Apps with Ultra", "date_modified": "2022-12-04T00:00:00.000Z", "author": { "name": "Craig Doremus" } }, { "id": "https://deno-blog.com/Using_Preact_Signals_with_Fresh.2022-11-01", "content_html": "\nFresh is the Deno full-stack framework created by Luca Casonato of the Deno core team and now hosted in the Deno github repository.This blog post assume you have some familiarity with Fresh. If not, see the Fresh documentation to get up to speed.
\nFresh uses Preact for the UI. Recently the Preact team has released a new library called Signals for reactive state management. Preact Signals are used for both global and local state management.
\nThis post will demonstrate how to use Signals with Fresh. I created a basic Fresh Todo app to illustrate the use of Preact Signals. The source code can be found in this Github repo.
\nAs of Fresh version 1.1, when you create a new fresh project the signals libraries are automatically added to the import map file.\nIf you are updating a Fresh project to use Signals, add the following lines to the imports section in your import map:
{\n \"imports\": {\n # other imports here\n \"@preact/signals\": \"https://esm.sh/*@preact/signals@1.0.3\",\n \"@preact/signals-core\": \"https://esm.sh/*@preact/signals-core@1.0.1\"\n }\n}All the Signals functions we will be using are located in the @preact/signals module.
The Todo app encapsulates global state management inside a function called createAppState (in state.ts). The signal function is used to add a field to global state:
function createAppState(): AppStateType {\n // create signals for todo array and current todo\n const todos = signal<string[]>([]);\n const currentTodo = signal<string>(\"\");\n // other stuff here...\n return {todos, currentTodo, /* Other function properties here...*/}\n}\n// function return value is the default export\nexport default createAppState();In this case, the current todo (currentTodo) and a todos array (todos) are held in an object returned by createAppState. Each call to the signal function takes an object or primitive argument that represents the initial value of that signal.
Functions that update the signals are also contained in createAppState (addTodo and removeTodo) and made available to other modules in the return value of that function (also note the TypeScript type AppStateType defined in state.ts).
function createAppState(): AppStateType {\n // ... todos, current todos signals created here as is todoCount ...\n\n const addTodo: AddTodoFunction = (e: Event): void => {\n e.preventDefault();\n todos.value = [...todos.value, currentTodo.value];\n currentTodo.value = \"\";\n };\n\n const removeTodo: RemoveTodoFunction = (index: number): void => {\n todos.value = todos.value.filter((_todo: unknown, i: number) =>\n i !== index\n );\n };\n return { todos, currentTodo, addTodo, removeTodo, todoCount /* todoCount explained below */ };\n}\nexport default createAppState();We will be using the createAppState function to pass signals and functions to the app's components. Ths done through the Preact\nContext (similar to React Context). Application state -- including the signals previously created -- is added to the context in the root component App (see App.tsx) using a context provider:
import { createContext } from \"preact\";\nimport state, { type AppStateType } from \"../state.ts\";\n\n// create the AppState context\nexport const AppState = createContext<AppStateType>({} as AppStateType);\n\nexport default function App() {\n return (\n <AppState.Provider value={state}>\n // Components that use the state here ...\n <AppState.Provider>\n );\n}The state field in the App module is the return value of the createAppState function (see state.ts). AppState.Provider is a Preact context provider which exposes state to the rest of the app enclosed within its component tree.
The state held in the context can be accessed by any of the app's components with the useContext function. Here it is used by the TodoList component to access the list of todos:
import { useContext } from \"preact/hooks\";\nimport { AppState } from \"./App.tsx\";\nimport Todo from \"./Todo.tsx\"\n\nexport default function TodoList() {\n // Destructure state to expose the todos signal\n const { todos } = useContext(AppState);\n return (\n <div className=\"todos\">\n // use the value property to obtain the todos array\n {todos.value?.map((item: string, i: number) => {\n return (\n <Todo text={item} index={i} />\n );\n })}\n </div>\n );\n}The object returned from a call to signal always contains a value field which is the current value of the signal. In the Todo app there are signals for all todos (todos, an array of strings) and the current todo (currentTodo, a string). The value of todos is obtained from this expression: todos.value.
The value property can also be used to set the value of a signal. There is no built-in setter like there is in the useState hook. Signal value mutation is done in the addTodo and removeTodo functions. The same thing can be done outside the app state object returned from createAppState. This is what is done in the input's onChange handler in AddTodo.tsx:
<input\n { /* other attrs missing here... */}\n value={currentTodo.value}\n onChange={(e) =>\n currentTodo.value = (e.target as HTMLInputElement).value}\n />Note that the type coercion of the event target is needed because of a bug in the current Preact TypeScript typings.
\nThe function computed is included in the Preact Signals module. Signals that are used within computed are subscribed to the signal and notified when the signal's value changes. That allows computed to derive values based on the value of one or more signals. When computed is notified of a signal value change, it automatically re-runs the callback function sent in as an argument. An example is found in the createAppState function in state.ts:
const todoCount = computed(() => todos.value.length);When todos.value changes, the callback function gets re-run and todoCount gets updated with the new count.
The use of local signals is illustrated with the Counter.tsx component that I've piggy-backed on to the Todo app for illustrative purposes.
\nThe Counter component counts button clicks and stores the counts in local storage so the current count can be recovered when the page is reloaded. Preact Signals is used to hold local state in this component.
Using signals for local state requires use of the useSignal hook. There is also a useComputed function that can be used for local computed values.
This is how the Counter component holds component state:
export default function Counter() {\n const COUNT_KEY = \"COUNT\";\n const count = useSignal<number>(parseInt(localStorage.getItem(COUNT_KEY) ?? \"0\"));\n // other code here...\n}The count is stored in local storage, so when the count signal is instantiated using useSignal, it pulls the count from local storage if it exists. Note that useSignal is for local state, while signal is used for global state. Also note that useSignal does not return a setter function like useState. The state value can be obtained from the signal (count.value in this case) and that value can be mutated directly as occurs in this button's onClick handler (in Counter.tsx):
<button onClick={() => {\n count.value = 0;\n localStorage.setItem(COUNT_KEY, \"0\");\n }}>Reset Count</button>The useComputed function is used for computing new values based on one or more signal's value. It is used for local state calculations, while computed is used for global state calculations. Both variations are subscribed to any signal that is contained within its function argument, so when the signal is updated, both useComputed and computed function arguments are automatically invoked. In the case of the Counter component, useComputed is used to calculate the counter value squared. Any time that a signal changes, the useComputed function is re-run if it uses that signal (count in Counter.tsx).
const square = useComputed(() => count.value * count.value);The effect function in the signals module is used to handle side effects like useEffect. However, effect does not have a dependency array like useEffect. Instead the effect is subscribed to signals contained within the callback function, so when a signal's value changes, the effect function is notified of that change and the callback is invoked. In Counter, the effect is used to update the count in local storage.
const dispose = effect(() => {\n localStorage.setItem(COUNT_KEY, count.value.toString());\n console.log(`Double: ${square.value}`)\n });\n useEffect(() => {\n return () => {\n // free-up effect's memory\n dispose();\n };\n }, []);The effect function returns a function (called dispose in this case) that can be used to invalidate the effect and free up memory that it uses. In this case we call dispose in the function returned by useEffect which gets called when the component is unmounted.
An effect can be nested inside another effect. Then you can make sure the signal only runs once like this:
// From Ryan Carniato stream: https://www.youtube.com/watch?v=QRtrS_SvR4w&t=10909s\nlet dispose;\neffect(() => {\n // clean up signal after it runs once\n if (dispose) dispose();\n // outer side effect here\n dispose = effect(() => {\n // inner side effect here\n });\n});In this code, the first time the outer effect callback is invoked, the dispose function is not run because it has not been assigned a value, but after the inner effect callback is invoked, then the outer effect disposes it.
The effect function can be used to work with both global and local state.
The batch function is used to update multiple signals at a time for performance optimization. For instance, the todo array and current todo could be updated together in this manner:
batch(() => {\n currentTodo.value = \"Another thing I have to do\";\n todos.value = todos.value.push(currentTodo.value)\n });The peek function is attached to a signal's value. It is used to get the value of a signal without subscribing to the signal. Once peek is called on a signal, any updates to the signal's value are not passed along to the return value. For example:
const countNow = count.value.peek();In this case, countNow will not be updated if count.value changes after the call to count.value.peak.
This post shows how to use the Preact signals module with Deno Fresh. Snippets from the post's source code Github repo have been used here, so make sure you check it out to get a complete picture of how everything fits together. Also see the README.md file for details on how to run the app locally.\nFinally, you should review the Preact Signals documentation for more details on the Signals API and its use.
\n", "url": "https://deno-blog.com/Using_Preact_Signals_with_Fresh.2022-11-01", "title": "Using Preact Signals with Fresh", "summary": "Using Preact Signals with Fresh", "date_modified": "2022-11-01T00:00:00.000Z", "author": { "name": "Craig Doremus" } }, { "id": "https://deno-blog.com/Processing_CSV_files_with_Deno.2022-09-20", "content_html": "\nThe CSV (Comma-Separated-Values) format is one of the most common ways to do\ndata interchange between systems. The Deno standard library contains a\nencoding/csv.ts module to facilitate reading and writing CSV files. The\nstringify function in that module converts a JavaScript (or JSON) object into\na CSV line while the parse function converts a CSV-formatted line back into an\nobject. This post explores transforming API data into CSV and back to JS\nobjects. Source code for this blog post can be found at\nhttps://github.com/cdoremus/deno-blog-code/tree/main/processing_csv.
A small amount of data is easily processed in a single write and read to and\nfrom a text file. In this case we use the Deno.writeTextFile and\nDeno.readTextFile functions to put or get CSV data in a single call.
We will be processing JSON data from an API called\nJSONPlaceholder which provides fake\ndata for many common resources like users, blog posts and todos. The JavaScript\nbuilt-in fetch function will be used to call the API. Here's what a call to\nget a list of users looks like:
async function fetchData(): Promise<User[]> {\n const resp = await fetch(\"https://jsonplaceholder.typicode.com/users\");\n return await resp.json();\n}The TypeScript-defined User type returned in a JS promise contains id, name\nand email keys.
Once the API data has been fetched, the stringify function from the\nencoding/cvs.ts module is used to format the data into CSV before it is\nwritten to a text file:
async function writeToFile(users: User[]): Promise<void> {\n const stringified = await stringify(users, USER_COLS);\n await Deno.writeTextFile(USER_FILE, stringified);\n}The stringify function takes an array of data to be persisted as CSV as the\nfirst argument and a string array of columns. Make sure that data and the column\narray are in the same order. The users array is filled with user objects\nhaving id, name and email keys corresponding to the JSON returned from the API\ncall. The USER_COLS object is a string array containing the names of the\nobject keys.
The encoding/csv.ts module's stringify function has an optional third\nargument that is an object with headers and separator keys. The headers\nkey (true by default) indicates whether a header containing the data's keys (id,\nname, email in this case) should be written to the file as the first line. The\nseparator key indicates the delimiter used to separate items (a comma by\ndefault, but any character can be used as a separator).
Finally, the delimited items are written to a file using the\nDeno.writeTextFile function.
See\npopulate_data.ts\nin the blog source code repo for more details.
\nReading CSV from a small file is done using Deno.readTextFile. In addition,\nthe encoding/csv.ts module contains a parse function that facilitates the\ntransformation of CSV data into an array of objects.
async function readCsvFile(): Promise<User[]> {\n const file = await Deno.readTextFile(USERS_FILE);\n return parse(file, { skipFirstRow: true, columns: USER_COLS }) as User[];\n}The second argument of parse contains an options argument which is an object\nwith skipFirstRow and columns keys. The skipFirstRow key indicates if you\nshould skip the first row which contains the column names (false by default).\nThis (skipfirstRow) needs to be set to true if you set headers to true\nin the stringify call. The columns key is an ordered array of column\nheaders. You need to make sure that the columns order corresponds to the order\nof data in each CSV row.
The columns values will be used as the keys for the objects being created from\nthe CSV data. Otherwise, you will just get an array of string arrays containing\nthe CSV data, so if you want the original object recreated, then columns needs\nto be used in your parse call.
See\nread_data.ts\nin the blog source code repo for more details.
\nWhen a large amount of data is needed to be processed, it cannot be done in a\nsingle operation due to memory constraints. In that case, the Deno.open\nfunction can be used. That function takes two arguments. The first is the\nabsolute or relative file path while the second is an object with read,\nwrite, append, create and createNew keys. The other Deno.open keys,\ntruncate and mode, are not relevant here.
We will be using the JSONPlaceholder post API here:
\nasync function fetchData(page_number: number): Promise<Post[]> {\n const resp = await fetch(\n `https://jsonplaceholder.typicode.com/posts?_limit=10&_page=${page_number}`,\n );\n return await resp.json();\n}The JSONPlaceholder posts API only contains 100 records. We will be writing 10\npages (chunks) of 10 records each. I created a TypeScript type Post that\ncontains the keys from the post API (userId, id, title and body).
Each of the post data chunks are written to the CSV file using the stringify\nfunction after a Deno.open call. Files opened in this manner need to be\nwritten as a byte array (Uint8Array).
async function writeToFileChunk(posts: Post[]) {\n const file = await Deno.open(POSTS_FILE, {\n append: true,\n });\n try {\n const stringified = await stringify(posts, POST_COLS, { headers: false });\n const byteArray = new Uint8Array(stringified.length);\n const encoder = new TextEncoder();\n encoder.encodeInto(stringified, byteArray);\n file.write(byteArray);\n } finally {\n file.close();\n }\n}A file reference obtained from calling Deno.open needs to be manually closed\nwhen finished. The best way to do this is in a finally block as I have done\nhere.
Since the file is written multiple times in append calls, we turned off the\nheaders option. Instead the headers will be written before the post API data\nis written.
export async function writeCsvHeader() {\n // change this if using a different CSV separator\n const header = POST_COLS.join(\",\");\n await Deno.writeTextFile(POSTS_FILE, `${header}\\n`);\n}There's one more thing that needs to be done to the post data. The body field\nhas a number of newline characters in it. These will interfere with the parse\nfunction in the encoding/csv.ts module that uses newlines to separate object\nrecords. In this case, I assume that the newlines have some significance, so I\nreplace each newline in the post body field with a pipe character (|). When\nthe data is used, then the pipe can be converted back to a newline or into\nsomething else (an HTML break tag, for instance).
async function main() {\n // Delete previously written file, if exists\n try {\n await Deno.remove(POSTS_FILE);\n } catch (_e) {\n // ignore, since file probably does not exist\n }\n // write header with object keys first\n await writeCsvHeader();\n // write data\n for (let i = 1; i <= TOTAL_API_PAGES; i++) {\n const users = await fetchData(i);\n // get rid of newlines from body field\n // so that parse function in cvs module works\n for (const post of users) {\n post.body = post.body.replaceAll(\"\\n\", \"|\");\n }\n await writeToFileChunk(users);\n }\n}See\npopulate_large_data.ts\nin the blog source code repo for more details.
\nReading data from a large CSV file involves in using the Deno.open function\nwith the read:true option.
I used the TextProtoReader in the textproto module to process the CSV data\nin chunks, a line at a time. That class' constructor takes a BufReader object\n(io/buffer module) with a file object passed in.
TextProtoReader.readline() is used to read a line of the CSV file and then\nparse in the encoding/csv module is used to transform each CSV line into a\npost object.
async function readLargeCsv() {\n const file = await Deno.open(POSTS_FILE, { read: true });\n\n const reader = new TextProtoReader(BufReader.create(file));\n let lines = \"\";\n while (true) {\n const line = await reader.readLine();\n if (line === null) break;\n lines = lines + line + \"\\n\";\n }\n // Convert CSV lines into Post objects\n const record = await parse(lines, { skipFirstRow: true, columns: POST_COLS });\n // Display Post records\n console.log(record);\n}I am just printing the objects to the console here for illustration, but there\nare a lot of other things that can be done with it such as displaying the\nobjects in a UI.
\nSee\nread_large_data.ts\nin the blog source code repo for more details.
\nThis article demonstrates how to use the Deno encoding/csv module to convert\ndata from an object representation (like JSON) to CSV and back again. I have\nused snippets here from the\nsource code for this article,\nso check out the source to see how everything fits together. A comment at the\ntop of each source code file will tell you how to run each example.
The deno-puppeteer library\n-- created by Deno team member Luca Casonato -- is a Deno-compatible port of the\npuppeteer Node (npm) library. The library has a number of\nuses including generating app screenshots and automating form submissions. We\nare using it here to do end-to-end (e2e) testing of a Deno webapp. The code for\nthis blog post can be found\nhere.
Although puppeteer and deno-puppeteer can be used to e2e test any webapp, we are\ngoing to test the default Fresh app created with this\ncommand-line (assuming Deno has been installed):
\ndeno run -A -r https://fresh.deno.dev using_deno-puppeteerThe new project will be found in the using_deno-puppeteer folder. Moving into\nthat directory, the app can be started in that folder:
deno task startThe resulting page at http://localhost:8000 looks like this:\n
A puppeteer.test.ts file is created to hold the tests. Inside that file, the\ndeno-puppeteer library needs to be imported:
import puppeteer, {\n Browser,\n Page,\n} from \"https://deno.land/x/puppeteer@14.1.1/mod.ts\";The Browser and Page classes are used in type annotations, while puppeteer\ndoes the library's work.
We are going to use the bdd library in the deno_std testing module to run our\npuppeteer e2e tests. That library includes the familiar functions describe,\nbeforeAll, afterAll, beforeEach, afterEach and it imported like this:
import {\n afterAll,\n beforeAll,\n describe,\n it,\n} from \"https://deno.land/std@0.151.0/testing/bdd.ts\";We will also need assert functions found in the deno_std testing module to\nverify test results:
\nimport {\n assert,\n assertEquals,\n fail,\n} from \"https://deno.land/std@0.151.0/testing/asserts.ts\";Finally, we need to add the readlines function from the standard io library\nto capture subprocess stdout messages in a helper function (see below).
import { readLines } from \"https://deno.land/std@0.151.0/io/mod.ts\";Behavior-driven development test libraries (like the popular\nJest lib) include a describe function to wrap a test\nsuite and it for test functions. Also included are beforeAll and afterAll\nfunctions used to initialize and cleanup test resources. These functions run\nbefore and after all tests are run. There are also beforeEach and afterEach\nfunctions to allow code to be run before and after each test runs (not used\nhere).
Our puppeteer tests have app server (server), Browser and Page objects\nthat need to be declared at the top of the describe block since they are used\nin the `before' and 'after' functions.
describe(\"e2e tests using puppeteer: \", () => {\n let server: { close: () => void };\n let browser: Browser;\n let page: Page;\n\n beforeAll(async () => {\n server = await startAppServer();\n browser = await startBrowser();\n page = await browser.newPage();\n await page.setViewport({ width: 400, height: 200 });\n });\n\n afterAll(async () => {\n await page?.close();\n await browser?.close();\n await server?.close();\n });\n\n // test functions next. . .\n});The app server, browser and page objects are used in all tests, so they are\ninitialized in the beforeAll function and closed in the afterAll function.\nThe close calls prevents the occurrence of 'leaking resources' errors. Make\nsure that the page object is always closed before the browser object.
Note that the server, browser and page variables need type annotations to\navoid TypeScript 'implicit any' errors.
The startAppServer and startBrowser functions abstract the mechanics of\nstarting the Fresh app server that serves the webapp and the puppeteer browser\nwhich we will run in headless mode to allow the tests to run in a CI/CD\nenvironment.
/**\n * Run the Fresh server locally.\n *\n * @returns {{close: () => void}}: A handle to the server allowing closing of the server sub-process and\n * stdout/stderr within that.\n */\nexport async function startAppServer(): Promise<{ close: () => void }> {\n const serverProcess = Deno.run({\n // Fresh command line without the wait flag\n cmd: [Deno.execPath(), \"run\", \"-A\", \"dev.ts\"],\n cwd: Deno.cwd(),\n stdout: \"piped\",\n stderr: \"piped\",\n });\n console.log(\"Waiting for server to start...\");\n // Display some stdout messages.\n for await (const line of readLines(serverProcess.stdout)) {\n if (line.includes(\"Listening on http\")) {\n console.log(line);\n break;\n }\n }\n return {\n async close() {\n await serverProcess.stdout.close();\n await serverProcess.stderr.close();\n await serverProcess.close();\n },\n };\n}\n/**\n * Start the puppeteer browser in headless mode\n *\n * @returns {Promise<Browser>}: Resolves to a puppeteer Browser instance\n */\nexport async function startBrowser(): Promise<Browser> {\n const browser: Browser = await puppeteer.launch({\n headless: true,\n args: [\"--no-sandbox\"],\n });\n return browser;\n}Individual tests are found in it functions:
it({\n name: \"should display welcome message\",\n fn: async () => {\n await page.goto(\"http://localhost:8000/\", {\n waitUntil: \"networkidle2\",\n });\n const selection = await page.waitForSelector(\"body > div > p\");\n if (selection) {\n const text = await page?.evaluate(\n (element: HTMLElement) => element.textContent,\n selection,\n );\n assert(text?.startsWith(\"Welcome\"));\n } else {\n fail(`ERROR: Selector not found`);\n }\n },\n});Once the page.goto function runs and navigates to the page to be tested. All\ntests in this file work on the same page. The page.waitForSelector is called\nwith a CSS selector pointing to the DOM node on the page to be verified. In this\ncase, we are verifying that a message that starts with 'Welcome' exists at that\nspot. We use the page.evaluate to obtain the text content (i.e. the message)\nfrom the HTMLElement.
The function of the counter component is tested in the next two test functions.\nWe want to know that the increment (+1) and decrement (-1) buttons work\nproperly.
\nit({\n name: \"should decrement counter\",\n fn: async () => {\n await page.goto(\"http://localhost:8000/\", {\n waitUntil: \"networkidle2\",\n });\n // TODO: Get counter text for later decrement comparison\n // click -1 button\n await page.click(\"body > div > div > button:nth-child(2)\");\n // check to see if counter has decremented\n const selection = await page.waitForSelector(\"body > div > div > p\");\n if (selection) {\n const text = await page.evaluate(\n (element: HTMLElement) => element.textContent,\n selection,\n );\n // counter should be 2 now\n assertEquals(text, \"2\");\n } else {\n fail(`ERROR: Selector not found`);\n }\n },\n});\n\nit({\n name: \"should increment counter\",\n fn: async () => {\n await page.goto(\"http://localhost:8000/\", {\n waitUntil: \"networkidle2\",\n });\n // TODO: Get counter text for later increment comparison\n // click +1 button\n await page.click(\"body > div > div > button:nth-child(3)\");\n // check to see if counter has decremented\n const selection = await page.waitForSelector(\"body > div > div > p\");\n if (selection) {\n const text = await page.evaluate(\n (element: HTMLElement) => element.textContent,\n selection,\n );\n // counter should be 4 now\n assertEquals(text, \"4\");\n } else {\n fail(`ERROR: Selector not found`);\n }\n },\n});The page.click function is used to click a button found at the DOM node\ndefined by the CSS selector. Once the button is clicked, the DOM node containing\nthe counter's value is found and verified to have been incremented or\ndecremented (note that the Fresh app sets the counter's start value to 3).
The command line to run all tests (deno test --no-check-A) has been\nencapsulated in the deno.json file as task 'test'. You run that with\ndeno task test. When that is done, the following output should appear:
$> deno task test\nWarning deno task is unstable and may drastically change in the future\nTask test deno test --no-check -A\nrunning 1 test from ./puppeteer.test.ts\nPuppeteer e2e testing... ...\n------- output -------\nWaiting for server to start...\nListening on http://localhost:8000/\n----- output end -----\n should display welcome message ... ok (1s)\n should decrement counter ... ok (1s)\n should increment counter ... ok (1s)\nPuppeteer e2e testing... ... ok (4s)\n\nok | 1 passed (3 steps) | 0 failed (5s)There are a number of functions found in the\nPuppeteer API that I have not covered here. Here are\nfew of the highlights:
\nPage.select to target a drop-down or select element.Page.type to type text into an input box.Page.waitForFunction waits for a function to finish evaluating.Page.screenshot to take a screenshot of the current page.Page.pdf to create a pdf of the current page.As stated previously, complete source code for the example in this article is\navailable\nhere.\nPlease note that the current versions of the libraries used in this example will\nchange with time.
\nWhile I used Fresh for this work, I learned how to use deno-puppeteer when I\ncreated e2e tests for the Ultra full-stack Deno\nframework. I want to thank Omar Mashaal and James Edmonds for their assistance\nin this effort.
\nI'd also like to thank Kyle June for reviewing previous versions of this post.
\nThe deno-puppeteer library can now be combined with Deno's build-in testing\nmodules to allow the full\ntesting pyramid\nto be done in a Deno-native way.
\nWelcome to my blog! I'll be blogging about the JavaScript runtime\nDeno. I have been closely following Deno since it's 1.0\nrelease, but I got really excited when the framework\nFresh was recently released to enable full-stack Deno\nsupported by the Deno core team. Rather than just reporting on Deno news, this\nblog will focus on articles that demonstrate how to use Deno technologies and\nESM third-party libraries.
\nThis blog is built using Fresh. Fresh uses Preact under the covers and follows\nrouting conventions popularized by NextJS. Fresh does not deploy JavaScript by\ndefault but allows for JS interactivity if needed (it was not needed at this\ntime). Twind, a runtime compiler for\nTailwind, was used to style the site with help from\na utility provided by the Fresh devs (util/twind.ts). I'm sure you'll see a\nlot more about Fresh in future blog posts.
At this point the blog is a simple app that just iterates though files written\nin Markdown stored in a posts folder. I'm using the\ngfm library to render the Markdown posts. I intend to\ngo into more details on how this is done in a future article.
Deno Deploy is used to deploy this blog. Deno\nDeploy's\ngithub integration\nmakes easy work of deploying a github repo to Deploy's edge platform.
\nI'm hoping to evolve the blog with new features and improved code quality as\ntime goes on. Source code can be found in this repo:\nhttps://github.com/cdoremus/fresh-blog.
\nPlease reach out to me on Twitter at @cdoremus\nto offer suggestions and ideas for this blog.
\n", "url": "https://deno-blog.com/How_I_made_this_blog.2022-08-07", "title": "How I made this blog", "summary": "How I made this blog", "date_modified": "2022-08-07T00:00:00.000Z", "author": { "name": "Craig Doremus" } } ] }