CoLists

CoLists are ordered collections that work like JavaScript arrays. They provide indexed access, iteration methods, and length properties, making them perfect for managing sequences of items.

Creating CoLists

CoLists are defined by specifying the type of items they contain:

class ListOfResources extends CoList.Of(co.string) {}

class ListOfTasks extends CoList.Of(co.ref(Task)) {}

To create a CoList:

// Create an empty list
const resources = ListOfResources.create([]);

// Create a list with initial items
const tasks = ListOfTasks.create([
  Task.create({ title: "Prepare soil beds", status: "in-progress" }),
  Task.create({ title: "Order compost", status: "todo" })
]);

Like other CoValues, you can specify ownership when creating CoLists.

Reading from CoLists

CoLists support standard array access patterns:

// Access by index
const firstTask = tasks[0];
console.log(firstTask.title);  // "Prepare soil beds"

// Get list length
console.log(tasks.length);     // 2

// Iteration
tasks.forEach(task => {
  console.log(task.title);
  // "Prepare soil beds"
  // "Order compost"
});

// Array methods
const todoTasks = tasks.filter(task => task.status === "todo");
console.log(todoTasks.length); // 1

Updating CoLists

Update CoLists just like you would JavaScript arrays:

// Add items
resources.push("Tomatoes");       // Add to end
resources.unshift("Lettuce");     // Add to beginning
tasks.push(Task.create({          // Add complex items
  title: "Install irrigation", 
  status: "todo"
}));

// Replace items
resources[0] = "Cucumber";           // Replace by index

// Modify nested items
tasks[0].status = "complete";        // Update properties of references

Deleting Items

Remove specific items by index with splice, or remove the first or last item with pop or shift:

// Remove 2 items starting at index 1
resources.splice(1, 2);              
console.log(resources);              // ["Cucumber", "Peppers"]

// Remove a single item at index 0
resources.splice(0, 1);
console.log(resources);              // ["Peppers"]

// Remove items
const lastItem = resources.pop();    // Remove and return last item
resources.shift();                   // Remove first item

Array Methods

CoLists support the standard JavaScript array methods you already know:

// Add multiple items at once
resources.push("Tomatoes", "Basil", "Peppers");

// Find items
const basil = resources.find(r => r === "Basil");

// Filter (returns regular array, not a CoList)
const tItems = resources.filter(r => r.startsWith("T"));
console.log(tItems); // ["Tomatoes"]

// Sort (modifies the CoList in-place)
resources.sort();
console.log(resources); // ["Basil", "Peppers", "Tomatoes"]

Type Safety

CoLists maintain type safety for their items:

// TypeScript catches type errors
resources.push("Carrots");        // ✓ Valid string
resources.push(42);               // ✗ Type error: expected string

// For lists of references
tasks.forEach(task => {
  console.log(task.title);        // TypeScript knows task has title
});

Best Practices

Common Patterns

List Rendering

CoLists work well with UI rendering libraries:

// React example
function TaskList({ tasks }) {
  return (
    <ul>
      {tasks.map(task => (
        <li key={task.id}>
          {task.title} - {task.status}
        </li>
      ))}
    </ul>
  );
}

Managing Relations

CoLists can be used to create one-to-many relationships:

class Project extends CoMap {
  name = co.string;
  tasks = co.ref(ListOfTasks);
}

// ...

const task = Task.create({ 
  title: "Plant seedlings",
  status: "todo",
  project: project, // Add a reference to the project
});

// Add a task to a garden project
project.tasks.push(task);

// Access the project from the task
console.log(task.project); // { name: "Garden Project", tasks: [task] }

CoLists

#Creating CoLists

#Reading from CoLists

#Updating CoLists

#Deleting Items

#Array Methods

#Type Safety

#Best Practices

#Common Patterns

#List Rendering

#Managing Relations