feat: box.readonly (#17)

Co-authored-by: Hunter Johnston <[email protected]>
Co-authored-by: Hunter Johnston <[email protected]>

.changeset/smart-weeks-sort.md

@@ -0,0 +1,5 @@
+---
+"runed": minor
+---
+
+Add `box.readonly` utility

.prettierrc

@@ -3,6 +3,7 @@
   "tabWidth": 4,
   "singleQuote": false,
   "trailingComma": "es5",
+  "semi": true,
   "printWidth": 100,
   "plugins": ["prettier-plugin-svelte", "prettier-plugin-tailwindcss"],
   "overrides": [
@@ -11,7 +12,20 @@
       "options": {
         "parser": "svelte"
       }
-    }
+    },
+	{
+		"files": "*.md",
+		"options": {
+			"parser": "markdown",
+			"printWidth": 100,
+			"proseWrap": "always",
+			"tabWidth": 2,
+			"useTabs": true,
+			"semi": true,
+			"trailingComma": "none",
+			"bracketSameLine": true
+		}
+	}
   ],
   "tailwindConfig": "./sites/docs/tailwind.config.js",
   "tailwindFunctions": ["clsx", "cn", "tv"]

.vscode/settings.json

@@ -1,12 +1,13 @@
 {
 	// Enable the ESlint flat config support
-	"eslint.experimental.useFlatConfig": true,
+	"eslint.useFlatConfig": true,
 	// Auto fix
 	"editor.codeActionsOnSave": {
 		"source.fixAll.eslint": "explicit",
 		"source.organizeImports": "never"
 	},
 	"editor.formatOnSave": true,
+	"editor.defaultFormatter": "esbenp.prettier-vscode",
 	// Enable eslint for all supported languages
 	"eslint.validate": [
 		"javascript",
@@ -16,7 +17,6 @@
 		"vue",
 		"html",
 		"svelte",
-		"markdown",
 		"json",
 		"jsonc",
 		"yaml",

README.md

@@ -8,7 +8,8 @@
 
 <!-- /automd -->
 
-Runed provides utilities to power your applications using the magic of [Svelte Runes](https://svelte.dev/blog/runes).
+Runed provides utilities to power your applications using the magic of
+[Svelte Runes](https://svelte.dev/blog/runes).
 
 ## Features
 
@@ -30,11 +31,10 @@ This project is supported by the following beautiful people/organizations:
 
 <!-- automd:contributors license=MIT author="huntabyte" -->
 
-Published under the [MIT](https://github.com/svecosystem/runed/blob/main/LICENSE) license.
-Made by [@TGlide](https://github.com/tglide), [@huntabyte](https://github.com/huntabyte) and [community](https://github.com/svecosystem/runed/graphs/contributors) 💛
-<br><br>
+Published under the [MIT](https://github.com/svecosystem/runed/blob/main/LICENSE) license. Made by
+[@TGlide](https://github.com/tglide), [@huntabyte](https://github.com/huntabyte) and
+[community](https://github.com/svecosystem/runed/graphs/contributors) 💛 <br><br>
 <a href="https://github.com/svecosystem/runed/graphs/contributors">
-<img src="https://contrib.rocks/image?repo=svecosystem/runed" />
-</a>
+<img src="https://contrib.rocks/image?repo=svecosystem/runed" /> </a>
 
 <!-- /automd -->

eslint.config.js

@@ -7,7 +7,6 @@ const CUSTOM_IGNORES = [
 	"**/node_modules/**",
 	"**/.svelte-kit/**",
 	".svelte-kit/**/*",
-	"*.md",
 ];
 
 export default config({

packages/runed/README.md

@@ -8,7 +8,8 @@
 
 <!-- /automd -->
 
-Runed provides utilities to power your applications using the magic of [Svelte Runes](https://svelte.dev/blog/runes).
+Runed provides utilities to power your applications using the magic of
+[Svelte Runes](https://svelte.dev/blog/runes).
 
 ## Features
 
@@ -22,11 +23,10 @@ Runed will be published to NPM once Svelte 5 is released.
 
 <!-- automd:contributors license=MIT author="huntabyte" -->
 
-Published under the [MIT](https://github.com/svecosystem/runed/blob/main/LICENSE) license.
-Made by [@tglide](https://github.com/tglide), [@huntabyte](https://github.com/huntabyte) and [community](https://github.com/svecosystem/runed/graphs/contributors) 💛
-<br><br>
+Published under the [MIT](https://github.com/svecosystem/runed/blob/main/LICENSE) license. Made by
+[@tglide](https://github.com/tglide), [@huntabyte](https://github.com/huntabyte) and
+[community](https://github.com/svecosystem/runed/graphs/contributors) 💛 <br><br>
 <a href="https://github.com/svecosystem/runed/graphs/contributors">
-<img src="https://contrib.rocks/image?repo=svecosystem/runed" />
-</a>
+<img src="https://contrib.rocks/image?repo=svecosystem/runed" /> </a>
 
 <!-- /automd -->

packages/runed/src/lib/functions/box/box.svelte.ts

@@ -185,8 +185,25 @@ function boxFlatten<R extends Record<string, unknown>>(boxes: R): BoxFlatten<R>
 	}, {} as BoxFlatten<R>);
 }
 
+/**
+ * Function that converts a box to a readonly box.
+ *
+ * @example
+ * const count = box(0) // WritableBox<number>
+ * const countReadonly = box.readonly(count) // ReadableBox<number>
+ */
+function toReadonlyBox<T>(box: ReadableBox<T>): ReadableBox<T> {
+	return {
+		[BoxSymbol]: true,
+		get value() {
+			return box.value;
+		},
+	};
+}
+
 box.from = boxFrom;
 box.with = boxWith;
 box.flatten = boxFlatten;
+box.readonly = toReadonlyBox;
 box.isBox = isBox;
 box.isWritableBox = isWritableBox;

packages/runed/src/lib/functions/box/box.test.svelte.ts

@@ -154,4 +154,37 @@ describe("box types", () => {
 			expectTypeOf(count).toMatchTypeOf<WritableBox<number>>();
 		}
 	});
+
+	test("box.readonly should return a non-settable box", () => {
+		const count = box(0);
+		const readonlyCount = box.readonly(count);
+		expectTypeOf(readonlyCount).toMatchTypeOf<ReadableBox<number>>();
+		expectTypeOf(readonlyCount).not.toMatchTypeOf<WritableBox<number>>();
+	});
+});
+
+describe("box.readonly", () => {
+	test("box.readonly returns a non-settable box", () => {
+		const count = box(0);
+		const readonlyCount = box.readonly(count);
+
+		function setReadOnlyCount() {
+			// eslint-disable-next-line ts/no-explicit-any
+			(readonlyCount as any).value = 1;
+		}
+
+		expect(setReadOnlyCount).toThrow();
+	});
+
+	test("box.readonly returned box should update with original box", () => {
+		const count = box(0);
+		const readonlyCount = box.readonly(count);
+
+		expect(readonlyCount.value).toBe(0);
+		count.value = 1;
+		expect(readonlyCount.value).toBe(1);
+
+		count.value = 2;
+		expect(readonlyCount.value).toBe(2);
+	});
 });

sites/docs/content/functions/box.md

@@ -9,7 +9,9 @@ import { UseActiveElementDemo } from '$lib/components/demos';
 
 ## Description
 
-State in runes is based on primitives, which provides a concise syntax. However, when sending these primitives across boundaries, e.g. in function arguments, the state is not reactive, and rather, the static value gets sent.
+State in runes is based on primitives, which provides a concise syntax. However, when sending these
+primitives across boundaries, e.g. in function arguments, the state is not reactive, and rather, the
+static value gets sent.
 
 Box provides several utilities to make sending and receiving reactive values easier.
 
@@ -45,7 +47,7 @@ Allows you to use getters and setters to define a box. Useful to pass around sta
 				count.value++;
 			},
 			// We pass a box that doubles the count value
-			double: box.with(() => count.value * 2),
+			double: box.with(() => count.value * 2)
 		};
 	}
 
@@ -67,8 +69,8 @@ Allows you to use getters and setters to define a box. Useful to pass around sta
 
 ### `box.from`
 
-Creates a box from an existing box, a getter function, or a static value.
-Used in functions to receive props that are optionally reactive.
+Creates a box from an existing box, a getter function, or a static value. Used in functions to
+receive props that are optionally reactive.
 
 ```svelte
 <script lang="ts">
@@ -83,7 +85,7 @@ Used in functions to receive props that are optionally reactive.
 				count.value++;
 			},
 			// We pass a box that doubles the count value
-			double: box.with(() => count.value * 2),
+			double: box.with(() => count.value * 2)
 		};
 	}
 
@@ -123,7 +125,7 @@ const flat = box.flatten({
 	double: box.with(() => count.value * 2),
 	increment() {
 		count.value++;
-	},
+	}
 });
 
 console.log(flat.count); // 1
@@ -132,6 +134,20 @@ flat.increment();
 console.log(flat.count); // 2
 ```
 
+### `box.readonly`
+
+Creates a readonly box from a writable box that remains in sync with the original box.
+
+```ts
+const count = box(1);
+const readonlyCount = box.readonly(count);
+console.log(readonlyCount.value); // 1
+count.value++;
+console.log(readonlyCount.value); // 2
+
+readonlyCount.value = 3; // Error: Cannot assign to read only property 'value' of object
+```
+
 ### `box.isBox`
 
 Checks if a value is a `Box`.

sites/docs/content/index.md

@@ -6,15 +6,18 @@ description: What this project is all about.
 <script>
 </script>
 
-Runed provides utilities to power your applications using the magic of [Svelte Runes](https://svelte.dev/blog/runes).
+Runed provides utilities to power your applications using the magic of
+[Svelte Runes](https://svelte.dev/blog/runes).
 
 Here are some tools that are provided:
 
--   Debouncing utilities synced with state
--   Element size tracking
--   RequestAnimationFrame helpers
--   etc.
+- Debouncing utilities synced with state
+- Element size tracking
+- RequestAnimationFrame helpers
+- etc.
 
 ## Next Steps
 
-Start using Runed in your Svelte app by following the [Getting Started](/docs/getting-started) guide. If you have any questions or need help, feel free to ask in the [Discord](https://discord.gg/hbAGu6akVy)!
+Start using Runed in your Svelte app by following the [Getting Started](/docs/getting-started)
+guide. If you have any questions or need help, feel free to ask in the
+[Discord](https://discord.gg/hbAGu6akVy)!