Merge pull request #156 from mainmatter/reference-docs

docs: start building the reference docs

Author: paoloricciuti

apps/docs/astro.config.mjs

@@ -90,9 +90,28 @@ export default defineConfig({
 				},
 				{
 					label: 'Reference',
-					autogenerate: {
-						directory: 'reference',
-					},
+					items: [
+						{
+							label: 'Default task',
+							link: '/reference/default',
+						},
+						{
+							label: 'Drop task',
+							link: '/reference/drop',
+						},
+						{
+							label: 'Enqueue task',
+							link: '/reference/enqueue',
+						},
+						{
+							label: 'KeepLatest task',
+							link: '/reference/keep-latest',
+						},
+						{
+							label: 'Restart task',
+							link: '/reference/restart',
+						},
+					],
 				},
 			],
 		}),

apps/docs/src/content/docs/reference/default.mdx

@@ -0,0 +1,239 @@
+---
+title: Default task
+description: the task function
+---
+
+import { LinkCard, Tabs, TabItem, Aside } from '@astrojs/starlight/components';
+
+This is the way to create a default task.
+
+There's no concurrency management in this task and every `perform` will be executed immediately.
+
+## Usage
+
+To specify a default task, you can either use the dot notation or the options notation.
+
+<Aside type="note">
+	We call this tab "Dot notation" because you can define a default task with `task.default`. But it's
+	much easier and recommended to just use `task`.
+</Aside>
+
+<Tabs syncKey="notation">
+
+<TabItem label="Dot notation">
+
+```svelte
+<script lang="ts">
+	import { task } from '@sheepdog/svelte';
+
+	const myTask = task(async () => {
+		// your code
+	});
+</script>
+```
+
+</TabItem>
+
+<TabItem label="Options notation">
+
+```svelte
+<script lang="ts">
+	import { task } from '@sheepdog/svelte';
+
+	const myTask = task(
+		async () => {
+			// your code
+		},
+		{ kind: 'default' },
+	);
+</script>
+```
+
+</TabItem>
+
+</Tabs>
+
+### The task store
+
+The return value of the task function will be a svelte store where you can access state from all the
+instances running and eventually cancel them with `cancelAll`.
+
+<LinkCard
+	href="/getting-started/usage/#task-structure"
+	title="Task structure"
+	description="Take a look at the Task structure documentation in our Getting started"
+/>
+
+### Passing props
+
+While defining a task, if the function that you pass in has some arguments, those will be required
+by the `perform` function (and it will be strongly typed too).
+
+<Aside type="caution">
+	If you need to pass multiple props you should use an object because the second parameter will
+	always be the [SheepdogOptions](#).
+</Aside>
+
+<Tabs syncKey="notation">
+
+<TabItem label="Dot notation">
+
+```svelte
+<script lang="ts">
+	import { task } from '@sheepdog/svelte';
+
+	const myTask = task(async (id: string) => {
+		// your code
+	});
+</script>
+
+<button
+	on:click={() => {
+		myTask.perform('42');
+	}}>perform</button
+>
+```
+
+</TabItem>
+
+<TabItem label="Options notation">
+
+```svelte
+<script lang="ts">
+	import { task } from '@sheepdog/svelte';
+
+	const myTask = task(
+		async (id: string) => {
+			// your code
+		},
+		{ kind: 'default' },
+	);
+</script>
+
+<button
+	on:click={() => {
+		myTask.perform('42');
+	}}>perform</button
+>
+```
+
+</TabItem>
+
+</Tabs>
+
+### Getting the return value
+
+If you return something from your task you can access the return value by awaiting the `perform`
+function.
+
+<Tabs syncKey="notation">
+
+<TabItem label="Dot notation">
+
+```svelte
+<script lang="ts">
+	import { task } from '@sheepdog/svelte';
+
+	const myTask = task(async () => {
+		return 42;
+	});
+</script>
+
+<button
+	on:click={() => {
+		const number = await myTask.perform();
+		console.log(number); // 42
+	}}>perform</button
+>
+```
+
+</TabItem>
+
+<TabItem label="Options notation">
+
+```svelte
+<script lang="ts">
+	import { task } from '@sheepdog/svelte';
+
+	const myTask = task(
+		async () => {
+			return 42;
+		},
+		{ kind: 'default' },
+	);
+</script>
+
+<button
+	on:click={() => {
+		const number = await myTask.perform();
+		console.log(number); // 42
+	}}>perform</button
+>
+```
+
+</TabItem>
+
+</Tabs>
+
+### Getting the `TaskInstance`
+
+If you don't await the `perform` function, then you'll get back the
+[task instance](/reference/task-instance) that you can use either to cancel it or to get its current
+state. The `TaskInstance` is also a svelte store and you can access the current value with
+`instance.get()`.
+
+<Tabs syncKey="notation">
+
+<TabItem label="Dot notation">
+
+```svelte
+<script lang="ts">
+	import { task } from '@sheepdog/svelte';
+
+	const myTask = task(async () => {
+		// your code
+	});
+</script>
+
+<button
+	on:click={() => {
+		const lastRun = myTask.perform();
+		console.log(lastRun.get()); // { isRunning: true, hasStarted: true, ... }
+		lastRun.cancel();
+	}}>perform</button
+>
+```
+
+</TabItem>
+
+<TabItem label="Options notation">
+
+```svelte
+<script lang="ts">
+	import { task } from '@sheepdog/svelte';
+
+	const myTask = task(
+		async () => {
+			// your code
+		},
+		{ kind: 'default' },
+	);
+</script>
+
+<button
+	on:click={() => {
+		lastRun = myTask.perform();
+		console.log(lastRun.get()); // { isRunning: true, hasStarted: true, ... }
+		lastRun.cancel();
+	}}>perform</button
+>
+```
+
+</TabItem>
+
+</Tabs>
+
+<Aside type="tip">
+	Since this kind of task does not do any concurrency management there's no way to specify a `max`
+	concurrency value.
+</Aside>