Programming With Needles

In my last post, I discussed the needle data structure, as formulated by Edward S. Lowry. In that post, I gave a quick conceptual overview, but didn't show any examples of what using needles might look like in practice. So let's do that now!

A simple example #

Here's an example of a simple JavaScript program that uses a needle-based approach to represent people and blog posts:

import { type, entity, literal } from "./needles.js";

// Schema:
// Person:
// - has_one Name: string
// - has_one Age: number
// - has_many Post

// Post:
// - has_one Title: string
// - has_one Content: string

// Declare types

const Person = type();
const Name = type();
const Age = type();
const Post = type();
const Title = type();
const Content = type();

// Create entities

const alice = entity(Person);

alice.set(Name, literal("Alice"));
alice.set(Age, literal(30));

const bob = entity(Person);

bob.set(Name, literal("Bob"));
bob.set(Age, literal(20));

const post = entity(Post);
post.set(Title, literal("My Post"));
post.set(Content, literal("This is my first post!"));

alice.append(Post, post);

const post2 = entity(Post);
post2.set(Title, literal("My Post 2"));
post2.set(Content, literal("This is my second post!"));

alice.append(Post, post2);

// Value access

console.log(alice.last(Post).get(Content).to); // -> "This is my second post"

True to Lowry's original formulation, the type, entity, and literal functions all return needles.

Looking at this code, we can see some interesting properties:

• Types are used for attribute access. Instead of using strings to identify attributes, we use types. Whereas in JavaScript you might write alice.name, here you write alice.get(Name).
• There's no distinction between single and plural attributes. To attach a single attribute, you use .set(type, entity); to append a plural attribute, you use .append(type, entity).

The second point is particularly interesting. Theoretically this would allow for more flexibility in modeling- you could have a user with multiple names, or a post with multiple titles. However, in practice I think this would become confusing, and you would probably want to externally enforce constraints on the data.

Visualizing the structure #

What does the underlying structure of this data look like? Here's a diagram, in Lowry's notation:

It all makes sense now, right? No? Okay, let's try a different approach, by turning the "entity" and "type" needles into nodes instead of lines. This is the result:

Wait a second-- are needles just trees?

Yes! Well, sort of. It would be more accurate to say that needles can be used to construct trees. They differ from traditional trees in the exact details of how the nodes and edges are connected, and how the structure is traversed. (I may go into more detail on this in a future post.) But for the purposes of understanding the code above, you can think of them as trees.

This makes the singular-plural distinction a little more clear. Each entity attribute is a node, and those nodes may have one-to-many children.

It seems fitting that a data structure named after pine needles would be used to represent trees. Presumably, the resulting tree is an evergreen.

< Back to all posts