1 files changed, 133 insertions, 0 deletions
diff --git a/js/baba-yaga/docs/02_data-structures.md b/js/baba-yaga/docs/02_data-structures.md
new file mode 100644
index 0000000..aa41ed9
--- /dev/null
+++ b/js/baba-yaga/docs/02_data-structures.md
@@ -0,0 +1,133 @@
+# Data Structures
+
+Two immutable data structures are built-in, lists and tables.
+
+## Lists
+```baba
+nums : [1, 2, 3];
+first  : nums.0;      // 1
+second : nums.1;      // 2
+
+// Common operations (immutable)
+plus4 : append nums 4;        // [1, 2, 3, 4]
+head0 : prepend 0 nums;       // [0, 1, 2, 3]
+joined: concat [1, 2] [3, 4]; // [1, 2, 3, 4]
+```
+
+## Tables
+```baba
+user : { name: "Ralph", age: 73 };
+name : user.name; // "Ralph"
+
+// Functional usage
+calculator : {
+  add: x y -> x + y,
+  mul: x y -> x * y
+};
+res : calculator.add 10 5; // 15
+```
+
+## Utilities
+
+### Core Utilities
+```baba
+length : Built-in; works on lists and strings
+shape  : Built-in; returns a metadata table for lists, strings, tables, scalars
+```
+
+### Array Programming Operations
+
+Baba Yaga provides powerful array programming operations inspired by APL, K, and Q:
+
+#### Indexing and Selection
+```baba
+data : [10, 20, 30, 40, 50];
+
+// Select elements at specific indices
+selected : at [0, 2, 4] data;        // [10, 30, 50]
+
+// Find indices where predicate is true
+evenIndices : where (x -> x % 2 = 0) data;  // [0, 1, 2, 3, 4]
+
+// Take first n elements
+firstThree : take 3 data;            // [10, 20, 30]
+
+// Drop first n elements  
+lastTwo : drop 3 data;               // [40, 50]
+```
+
+#### Cumulative Operations
+```baba
+numbers : [1, 2, 3, 4, 5];
+
+// General scan operation
+addFunc : acc x -> acc + x;
+scanned : scan addFunc 0 numbers;    // [0, 1, 3, 6, 10, 15]
+
+// Cumulative sum and product utilities
+cumSum : cumsum numbers;             // [0, 1, 3, 6, 10, 15]
+cumProd : cumprod numbers;           // [1, 1, 2, 6, 24, 120]
+```
+
+#### Broadcasting and Element-wise Operations
+```baba
+values : [1, 2, 3, 4];
+
+// Apply scalar operation to each element
+addTen : broadcast (x y -> x + y) 10 values;  // [11, 12, 13, 14]
+
+// Element-wise operations on two arrays
+array1 : [1, 2, 3];
+array2 : [4, 5, 6];
+multiplied : zipWith (x y -> x * y) array1 array2;  // [4, 10, 18]
+
+// Reshape flat array into matrix
+flatData : [1, 2, 3, 4, 5, 6];
+matrix : reshape [2, 3] flatData;    // 2x3 matrix
+```
+
+#### Monadic Operations
+```baba
+// flatMap for flattening mapped results
+duplicator : x -> [x, x];
+original : [1, 2, 3];
+flattened : flatMap duplicator original;  // [1, 1, 2, 2, 3, 3]
+```
+
+### Traditional Data Processing Utilities
+```baba
+// Array manipulation
+numbers : [1, 2, 3, 4, 5, 6];
+grouped : chunk numbers 2;        // [[1, 2], [3, 4], [5, 6]]
+sequence : range 1 10;            // [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
+duplicated : repeat 4 "item";     // ["item", "item", "item", "item"]
+
+// Sorting and grouping
+people : [{name: "Alice", age: 30}, {name: "Bob", age: 25}];
+sorted : sort.by people (p -> p.age);     // Sorted by age
+grouped : group.by people (p -> p.age > 27); // Group by age criteria
+
+// Data validation
+valid : validate.notEmpty numbers;        // true
+inRange : validate.range 1 10 5;         // true
+correctType : validate.type "List" numbers; // true
+
+// Text processing
+text : "hello world example";
+words : text.words text;                 // ["hello", "world", "example"]
+padded : text.padLeft 15 "centered";     // "     centered"
+```
+
+## Shape
+`shape` returns a metadata table describing the argument. It is similar in spirit to APL's shape (⍴) but returns a table with fields.
+
+```baba
+lst : [10, 20, 30];
+sh  : shape lst;   // { kind: "List", rank: 1, shape: [3], size: 3, isEmpty: false }
+
+str : "abc";
+shape str;         // { kind: "String", rank: 1, shape: [3], size: 3, isEmpty: false }
+
+tbl : { a: 1, b: 2 };
+shape tbl;         // { kind: "Table", rank: 1, shape: [2], size: 2, keys: ["a", "b"], isEmpty: false }
+```