Blork! Shared Utilities and Types

Blork! is an internal work management service developed and used by Butterscotch Shenanigans ("Bscotch"). It is currently not available in any public way, so this package is only of use to Bscotch staff.

This package includes a client for talking to Blork servers and a bunch of shared utilities for various aspects of working with Blork data.

Requirements

• Node.js 20+ (though many features work in both Node.js and modern browsers)

Blork! Client

To automate tasks in Blork, in particular creating new tasks, you can use the Blork Client provided by this package.

import { BlorkClient, textToNewTasks } from '@bscotch/blork-shared';

const client = new BlorkClient({
	baseUrl: 'http://localhost:8080', // or wherever the Blork instance is hosted
	userId: 'your-user-id', // Unless you can rely on browser cookies
	password: 'your-password', // ^^
});

// Make sure the server is up
await client.isHealthy();

// Get *all* tasks
const allTasks = await client.getTasks();

// Create a new, empty task
const newTask = await client.createTasks('parent-task-id', { tasks: [{}] });

// Create some tasks from a nested, text-based task list
const asTasks = textToNewTasks('hello\n\tworld\n\thi');
await client.createTasks('parent-task-id', { tasks: asTasks });

// Or just send the template directly!
await client.createTasks('parent-task-id', {
	template: 'hello\n\tworld\n\thi',
});

// ... plus lots of methods to set done-state, snooze a task, delete a task, etc etc

Task Cache utilities

The Blork server and webapp both construct and maintain task caches to stay up to date and validate operations. For most other use-cases this will be overkill, but since this package includes a lot of utilities for a "Task Cache" you may want to construct one even if it doesn't need to be kept up to date.

For example:

import {
	type TaskCache,
	listTaskChildrenRecursive,
	planTaskDeletion,
	taskIsNotBlocked,
} from '@bscotch/blork-shared';

// Get *all* tasks
const allTasks = await client.getTasks();

// Turn them into a simple, Map-based cache
const cache: TaskCache = new Map();
allTasks.forEach((task) => cache.set(task.taskId, task));

// Use that cache for all kinds of operations
const children = listTaskChildrenRecursive(cache, 'some-task-id');
// See if a deletion is possible, and what all changes will happen
// as a consequence (the Blork server performs this process, so you
// you don't need to do it before attempting to delete a task)
const deletionPlan = planTaskDeletion(cache, 'some-task-id');
if (taskIsNotBlocked(cache, 'some-task-id')) {
	// Then this task is not blocked by anything
}

You can also use the Blork Query Language to search through your task cache:

import { searchTasks } from '@bscotch/blork-shared';

const users = await client.listAllUsers();

const { parsedQuery, matches } = searchTasks(
	'hello world > is:starred > @me title:some stuff',
	taskCache,
	{
		users,
		currentUserId: 'my-user-id',
	},
);