starlight-dataset 1.0.0

package/README.md

@@ -0,0 +1,160 @@
+#  starlight-dataset
+
+A lightweight dataset utility library for the **Starlight Machine Learning ecosystem**.
+It provides a clean abstraction for handling data, batching, shuffling, and train/test splitting—designed to work seamlessly with other Starlight ML packages.
+
+---
+
+##  Features
+
+*  Dataset abstraction (`Dataset` class)
+*  Immutable operations (`map`, `filter`, `shuffle`, etc.)
+*  Deterministic shuffling
+*  Batch generation
+*  Train / test split
+*  Works with regression, classification, clustering, and pipelines
+
+---
+
+##  Installation
+
+```bash
+npm install starlight-dataset
+```
+
+Or import directly in your Starlight environment:
+
+```js
+import { Dataset, dataset } from "starlight-dataset";
+```
+
+---
+
+##  Basic Usage
+
+### Create a Dataset
+
+```js
+import { dataset } from "starlight-dataset";
+
+const ds = dataset([1, 2, 3, 4, 5]);
+```
+
+---
+
+### Map & Filter
+
+```js
+const processed = ds
+  .map(x => x * 2)
+  .filter(x => x > 5);
+
+processed.toArray();
+// [6, 8, 10]
+```
+
+---
+
+##  Shuffling
+
+```js
+const shuffled = ds.shuffle();
+```
+
+Deterministic shuffle with seed:
+
+```js
+const shuffled = ds.shuffle(0.42);
+```
+
+---
+
+##  Batching
+
+```js
+const batches = ds.batch(2);
+
+batches.toArray();
+// [ [1, 2], [3, 4], [5] ]
+```
+
+---
+
+##  Train / Test Split
+
+```js
+const { train, test } = ds.split(0.8);
+
+train.size(); // 4
+test.size();  // 1
+```
+
+Disable shuffle if needed:
+
+```js
+ds.split(0.8, false);
+```
+
+---
+
+##  Pairing Features & Labels
+
+```js
+import { fromPairs } from "starlight-dataset";
+
+const X = [[1], [2], [3]];
+const y = [2, 4, 6];
+
+const paired = fromPairs(X, y);
+
+paired.toArray();
+// [ { x: [1], y: 2 }, { x: [2], y: 4 }, { x: [3], y: 6 } ]
+```
+
+---
+
+##  Dataset API
+
+### `Dataset`
+
+| Method                   | Description             |
+| ------------------------ | ----------------------- |
+| `map(fn)`                | Transform each element  |
+| `filter(fn)`             | Filter elements         |
+| `shuffle(seed?)`         | Shuffle dataset         |
+| `batch(size)`            | Create batches          |
+| `split(ratio, shuffle?)` | Train/test split        |
+| `take(n)`                | Take first `n` elements |
+| `skip(n)`                | Skip first `n` elements |
+| `repeat(times)`          | Repeat dataset          |
+| `size()`                 | Dataset size            |
+| `toArray()`              | Convert to array        |
+
+---
+
+##  Designed for Starlight ML
+
+This package integrates naturally with:
+
+* **starlight-ml**
+* **starlight-vec**
+* **starlight-classifier**
+* **starlight-regression**
+* **starlight-pipeline**
+* **starlight-train (future)**
+
+---
+
+##  Philosophy
+
+* Simple over clever
+* Immutable over mutable
+* Readable over magical
+* Educational yet production-ready
+
+---
+
+##  License
+
+MIT © Dominex Macedon
+

package/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "starlight-dataset",
+  "version": "1.0.0",
+  "description": "Dataset utilities for batching, shuffling, and splitting data in Starlight ML",
+  "type": "module",
+  "main": "starlight-dataset.mjs",
+  "keywords": [
+    "starlight",
+    "dataset",
+    "machine-learning",
+    "batching",
+    "data-pipeline"
+  ],
+  "author": "Dominex Macedon",
+  "license": "MIT",
+  "dependencies": {},
+  "devDependencies": {}
+}

package/starlight-dataset.mjs

@@ -0,0 +1,92 @@
+export class Dataset {
+  constructor(data = []) {
+    if (!Array.isArray(data)) {
+      throw new Error("Dataset data must be an array");
+    }
+    this.data = data;
+  }
+
+  map(fn) {
+    return new Dataset(this.data.map(fn));
+  }
+
+  filter(fn) {
+    return new Dataset(this.data.filter(fn));
+  }
+
+  forEach(fn) {
+    this.data.forEach(fn);
+  }
+
+  toArray() {
+    return this.data.slice();
+  }
+
+  size() {
+    return this.data.length;
+  }
+
+ take(n = 1) {
+    return new Dataset(this.data.slice(0, n));
+  }
+
+  skip(n = 0) {
+    return new Dataset(this.data.slice(n));
+  }
+
+  repeat(times = 1) {
+    const result = [];
+    for (let i = 0; i < times; i++) {
+      result.push(...this.data);
+    }
+    return new Dataset(result);
+  }
+
+  shuffle(seed = Math.random()) {
+    const arr = this.data.slice();
+    let s = seed * 100000;
+
+    for (let i = arr.length - 1; i > 0; i--) {
+      s = (s * 9301 + 49297) % 233280;
+      const j = Math.floor((s / 233280) * (i + 1));
+      [arr[i], arr[j]] = [arr[j], arr[i]];
+    }
+
+    return new Dataset(arr);
+  }
+
+  batch(size = 1) {
+    if (size <= 0) throw new Error("Batch size must be > 0");
+
+    const batches = [];
+    for (let i = 0; i < this.data.length; i += size) {
+      batches.push(this.data.slice(i, i + size));
+    }
+
+    return new Dataset(batches);
+  }
+
+  split(ratio = 0.8, shuffle = true) {
+    const data = shuffle ? this.shuffle().data : this.data;
+    const cut = Math.floor(data.length * ratio);
+
+    return {
+      train: new Dataset(data.slice(0, cut)),
+      test: new Dataset(data.slice(cut))
+    };
+  }
+}
+
+export function dataset(data = []) {
+  return new Dataset(data);
+}
+
+export function fromPairs(X = [], y = []) {
+  if (X.length !== y.length) {
+    throw new Error("X and y must have the same length");
+  }
+
+  return new Dataset(
+    X.map((x, i) => ({ x, y: y[i] }))
+  );
+}