From 88a2efd4a883190ef9cf0e44a37f974e61f55594 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sat, 4 Apr 2026 03:57:49 +0000
Subject: [PATCH 1/4] Initial plan


From d3ab7edcb2d4d90250531466ca0c602f06465792 Mon Sep 17 00:00:00 2001
From: "github-actions[bot]"
 <41898282+github-actions[bot]@users.noreply.github.com>
Date: Sat, 4 Apr 2026 01:43:13 +0000
Subject: [PATCH 2/4] Iteration 3: Implement Dtype system and Series

Add Dtype immutable singleton system (16 pandas dtypes with kind, itemsize,
casting rules, and inferFrom), implement Series<T> (1-D labeled array with
dtype inference, element access, arithmetic, comparison, boolean masking,
statistical aggregation, sorting, and manipulation), plus comprehensive
tests. Fix pre-existing noUncheckedIndexedAccess errors in base-index.ts.

Run: https://github.com/githubnext/tsessebe/actions/runs/23968306924

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Co-authored-by: mrjf <180956+mrjf@users.noreply.github.com>
---
 src/core/dtype.ts         | 349 +++++++++++++++++++
 src/core/index.ts         |   4 +
 src/core/series.ts        | 689 ++++++++++++++++++++++++++++++++++++++
 src/index.ts              |   4 +
 tests/core/dtype.test.ts  | 158 +++++++++
 tests/core/series.test.ts | 278 +++++++++++++++
 6 files changed, 1482 insertions(+)
 create mode 100644 src/core/dtype.ts
 create mode 100644 src/core/series.ts
 create mode 100644 tests/core/dtype.test.ts
 create mode 100644 tests/core/series.test.ts

diff --git a/src/core/dtype.ts b/src/core/dtype.ts
new file mode 100644
index 00000000..de30242a
--- /dev/null
+++ b/src/core/dtype.ts
@@ -0,0 +1,349 @@
+/**
+ * Dtype system — immutable singleton descriptors for all pandas-equivalent dtypes.
+ *
+ * Mirrors pandas' dtype hierarchy: numeric (int, uint, float), bool, string,
+ * object, datetime, timedelta, and category. Each Dtype is a flyweight (cached
+ * singleton keyed by name) so identity comparisons (`===`) work correctly.
+ */
+
+import type { DtypeName, Scalar } from "../types.ts";
+
+/** Classification of a dtype into a broad "kind". */
+export type DtypeKind =
+  | "int"
+  | "uint"
+  | "float"
+  | "bool"
+  | "string"
+  | "object"
+  | "datetime"
+  | "timedelta"
+  | "category";
+
+/** Size of a single element in bytes (0 = variable / unknown). */
+export type ItemSize = 0 | 1 | 2 | 4 | 8;
+
+const _registry = new Map<DtypeName, Dtype>();
+
+interface InferFlags {
+  allBool: boolean;
+  allInt: boolean;
+  allFloat: boolean;
+  allDate: boolean;
+  allString: boolean;
+}
+
+/**
+ * An immutable descriptor for a data type.
+ *
+ * Obtain instances via the static factory methods or the `Dtype` named
+ * constants rather than the constructor.
+ *
+ * @example
+ * ```ts
+ * const dt = Dtype.float64;
+ * dt.isNumeric; // true
+ * dt.itemsize;  // 8
+ * Dtype.from("float64") === dt; // true — singletons
+ * ```
+ */
+export class Dtype {
+  readonly name: DtypeName;
+  readonly kind: DtypeKind;
+  readonly itemsize: ItemSize;
+
+  private constructor(name: DtypeName, kind: DtypeKind, itemsize: ItemSize) {
+    this.name = name;
+    this.kind = kind;
+    this.itemsize = itemsize;
+  }
+
+  // ─── singleton factory ──────────────────────────────────────────
+
+  /** Return (or create) the singleton for `name`. */
+  static from(name: DtypeName): Dtype {
+    const cached = _registry.get(name);
+    if (cached !== undefined) {
+      return cached;
+    }
+    const dt = Dtype.build(name);
+    _registry.set(name, dt);
+    return dt;
+  }
+
+  private static build(name: DtypeName): Dtype {
+    switch (name) {
+      case "int8":
+        return new Dtype("int8", "int", 1);
+      case "int16":
+        return new Dtype("int16", "int", 2);
+      case "int32":
+        return new Dtype("int32", "int", 4);
+      case "int64":
+        return new Dtype("int64", "int", 8);
+      case "uint8":
+        return new Dtype("uint8", "uint", 1);
+      case "uint16":
+        return new Dtype("uint16", "uint", 2);
+      case "uint32":
+        return new Dtype("uint32", "uint", 4);
+      case "uint64":
+        return new Dtype("uint64", "uint", 8);
+      case "float32":
+        return new Dtype("float32", "float", 4);
+      case "float64":
+        return new Dtype("float64", "float", 8);
+      case "bool":
+        return new Dtype("bool", "bool", 1);
+      case "string":
+        return new Dtype("string", "string", 0);
+      case "object":
+        return new Dtype("object", "object", 0);
+      case "datetime":
+        return new Dtype("datetime", "datetime", 8);
+      case "timedelta":
+        return new Dtype("timedelta", "timedelta", 8);
+      case "category":
+        return new Dtype("category", "category", 0);
+    }
+  }
+
+  // ─── named singletons ───────────────────────────────────────────
+
+  static readonly int8 = Dtype.from("int8");
+  static readonly int16 = Dtype.from("int16");
+  static readonly int32 = Dtype.from("int32");
+  static readonly int64 = Dtype.from("int64");
+  static readonly uint8 = Dtype.from("uint8");
+  static readonly uint16 = Dtype.from("uint16");
+  static readonly uint32 = Dtype.from("uint32");
+  static readonly uint64 = Dtype.from("uint64");
+  static readonly float32 = Dtype.from("float32");
+  static readonly float64 = Dtype.from("float64");
+  static readonly bool = Dtype.from("bool");
+  static readonly string = Dtype.from("string");
+  static readonly object = Dtype.from("object");
+  static readonly datetime = Dtype.from("datetime");
+  static readonly timedelta = Dtype.from("timedelta");
+  static readonly category = Dtype.from("category");
+
+  // ─── type predicates ────────────────────────────────────────────
+
+  get isNumeric(): boolean {
+    return this.kind === "int" || this.kind === "uint" || this.kind === "float";
+  }
+
+  get isInteger(): boolean {
+    return this.kind === "int" || this.kind === "uint";
+  }
+
+  get isSignedInteger(): boolean {
+    return this.kind === "int";
+  }
+
+  get isUnsignedInteger(): boolean {
+    return this.kind === "uint";
+  }
+
+  get isFloat(): boolean {
+    return this.kind === "float";
+  }
+
+  get isBool(): boolean {
+    return this.kind === "bool";
+  }
+
+  get isString(): boolean {
+    return this.kind === "string";
+  }
+
+  get isDatetime(): boolean {
+    return this.kind === "datetime";
+  }
+
+  get isTimedelta(): boolean {
+    return this.kind === "timedelta";
+  }
+
+  get isCategory(): boolean {
+    return this.kind === "category";
+  }
+
+  get isObject(): boolean {
+    return this.kind === "object";
+  }
+
+  // ─── casting / promotion ────────────────────────────────────────
+
+  /**
+   * True when values of `this` dtype can be safely cast to `target`
+   * without loss of information.
+   */
+  canCastTo(target: Dtype): boolean {
+    if (this === target) {
+      return true;
+    }
+    // Numeric promotion rules (mirrors numpy safe casting).
+    const order: readonly DtypeName[] = [
+      "int8",
+      "int16",
+      "int32",
+      "int64",
+      "uint8",
+      "uint16",
+      "uint32",
+      "uint64",
+      "float32",
+      "float64",
+    ];
+    const fromIdx = order.indexOf(this.name);
+    const toIdx = order.indexOf(target.name);
+    if (fromIdx !== -1 && toIdx !== -1) {
+      // Unsigned → signed: only safe if there's enough headroom.
+      if (this.isUnsignedInteger && target.isSignedInteger) {
+        return target.itemsize > this.itemsize;
+      }
+      return toIdx >= fromIdx;
+    }
+    // bool → any numeric is safe.
+    if (this.isBool && target.isNumeric) {
+      return true;
+    }
+    // string → object is safe.
+    if (this.isString && target.isObject) {
+      return true;
+    }
+    return false;
+  }
+
+  /**
+   * Return the smallest dtype that can represent both `a` and `b` without loss.
+   * Falls back to `object` when no numeric promotion exists.
+   */
+  static commonType(a: Dtype, b: Dtype): Dtype {
+    if (a === b) {
+      return a;
+    }
+    if (a.canCastTo(b)) {
+      return b;
+    }
+    if (b.canCastTo(a)) {
+      return a;
+    }
+    // Mixed int / float → float64.
+    if (a.isNumeric && b.isNumeric) {
+      return Dtype.float64;
+    }
+    // bool + numeric → numeric.
+    if (a.isBool && b.isNumeric) {
+      return b;
+    }
+    if (b.isBool && a.isNumeric) {
+      return a;
+    }
+    // Anything else → object.
+    return Dtype.object;
+  }
+
+  // ─── inference ──────────────────────────────────────────────────
+
+  /**
+   * Infer the most specific dtype from an array of scalar values.
+   *
+   * Rules (in priority order):
+   * 1. Empty array → float64 (pandas default).
+   * 2. All booleans → bool.
+   * 3. All integers (number without fractional part, no NaN/Inf) → int64.
+   * 4. All finite/NaN numbers → float64.
+   * 5. All Date objects → datetime.
+   * 6. All strings → string.
+   * 7. Otherwise → object.
+   */
+  static inferFrom(values: readonly Scalar[]): Dtype {
+    if (values.length === 0) {
+      return Dtype.float64;
+    }
+    const flags = Dtype.scanFlags(values);
+    return Dtype.flagsToDtype(flags);
+  }
+
+  private static scanFlags(values: readonly Scalar[]): InferFlags {
+    const flags: InferFlags = {
+      allBool: true,
+      allInt: true,
+      allFloat: true,
+      allDate: true,
+      allString: true,
+    };
+    for (const v of values) {
+      if (v === null || v === undefined) {
+        continue;
+      }
+      Dtype.updateFlags(flags, v);
+    }
+    return flags;
+  }
+
+  private static updateFlags(flags: InferFlags, v: NonNullable<Scalar>): void {
+    const t = typeof v;
+    if (t !== "boolean") {
+      flags.allBool = false;
+    }
+    if (t === "boolean") {
+      flags.allString = false;
+      flags.allDate = false;
+    } else if (t === "number") {
+      flags.allString = false;
+      flags.allDate = false;
+      if (!(Number.isFinite(v as number) && Number.isInteger(v as number))) {
+        flags.allInt = false;
+      }
+    } else if (v instanceof Date) {
+      flags.allString = false;
+      flags.allInt = false;
+      flags.allFloat = false;
+      flags.allBool = false;
+    } else if (t === "string") {
+      flags.allInt = false;
+      flags.allFloat = false;
+      flags.allDate = false;
+      flags.allBool = false;
+    } else {
+      flags.allBool = false;
+      flags.allInt = false;
+      flags.allFloat = false;
+      flags.allDate = false;
+      flags.allString = false;
+    }
+  }
+
+  private static flagsToDtype(f: InferFlags): Dtype {
+    if (f.allBool) {
+      return Dtype.bool;
+    }
+    if (f.allInt) {
+      return Dtype.int64;
+    }
+    if (f.allFloat) {
+      return Dtype.float64;
+    }
+    if (f.allDate) {
+      return Dtype.datetime;
+    }
+    if (f.allString) {
+      return Dtype.string;
+    }
+    return Dtype.object;
+  }
+
+  // ─── misc ────────────────────────────────────────────────────────
+
+  toString(): string {
+    return this.name;
+  }
+
+  /** Equality: dtypes are singletons, so reference equality suffices. */
+  equals(other: Dtype): boolean {
+    return this === other;
+  }
+}
diff --git a/src/core/index.ts b/src/core/index.ts
index 16265d50..2b843122 100644
--- a/src/core/index.ts
+++ b/src/core/index.ts
@@ -1,3 +1,7 @@
 export { Index } from "./base-index.ts";
 export type { IndexOptions } from "./base-index.ts";
 export { RangeIndex } from "./range-index.ts";
+export { Dtype } from "./dtype.ts";
+export type { DtypeKind, ItemSize } from "./dtype.ts";
+export { Series } from "./series.ts";
+export type { SeriesOptions } from "./series.ts";
diff --git a/src/core/series.ts b/src/core/series.ts
new file mode 100644
index 00000000..f973b441
--- /dev/null
+++ b/src/core/series.ts
@@ -0,0 +1,689 @@
+/**
+ * Series — a one-dimensional labeled array with dtype awareness.
+ *
+ * Mirrors `pandas.Series`: an ordered sequence of values indexed by an
+ * `Index<Label>`.  Every Series carries a `Dtype` descriptor and supports
+ * element access, arithmetic, statistical aggregation, boolean masking, and
+ * missing-value handling.
+ */
+
+import type { Label, Scalar } from "../types.ts";
+import { Index } from "./base-index.ts";
+import { Dtype } from "./dtype.ts";
+import { RangeIndex } from "./range-index.ts";
+
+// ─── helpers ──────────────────────────────────────────────────────────────────
+
+/** Build a default RangeIndex of length `n`. */
+function defaultIndex(n: number): Index<Label> {
+  return new RangeIndex(n) as unknown as Index<Label>;
+}
+
+// ─── SeriesOptions ────────────────────────────────────────────────────────────
+
+/** Constructor options accepted by `Series`. */
+export interface SeriesOptions<T extends Scalar = Scalar> {
+  readonly data: readonly T[];
+  readonly index?: Index<Label> | readonly Label[];
+  readonly dtype?: Dtype;
+  readonly name?: string | null;
+}
+
+// ─── Series ───────────────────────────────────────────────────────────────────
+
+/**
+ * A one-dimensional labeled array.
+ *
+ * `Series` is the TypeScript equivalent of `pandas.Series`.
+ * Values are stored in an immutable array; labels are stored in an `Index`.
+ *
+ * @example
+ * ```ts
+ * const s = new Series({ data: [1, 2, 3], name: "x" });
+ * s.sum();   // 6
+ * s.mean();  // 2
+ * s.at(0);   // 1
+ * ```
+ */
+export class Series<T extends Scalar = Scalar> {
+  private readonly _values: readonly T[];
+  readonly index: Index<Label>;
+  readonly dtype: Dtype;
+  readonly name: string | null;
+
+  // ─── construction ─────────────────────────────────────────────────────────
+
+  constructor(options: SeriesOptions<T>) {
+    const { data, index, dtype, name } = options;
+    this._values = Object.freeze([...data]);
+    this.dtype = dtype ?? Dtype.inferFrom(data as readonly Scalar[]);
+    this.name = name ?? null;
+
+    if (index === undefined) {
+      this.index = defaultIndex(data.length);
+    } else if (index instanceof Index) {
+      if (index.size !== data.length) {
+        throw new RangeError(
+          `Index length ${index.size} does not match data length ${data.length}`,
+        );
+      }
+      this.index = index;
+    } else {
+      // readonly Label[]
+      if (index.length !== data.length) {
+        throw new RangeError(
+          `Index length ${index.length} does not match data length ${data.length}`,
+        );
+      }
+      this.index = new Index<Label>(index);
+    }
+  }
+
+  /**
+   * Create a Series from a plain object mapping label → value.
+   */
+  static fromObject<T extends Scalar>(
+    obj: Readonly<Record<string, T>>,
+    name?: string | null,
+  ): Series<T> {
+    const keys = Object.keys(obj);
+    const vals = keys.map((k) => obj[k] as T);
+    return new Series<T>({
+      data: vals,
+      index: keys,
+      ...(name !== undefined ? { name } : {}),
+    });
+  }
+
+  // ─── properties ───────────────────────────────────────────────────────────
+
+  get size(): number {
+    return this._values.length;
+  }
+
+  get length(): number {
+    return this._values.length;
+  }
+
+  get shape(): [number] {
+    return [this._values.length];
+  }
+
+  get ndim(): 1 {
+    return 1;
+  }
+
+  get empty(): boolean {
+    return this._values.length === 0;
+  }
+
+  /** Snapshot of the underlying values as a plain array. */
+  get values(): readonly T[] {
+    return this._values;
+  }
+
+  // ─── element access ───────────────────────────────────────────────────────
+
+  /**
+   * Access element by **label** (mirrors pandas `Series.at[label]`).
+   * Throws `KeyError` when the label is not found.
+   */
+  at(label: Label): T {
+    const pos = this.index.getLoc(label);
+    const i = typeof pos === "number" ? pos : (pos[0] as number);
+    return this._values[i] as T;
+  }
+
+  /**
+   * Access element by **integer position** (mirrors pandas `Series.iat[i]`).
+   */
+  iat(i: number): T {
+    const len = this._values.length;
+    const idx = i < 0 ? len + i : i;
+    if (idx < 0 || idx >= len) {
+      throw new RangeError(`Position ${i} is out of bounds for axis of size ${len}`);
+    }
+    return this._values[idx] as T;
+  }
+
+  /**
+   * Label-based selection — mirrors `Series.loc[label]` or
+   * `Series.loc[labels]` for an array of labels.
+   */
+  loc(label: Label): T;
+  loc(labels: readonly Label[]): Series<T>;
+  loc(labelOrLabels: Label | readonly Label[]): T | Series<T> {
+    if (Array.isArray(labelOrLabels)) {
+      const labels = labelOrLabels as readonly Label[];
+      const positions = labels.map((lbl) => {
+        const pos = this.index.getLoc(lbl);
+        return typeof pos === "number" ? pos : (pos[0] as number);
+      });
+      const newData = positions.map((p) => this._values[p] as T);
+      const newIndex = new Index<Label>(labels);
+      return new Series<T>({ data: newData, index: newIndex, dtype: this.dtype, name: this.name });
+    }
+    return this.at(labelOrLabels as Label);
+  }
+
+  /**
+   * Integer position-based selection — mirrors `Series.iloc[i]` or
+   * `Series.iloc[positions]`.
+   */
+  iloc(position: number): T;
+  iloc(positions: readonly number[]): Series<T>;
+  iloc(posOrPositions: number | readonly number[]): T | Series<T> {
+    if (Array.isArray(posOrPositions)) {
+      const positions = posOrPositions as readonly number[];
+      const newData = positions.map((p) => this.iat(p));
+      const newIndex = this.index.take(positions);
+      return new Series<T>({ data: newData, index: newIndex, dtype: this.dtype, name: this.name });
+    }
+    return this.iat(posOrPositions as number);
+  }
+
+  // ─── arithmetic ───────────────────────────────────────────────────────────
+
+  private _scalarOp(other: T | Series<T>, fn: (a: number, b: number) => number): Series<number> {
+    const isScalar = !(other instanceof Series);
+    if (isScalar) {
+      const b = other as number;
+      const newData = this._values.map((v) => {
+        const a = v as unknown as number;
+        return fn(a, b);
+      });
+      return new Series<number>({
+        data: newData,
+        index: this.index,
+        dtype: Dtype.float64,
+        name: this.name,
+      });
+    }
+    const o = other as Series<T>;
+    if (o.size !== this.size) {
+      throw new RangeError(
+        `Cannot operate on Series of different sizes: ${this.size} vs ${o.size}`,
+      );
+    }
+    const newData = this._values.map((v, i) => {
+      const a = v as unknown as number;
+      const b = o._values[i] as unknown as number;
+      return fn(a, b);
+    });
+    return new Series<number>({
+      data: newData,
+      index: this.index,
+      dtype: Dtype.float64,
+      name: this.name,
+    });
+  }
+
+  /** Element-wise addition. */
+  add(other: T | Series<T>): Series<number> {
+    return this._scalarOp(other, (a, b) => a + b);
+  }
+
+  /** Element-wise subtraction. */
+  sub(other: T | Series<T>): Series<number> {
+    return this._scalarOp(other, (a, b) => a - b);
+  }
+
+  /** Element-wise multiplication. */
+  mul(other: T | Series<T>): Series<number> {
+    return this._scalarOp(other, (a, b) => a * b);
+  }
+
+  /** Element-wise division (true division, returns float). */
+  div(other: T | Series<T>): Series<number> {
+    return this._scalarOp(other, (a, b) => a / b);
+  }
+
+  /** Element-wise floor division. */
+  floordiv(other: T | Series<T>): Series<number> {
+    return this._scalarOp(other, (a, b) => Math.floor(a / b));
+  }
+
+  /** Element-wise modulo. */
+  mod(other: T | Series<T>): Series<number> {
+    return this._scalarOp(other, (a, b) => a % b);
+  }
+
+  /** Element-wise exponentiation. */
+  pow(other: T | Series<T>): Series<number> {
+    return this._scalarOp(other, (a, b) => a ** b);
+  }
+
+  // ─── comparison ───────────────────────────────────────────────────────────
+
+  private _cmpOp(other: T | Series<T>, fn: (a: T, b: T) => boolean): Series<boolean> {
+    const isScalar = !(other instanceof Series);
+    if (isScalar) {
+      const b = other as T;
+      const newData = this._values.map((a) => fn(a, b));
+      return new Series<boolean>({
+        data: newData,
+        index: this.index,
+        dtype: Dtype.bool,
+        name: this.name,
+      });
+    }
+    const o = other as Series<T>;
+    if (o.size !== this.size) {
+      throw new RangeError(`Cannot compare Series of different sizes: ${this.size} vs ${o.size}`);
+    }
+    const newData = this._values.map((a, i) => fn(a, o._values[i] as T));
+    return new Series<boolean>({
+      data: newData,
+      index: this.index,
+      dtype: Dtype.bool,
+      name: this.name,
+    });
+  }
+
+  eq(other: T | Series<T>): Series<boolean> {
+    return this._cmpOp(other, (a, b) => a === b);
+  }
+
+  ne(other: T | Series<T>): Series<boolean> {
+    return this._cmpOp(other, (a, b) => a !== b);
+  }
+
+  lt(other: T | Series<T>): Series<boolean> {
+    return this._cmpOp(other, (a, b) => {
+      if (a === null || b === null) {
+        return false;
+      }
+      return (a as number | string | boolean) < (b as number | string | boolean);
+    });
+  }
+
+  le(other: T | Series<T>): Series<boolean> {
+    return this._cmpOp(other, (a, b) => {
+      if (a === null || b === null) {
+        return false;
+      }
+      return (a as number | string | boolean) <= (b as number | string | boolean);
+    });
+  }
+
+  gt(other: T | Series<T>): Series<boolean> {
+    return this._cmpOp(other, (a, b) => {
+      if (a === null || b === null) {
+        return false;
+      }
+      return (a as number | string | boolean) > (b as number | string | boolean);
+    });
+  }
+
+  ge(other: T | Series<T>): Series<boolean> {
+    return this._cmpOp(other, (a, b) => {
+      if (a === null || b === null) {
+        return false;
+      }
+      return (a as number | string | boolean) >= (b as number | string | boolean);
+    });
+  }
+
+  // ─── boolean masking ─────────────────────────────────────────────────────
+
+  /**
+   * Filter by a boolean mask Series or array.
+   * Returns a new Series containing only elements where the mask is `true`.
+   */
+  filter(mask: Series<boolean> | readonly boolean[]): Series<T> {
+    const bools = mask instanceof Series ? mask.values : mask;
+    if (bools.length !== this._values.length) {
+      throw new RangeError(
+        `Mask length ${bools.length} does not match Series length ${this._values.length}`,
+      );
+    }
+    const newData: T[] = [];
+    const newLabels: Label[] = [];
+    for (let i = 0; i < this._values.length; i++) {
+      if (bools[i]) {
+        newData.push(this._values[i] as T);
+        newLabels.push(this.index.at(i));
+      }
+    }
+    return new Series<T>({
+      data: newData,
+      index: new Index<Label>(newLabels),
+      dtype: this.dtype,
+      name: this.name,
+    });
+  }
+
+  // ─── missing value handling ───────────────────────────────────────────────
+
+  /** Boolean mask: `true` where the value is `null` or `undefined` or `NaN`. */
+  isna(): Series<boolean> {
+    return new Series<boolean>({
+      data: this._values.map(
+        (v) => v === null || v === undefined || (typeof v === "number" && Number.isNaN(v)),
+      ),
+      index: this.index,
+      dtype: Dtype.bool,
+      name: this.name,
+    });
+  }
+
+  /** Boolean mask: `true` where the value is not missing. */
+  notna(): Series<boolean> {
+    const naFlags = this.isna().values;
+    return new Series<boolean>({
+      data: naFlags.map((f) => !f),
+      index: this.index,
+      dtype: Dtype.bool,
+      name: this.name,
+    });
+  }
+
+  /** Return a new Series with missing values removed. */
+  dropna(): Series<T> {
+    const mask = this.notna();
+    return this.filter(mask);
+  }
+
+  /** Return a new Series with missing values replaced by `value`. */
+  fillna(value: T): Series<T> {
+    return new Series<T>({
+      data: this._values.map((v) =>
+        v === null || v === undefined || (typeof v === "number" && Number.isNaN(v)) ? value : v,
+      ),
+      index: this.index,
+      dtype: this.dtype,
+      name: this.name,
+    });
+  }
+
+  // ─── statistical aggregation ─────────────────────────────────────────────
+
+  /** Number of non-null values. */
+  count(): number {
+    return this._values.filter(
+      (v) => v !== null && v !== undefined && !(typeof v === "number" && Number.isNaN(v)),
+    ).length;
+  }
+
+  private _numericValues(): number[] {
+    return this._values
+      .filter(
+        (v): v is NonNullable<T> =>
+          v !== null && v !== undefined && !(typeof v === "number" && Number.isNaN(v)),
+      )
+      .map((v) => v as unknown as number);
+  }
+
+  /** Sum of all non-null values. Returns `NaN` for an empty Series. */
+  sum(): number {
+    const nums = this._numericValues();
+    if (nums.length === 0) {
+      return 0;
+    }
+    return nums.reduce((acc, v) => acc + v, 0);
+  }
+
+  /** Arithmetic mean. Returns `NaN` for an empty Series. */
+  mean(): number {
+    const nums = this._numericValues();
+    if (nums.length === 0) {
+      return Number.NaN;
+    }
+    return this.sum() / nums.length;
+  }
+
+  /** Minimum value. Returns `undefined` for an empty Series. */
+  min(): T | undefined {
+    const vals = this._values.filter(
+      (v): v is NonNullable<T> =>
+        v !== null && v !== undefined && !(typeof v === "number" && Number.isNaN(v)),
+    );
+    if (vals.length === 0) {
+      return undefined;
+    }
+    return vals.reduce((a, b) => {
+      if (a === null) {
+        return b;
+      }
+      if (b === null) {
+        return a;
+      }
+      return (a as number | string | boolean) <= (b as number | string | boolean) ? a : b;
+    });
+  }
+
+  /** Maximum value. Returns `undefined` for an empty Series. */
+  max(): T | undefined {
+    const vals = this._values.filter(
+      (v): v is NonNullable<T> =>
+        v !== null && v !== undefined && !(typeof v === "number" && Number.isNaN(v)),
+    );
+    if (vals.length === 0) {
+      return undefined;
+    }
+    return vals.reduce((a, b) => {
+      if (a === null) {
+        return b;
+      }
+      if (b === null) {
+        return a;
+      }
+      return (a as number | string | boolean) >= (b as number | string | boolean) ? a : b;
+    });
+  }
+
+  /** Population standard deviation (ddof=1, like pandas default). */
+  std(ddof = 1): number {
+    return Math.sqrt(this.var(ddof));
+  }
+
+  /** Sample variance (ddof=1). */
+  var(ddof = 1): number {
+    const nums = this._numericValues();
+    const n = nums.length;
+    if (n < 2) {
+      return Number.NaN;
+    }
+    const mu = nums.reduce((acc, v) => acc + v, 0) / n;
+    const ss = nums.reduce((acc, v) => acc + (v - mu) ** 2, 0);
+    return ss / (n - ddof);
+  }
+
+  /** Median (middle value of sorted non-null data). */
+  median(): number {
+    const nums = this._numericValues().sort((a, b) => a - b);
+    const n = nums.length;
+    if (n === 0) {
+      return Number.NaN;
+    }
+    const mid = Math.floor(n / 2);
+    if (n % 2 === 1) {
+      return nums[mid] as number;
+    }
+    return ((nums[mid - 1] as number) + (nums[mid] as number)) / 2;
+  }
+
+  /** Number of unique non-null values. */
+  nunique(): number {
+    const nonNull = this._values.filter(
+      (v) => v !== null && v !== undefined && !(typeof v === "number" && Number.isNaN(v)),
+    );
+    return new Set(nonNull).size;
+  }
+
+  /** Return sorted unique values. */
+  unique(): T[] {
+    const seen = new Set<T>();
+    const result: T[] = [];
+    for (const v of this._values) {
+      if (!seen.has(v)) {
+        seen.add(v);
+        result.push(v);
+      }
+    }
+    return result;
+  }
+
+  /** Return value counts as a new Series (label → count), sorted by frequency. */
+  valueCounts(): Series<number> {
+    const counts = new Map<T, number>();
+    for (const v of this._values) {
+      if (v !== null && v !== undefined) {
+        counts.set(v, (counts.get(v) ?? 0) + 1);
+      }
+    }
+    const sorted = [...counts.entries()].sort((a, b) => b[1] - a[1]);
+    return new Series<number>({
+      data: sorted.map(([, count]) => count),
+      index: new Index<Label>(sorted.map(([v]) => v as Label)),
+      dtype: Dtype.int64,
+      name: "count",
+    });
+  }
+
+  // ─── sorting ─────────────────────────────────────────────────────────────
+
+  /** Return a new Series sorted by values. */
+  sortValues(ascending = true, naPosition: "first" | "last" = "last"): Series<T> {
+    const pairs = this._values.map((v, i) => ({ v, i }));
+    pairs.sort((a, b) => {
+      const aNull =
+        a.v === null || a.v === undefined || (typeof a.v === "number" && Number.isNaN(a.v));
+      const bNull =
+        b.v === null || b.v === undefined || (typeof b.v === "number" && Number.isNaN(b.v));
+      if (aNull && bNull) {
+        return 0;
+      }
+      if (aNull) {
+        return naPosition === "first" ? -1 : 1;
+      }
+      if (bNull) {
+        return naPosition === "first" ? 1 : -1;
+      }
+      const av = a.v as number | string | boolean;
+      const bv = b.v as number | string | boolean;
+      if (av === bv) {
+        return 0;
+      }
+      const cmp = av < bv ? -1 : 1;
+      return ascending ? cmp : -cmp;
+    });
+    return new Series<T>({
+      data: pairs.map(({ v }) => v),
+      index: this.index.take(pairs.map(({ i }) => i)),
+      dtype: this.dtype,
+      name: this.name,
+    });
+  }
+
+  /** Return a new Series sorted by its index labels. */
+  sortIndex(ascending = true): Series<T> {
+    const perm = this.index.argsort();
+    const orderedPerm = ascending ? [...perm] : [...perm].reverse();
+    return new Series<T>({
+      data: orderedPerm.map((p) => this._values[p] as T),
+      index: this.index.take(orderedPerm),
+      dtype: this.dtype,
+      name: this.name,
+    });
+  }
+
+  // ─── manipulation ─────────────────────────────────────────────────────────
+
+  /** Return a shallow copy with an optional new name. */
+  copy(name?: string | null): Series<T> {
+    return new Series<T>({
+      data: [...this._values],
+      index: this.index.copy(),
+      dtype: this.dtype,
+      name: name === undefined ? this.name : name,
+    });
+  }
+
+  /** Return a new Series with a different name. */
+  rename(name: string | null): Series<T> {
+    return this.copy(name);
+  }
+
+  /** Return a new Series with a new Index. */
+  setIndex(index: Index<Label> | readonly Label[]): Series<T> {
+    return new Series<T>({
+      data: [...this._values],
+      index,
+      dtype: this.dtype,
+      name: this.name,
+    });
+  }
+
+  /** Reset the index to a default RangeIndex. */
+  resetIndex(): Series<T> {
+    return new Series<T>({
+      data: [...this._values],
+      index: defaultIndex(this._values.length),
+      dtype: this.dtype,
+      name: this.name,
+    });
+  }
+
+  /**
+   * Apply a function to each value, returning a new Series.
+   */
+  map<U extends Scalar>(fn: (value: T, index: Label, pos: number) => U): Series<U> {
+    return new Series<U>({
+      data: this._values.map((v, i) => fn(v, this.index.at(i), i)),
+      index: this.index,
+      name: this.name,
+    });
+  }
+
+  // ─── set operations ───────────────────────────────────────────────────────
+
+  /** True when `value` exists in this Series. */
+  isin(values: readonly T[]): Series<boolean> {
+    const set = new Set<T>(values);
+    return new Series<boolean>({
+      data: this._values.map((v) => set.has(v)),
+      index: this.index,
+      dtype: Dtype.bool,
+      name: this.name,
+    });
+  }
+
+  // ─── conversion ───────────────────────────────────────────────────────────
+
+  toArray(): T[] {
+    return [...this._values];
+  }
+
+  toList(): T[] {
+    return this.toArray();
+  }
+
+  /**
+   * Convert to a plain key→value object.
+   * Works best when the index is string-labeled.
+   */
+  toObject(): Record<string, T> {
+    const result: Record<string, T> = {};
+    for (let i = 0; i < this._values.length; i++) {
+      result[String(this.index.at(i))] = this._values[i] as T;
+    }
+    return result;
+  }
+
+  // ─── iteration ────────────────────────────────────────────────────────────
+
+  *[Symbol.iterator](): Generator<T> {
+    for (const v of this._values) {
+      yield v;
+    }
+  }
+
+  // ─── display ──────────────────────────────────────────────────────────────
+
+  toString(): string {
+    const rows = this._values.map((v, i) => `${String(this.index.at(i))}\t${String(v)}`).join("\n");
+    const footer = `Name: ${this.name ?? "(unnamed)"}, dtype: ${this.dtype.name}, Length: ${this.size}`;
+    return `${rows}\n${footer}`;
+  }
+}
diff --git a/src/index.ts b/src/index.ts
index 978717d4..7d4ae761 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -29,3 +29,7 @@ export type {
 export { Index } from "./core/index.ts";
 export type { IndexOptions } from "./core/index.ts";
 export { RangeIndex } from "./core/index.ts";
+export { Dtype } from "./core/dtype.ts";
+export type { DtypeKind, ItemSize } from "./core/dtype.ts";
+export { Series } from "./core/series.ts";
+export type { SeriesOptions } from "./core/series.ts";
diff --git a/tests/core/dtype.test.ts b/tests/core/dtype.test.ts
new file mode 100644
index 00000000..74755558
--- /dev/null
+++ b/tests/core/dtype.test.ts
@@ -0,0 +1,158 @@
+/**
+ * Tests for the Dtype system.
+ */
+import { describe, expect, it } from "bun:test";
+import { Dtype } from "../../src/core/index.ts";
+
+describe("Dtype", () => {
+  describe("singletons", () => {
+    it("returns the same instance for identical names", () => {
+      expect(Dtype.from("float64")).toBe(Dtype.float64);
+      expect(Dtype.from("int32")).toBe(Dtype.int32);
+      expect(Dtype.from("bool")).toBe(Dtype.bool);
+    });
+
+    it("all 16 named dtypes are accessible", () => {
+      const names = [
+        "int8",
+        "int16",
+        "int32",
+        "int64",
+        "uint8",
+        "uint16",
+        "uint32",
+        "uint64",
+        "float32",
+        "float64",
+        "bool",
+        "string",
+        "object",
+        "datetime",
+        "timedelta",
+        "category",
+      ] as const;
+      for (const n of names) {
+        const dt = Dtype.from(n);
+        expect(dt.name).toBe(n);
+      }
+    });
+  });
+
+  describe("kind classification", () => {
+    it("integer kinds", () => {
+      expect(Dtype.int32.kind).toBe("int");
+      expect(Dtype.int32.isInteger).toBe(true);
+      expect(Dtype.int32.isSignedInteger).toBe(true);
+      expect(Dtype.uint16.isUnsignedInteger).toBe(true);
+    });
+
+    it("float kind", () => {
+      expect(Dtype.float64.isFloat).toBe(true);
+      expect(Dtype.float64.isNumeric).toBe(true);
+    });
+
+    it("bool kind", () => {
+      expect(Dtype.bool.isBool).toBe(true);
+    });
+
+    it("string kind", () => {
+      expect(Dtype.string.isString).toBe(true);
+    });
+
+    it("datetime kind", () => {
+      expect(Dtype.datetime.isDatetime).toBe(true);
+    });
+  });
+
+  describe("itemsize", () => {
+    it("int8 is 1 byte", () => expect(Dtype.int8.itemsize).toBe(1));
+    it("int64 is 8 bytes", () => expect(Dtype.int64.itemsize).toBe(8));
+    it("float32 is 4 bytes", () => expect(Dtype.float32.itemsize).toBe(4));
+    it("string itemsize is 0 (variable)", () => expect(Dtype.string.itemsize).toBe(0));
+  });
+
+  describe("canCastTo", () => {
+    it("can cast int8 → int32", () => {
+      expect(Dtype.int8.canCastTo(Dtype.int32)).toBe(true);
+    });
+
+    it("cannot cast int32 → int8", () => {
+      expect(Dtype.int32.canCastTo(Dtype.int8)).toBe(false);
+    });
+
+    it("can cast int64 → float64", () => {
+      expect(Dtype.int64.canCastTo(Dtype.float64)).toBe(true);
+    });
+
+    it("can cast bool → float64", () => {
+      expect(Dtype.bool.canCastTo(Dtype.float64)).toBe(true);
+    });
+
+    it("same type always castable", () => {
+      expect(Dtype.float64.canCastTo(Dtype.float64)).toBe(true);
+    });
+  });
+
+  describe("commonType", () => {
+    it("same dtype returns itself", () => {
+      expect(Dtype.commonType(Dtype.int32, Dtype.int32)).toBe(Dtype.int32);
+    });
+
+    it("int32 + int64 → int64", () => {
+      expect(Dtype.commonType(Dtype.int32, Dtype.int64)).toBe(Dtype.int64);
+    });
+
+    it("int + float → float64", () => {
+      expect(Dtype.commonType(Dtype.int32, Dtype.float64)).toBe(Dtype.float64);
+    });
+
+    it("bool + int → int (numeric)", () => {
+      const result = Dtype.commonType(Dtype.bool, Dtype.int32);
+      expect(result.isNumeric).toBe(true);
+    });
+
+    it("int + string → object", () => {
+      expect(Dtype.commonType(Dtype.int32, Dtype.string)).toBe(Dtype.object);
+    });
+  });
+
+  describe("inferFrom", () => {
+    it("empty array → float64", () => {
+      expect(Dtype.inferFrom([])).toBe(Dtype.float64);
+    });
+
+    it("all booleans → bool", () => {
+      expect(Dtype.inferFrom([true, false, true])).toBe(Dtype.bool);
+    });
+
+    it("all integers → int64", () => {
+      expect(Dtype.inferFrom([1, 2, 3])).toBe(Dtype.int64);
+    });
+
+    it("mixed int/float → float64", () => {
+      expect(Dtype.inferFrom([1, 2.5, 3])).toBe(Dtype.float64);
+    });
+
+    it("all strings → string", () => {
+      expect(Dtype.inferFrom(["a", "b", "c"])).toBe(Dtype.string);
+    });
+
+    it("all Dates → datetime", () => {
+      expect(Dtype.inferFrom([new Date(), new Date()])).toBe(Dtype.datetime);
+    });
+
+    it("mixed types → object", () => {
+      expect(Dtype.inferFrom([1, "a", true])).toBe(Dtype.object);
+    });
+
+    it("nulls are treated as compatible with any type", () => {
+      expect(Dtype.inferFrom([1, null, 2])).toBe(Dtype.int64);
+    });
+  });
+
+  describe("toString", () => {
+    it("returns the dtype name", () => {
+      expect(Dtype.float64.toString()).toBe("float64");
+    });
+  });
+});
diff --git a/tests/core/series.test.ts b/tests/core/series.test.ts
new file mode 100644
index 00000000..30f24644
--- /dev/null
+++ b/tests/core/series.test.ts
@@ -0,0 +1,278 @@
+/**
+ * Tests for Series.
+ */
+import { describe, expect, it } from "bun:test";
+import { Dtype, Index, Series } from "../../src/core/index.ts";
+describe("Series", () => {
+  describe("construction", () => {
+    it("creates from numeric array with default RangeIndex", () => {
+      const s = new Series({ data: [1, 2, 3] });
+      expect(s.size).toBe(3);
+      expect(s.dtype).toBe(Dtype.int64);
+    });
+
+    it("creates with an explicit string index", () => {
+      const s = new Series({ data: [10, 20, 30], index: ["a", "b", "c"] });
+      expect(s.index.size).toBe(3);
+      expect(s.at("a")).toBe(10);
+    });
+
+    it("creates with an explicit Index object", () => {
+      const idx = new Index<string | number>(["x", "y"]);
+      const s = new Series({ data: [1, 2], index: idx });
+      expect(s.at("x")).toBe(1);
+    });
+
+    it("throws when index length mismatches data length", () => {
+      expect(() => new Series({ data: [1, 2], index: ["a"] })).toThrow(RangeError);
+    });
+
+    it("infers dtype from data", () => {
+      expect(new Series({ data: [true, false] }).dtype).toBe(Dtype.bool);
+      expect(new Series({ data: ["a", "b"] }).dtype).toBe(Dtype.string);
+    });
+
+    it("respects an explicit dtype override", () => {
+      const s = new Series({ data: [1, 2], dtype: Dtype.float64 });
+      expect(s.dtype).toBe(Dtype.float64);
+    });
+
+    it("stores the name", () => {
+      expect(new Series({ data: [1], name: "price" }).name).toBe("price");
+    });
+
+    it("name defaults to null", () => {
+      expect(new Series({ data: [1] }).name).toBeNull();
+    });
+  });
+
+  describe("fromObject", () => {
+    it("creates from a plain object", () => {
+      const s = Series.fromObject({ a: 1, b: 2, c: 3 });
+      expect(s.at("a")).toBe(1);
+      expect(s.size).toBe(3);
+    });
+  });
+
+  describe("properties", () => {
+    const s = new Series({ data: [1, 2, 3] });
+
+    it("size", () => expect(s.size).toBe(3));
+    it("length", () => expect(s.length).toBe(3));
+    it("shape", () => expect(s.shape).toEqual([3]));
+    it("ndim", () => expect(s.ndim).toBe(1));
+    it("empty (false)", () => expect(s.empty).toBe(false));
+    it("empty (true)", () => expect(new Series({ data: [] }).empty).toBe(true));
+    it("values", () => expect(s.values).toEqual([1, 2, 3]));
+  });
+
+  describe("element access", () => {
+    const s = new Series({ data: [10, 20, 30], index: ["a", "b", "c"], name: "v" });
+
+    it("at(label)", () => expect(s.at("a")).toBe(10));
+    it("iat(0)", () => expect(s.iat(0)).toBe(10));
+    it("iat(-1)", () => expect(s.iat(-1)).toBe(30));
+    it("loc(label)", () => expect(s.loc("b")).toBe(20));
+
+    it("loc(labels) returns a new Series", () => {
+      const sub = s.loc(["a", "c"]);
+      expect(sub instanceof Series).toBe(true);
+      expect(sub.size).toBe(2);
+      expect(sub.iat(0)).toBe(10);
+      expect(sub.iat(1)).toBe(30);
+    });
+
+    it("iloc(position) returns scalar", () => expect(s.iloc(1)).toBe(20));
+
+    it("iloc(positions) returns a new Series", () => {
+      const sub = s.iloc([0, 2]);
+      expect(sub instanceof Series).toBe(true);
+      expect(sub.size).toBe(2);
+    });
+
+    it("iat out of bounds throws", () => {
+      expect(() => s.iat(100)).toThrow(RangeError);
+    });
+  });
+
+  describe("arithmetic", () => {
+    const a = new Series({ data: [1, 2, 3] });
+    const b = new Series({ data: [4, 5, 6] });
+
+    it("add scalar", () => expect(a.add(10 as never).values).toEqual([11, 12, 13]));
+    it("add series", () => expect(a.add(b as never).values).toEqual([5, 7, 9]));
+    it("sub series", () => expect(b.sub(a as never).values).toEqual([3, 3, 3]));
+    it("mul scalar", () => expect(a.mul(2 as never).values).toEqual([2, 4, 6]));
+    it("div series", () => expect(b.div(a as never).values).toEqual([4, 2.5, 2]));
+    it("mod", () => expect(b.mod(a as never).values).toEqual([0, 1, 0]));
+    it("pow", () => expect(a.pow(2 as never).values).toEqual([1, 4, 9]));
+    it("floordiv", () => expect(b.floordiv(a as never).values).toEqual([4, 2, 2]));
+
+    it("throws when sizes differ", () => {
+      const c = new Series({ data: [1, 2] });
+      expect(() => a.add(c as never)).toThrow(RangeError);
+    });
+  });
+
+  describe("comparison", () => {
+    const s = new Series({ data: [1, 2, 3] });
+
+    it("eq", () => expect(s.eq(2 as never).values).toEqual([false, true, false]));
+    it("ne", () => expect(s.ne(2 as never).values).toEqual([true, false, true]));
+    it("lt", () => expect(s.lt(2 as never).values).toEqual([true, false, false]));
+    it("le", () => expect(s.le(2 as never).values).toEqual([true, true, false]));
+    it("gt", () => expect(s.gt(2 as never).values).toEqual([false, false, true]));
+    it("ge", () => expect(s.ge(2 as never).values).toEqual([false, true, true]));
+  });
+
+  describe("filter", () => {
+    const s = new Series({ data: [1, 2, 3, 4, 5] });
+
+    it("filters by boolean mask array", () => {
+      const result = s.filter([true, false, true, false, true]);
+      expect(result.values).toEqual([1, 3, 5]);
+    });
+
+    it("filters by boolean Series", () => {
+      const mask = s.gt(2 as never);
+      const result = s.filter(mask);
+      expect(result.values).toEqual([3, 4, 5]);
+    });
+
+    it("throws on mask length mismatch", () => {
+      expect(() => s.filter([true, false])).toThrow(RangeError);
+    });
+  });
+
+  describe("missing values", () => {
+    const s = new Series<number | null>({ data: [1, null, 3, null, 5] });
+
+    it("isna", () => expect(s.isna().values).toEqual([false, true, false, true, false]));
+    it("notna", () => expect(s.notna().values).toEqual([true, false, true, false, true]));
+    it("dropna removes nulls", () => expect(s.dropna().values).toEqual([1, 3, 5]));
+    it("fillna replaces nulls", () => {
+      const filled = s.fillna(0);
+      expect(filled.values).toEqual([1, 0, 3, 0, 5]);
+    });
+  });
+
+  describe("aggregation", () => {
+    const s = new Series({ data: [1, 2, 3, 4, 5] });
+
+    it("sum", () => expect(s.sum()).toBe(15));
+    it("mean", () => expect(s.mean()).toBe(3));
+    it("min", () => expect(s.min()).toBe(1));
+    it("max", () => expect(s.max()).toBe(5));
+    it("count", () => expect(s.count()).toBe(5));
+    it("median", () => expect(s.median()).toBe(3));
+    it("std (ddof=1)", () => {
+      const std = s.std();
+      expect(std).toBeCloseTo(Math.sqrt(2.5));
+    });
+    it("var (ddof=1)", () => expect(s.var()).toBeCloseTo(2.5));
+    it("nunique", () => expect(s.nunique()).toBe(5));
+
+    it("sum with nulls skips them", () => {
+      const s2 = new Series({ data: [1, null, 2, null, 3] as never[] });
+      expect(s2.sum()).toBe(6);
+    });
+
+    it("mean returns NaN for empty", () => {
+      expect(Number.isNaN(new Series({ data: [] }).mean())).toBe(true);
+    });
+  });
+
+  describe("valueCounts", () => {
+    it("returns counts sorted by frequency", () => {
+      const s = new Series({ data: ["a", "b", "a", "c", "a", "b"] });
+      const vc = s.valueCounts();
+      expect(vc.iat(0)).toBe(3); // 'a' appears 3 times
+      expect(vc.iat(1)).toBe(2); // 'b' appears 2 times
+      expect(vc.iat(2)).toBe(1); // 'c' appears 1 time
+    });
+  });
+
+  describe("sorting", () => {
+    it("sortValues ascending", () => {
+      const s = new Series({ data: [3, 1, 2] });
+      expect(s.sortValues().values).toEqual([1, 2, 3]);
+    });
+
+    it("sortValues descending", () => {
+      const s = new Series({ data: [3, 1, 2] });
+      expect(s.sortValues(false).values).toEqual([3, 2, 1]);
+    });
+
+    it("sortValues places nulls last by default", () => {
+      const s = new Series<number | null>({ data: [3, null, 1] });
+      expect(s.sortValues().values).toEqual([1, 3, null]);
+    });
+
+    it("sortIndex ascending", () => {
+      const s = new Series({ data: [10, 20, 30], index: ["c", "a", "b"] });
+      const sorted = s.sortIndex();
+      expect(sorted.index.values).toEqual(["a", "b", "c"]);
+      expect(sorted.values).toEqual([20, 30, 10]);
+    });
+  });
+
+  describe("manipulation", () => {
+    it("copy creates independent copy", () => {
+      const s = new Series({ data: [1, 2, 3], name: "x" });
+      const c = s.copy();
+      expect(c.values).toEqual(s.values);
+      expect(c).not.toBe(s);
+    });
+
+    it("rename changes name", () => {
+      const s = new Series({ data: [1], name: "x" });
+      expect(s.rename("y").name).toBe("y");
+    });
+
+    it("resetIndex gives RangeIndex", () => {
+      const s = new Series({ data: [1, 2, 3], index: ["a", "b", "c"] });
+      const r = s.resetIndex();
+      expect(r.index.values).toEqual([0, 1, 2]);
+    });
+
+    it("map transforms values", () => {
+      const s = new Series({ data: [1, 2, 3] });
+      const doubled = s.map((v) => (v as number) * 2);
+      expect(doubled.values).toEqual([2, 4, 6]);
+    });
+  });
+
+  describe("isin", () => {
+    it("returns boolean mask", () => {
+      const s = new Series({ data: [1, 2, 3, 4] });
+      expect(s.isin([2, 4] as never[]).values).toEqual([false, true, false, true]);
+    });
+  });
+
+  describe("conversion", () => {
+    it("toArray", () => {
+      expect(new Series({ data: [1, 2] }).toArray()).toEqual([1, 2]);
+    });
+
+    it("toObject", () => {
+      const s = new Series({ data: [10, 20], index: ["a", "b"] });
+      expect(s.toObject()).toEqual({ a: 10, b: 20 });
+    });
+  });
+
+  describe("iteration", () => {
+    it("is iterable", () => {
+      const s = new Series({ data: [1, 2, 3] });
+      expect([...s]).toEqual([1, 2, 3]);
+    });
+  });
+
+  describe("toString", () => {
+    it("includes dtype and length", () => {
+      const s = new Series({ data: [1, 2], name: "val" });
+      const str = s.toString();
+      expect(str).toContain("val");
+      expect(str).toContain("int64");
+    });
+  });
+});

From cada2ee96bd6ec42b6628bc74aab4d0181c3638d Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sat, 4 Apr 2026 04:04:59 +0000
Subject: [PATCH 3/4] Apply Autoloop Iteration 3 changes (Dtype system +
 Series) and fix lint issues

Cherry-pick the Dtype system and Series implementation from the autoloop
branch (autoloop/build-tsb-pandas-typescript-migration-bdf4100e5aade1f0).
Resolve merge conflicts by keeping main's base-index.ts fixes (wider Label
types, no as-casts). Fix new lint warnings: use barrel exports, add default
switch clause, extract sort comparator to reduce cognitive complexity.

Agent-Logs-Url: https://github.com/githubnext/tsessebe/sessions/8871403f-f41c-4311-a8fd-19f148d98d2d

Co-authored-by: mrjf <180956+mrjf@users.noreply.github.com>
---
 src/core/dtype.ts         |  4 +++
 src/core/series.ts        | 53 +++++++++++++++++++++++----------------
 src/index.ts              |  8 +++---
 tests/core/dtype.test.ts  |  2 +-
 tests/core/series.test.ts |  2 +-
 5 files changed, 41 insertions(+), 28 deletions(-)

diff --git a/src/core/dtype.ts b/src/core/dtype.ts
index de30242a..6ca8622b 100644
--- a/src/core/dtype.ts
+++ b/src/core/dtype.ts
@@ -105,6 +105,10 @@ export class Dtype {
         return new Dtype("timedelta", "timedelta", 8);
       case "category":
         return new Dtype("category", "category", 0);
+      default: {
+        const _exhaustive: never = name;
+        throw new Error(`Unknown dtype: ${_exhaustive}`);
+      }
     }
   }
 
diff --git a/src/core/series.ts b/src/core/series.ts
index f973b441..5ff2b6e6 100644
--- a/src/core/series.ts
+++ b/src/core/series.ts
@@ -19,6 +19,36 @@ function defaultIndex(n: number): Index<Label> {
   return new RangeIndex(n) as unknown as Index<Label>;
 }
 
+/** True when the value should be treated as missing (null, undefined, or NaN). */
+function isMissing(v: Scalar): boolean {
+  return v === null || v === undefined || (typeof v === "number" && Number.isNaN(v));
+}
+
+/** Compare two scalar values with null/NaN handling for sorting. */
+function compareScalars(
+  a: Scalar,
+  b: Scalar,
+  ascending: boolean,
+  naPosition: "first" | "last",
+): number {
+  const aNull = isMissing(a);
+  const bNull = isMissing(b);
+  if (aNull && bNull) {
+    return 0;
+  }
+  if (aNull) {
+    return naPosition === "first" ? -1 : 1;
+  }
+  if (bNull) {
+    return naPosition === "first" ? 1 : -1;
+  }
+  if (a === b) {
+    return 0;
+  }
+  const cmp = (a as number | string | boolean) < (b as number | string | boolean) ? -1 : 1;
+  return ascending ? cmp : -cmp;
+}
+
 // ─── SeriesOptions ────────────────────────────────────────────────────────────
 
 /** Constructor options accepted by `Series`. */
@@ -546,28 +576,7 @@ export class Series<T extends Scalar = Scalar> {
   /** Return a new Series sorted by values. */
   sortValues(ascending = true, naPosition: "first" | "last" = "last"): Series<T> {
     const pairs = this._values.map((v, i) => ({ v, i }));
-    pairs.sort((a, b) => {
-      const aNull =
-        a.v === null || a.v === undefined || (typeof a.v === "number" && Number.isNaN(a.v));
-      const bNull =
-        b.v === null || b.v === undefined || (typeof b.v === "number" && Number.isNaN(b.v));
-      if (aNull && bNull) {
-        return 0;
-      }
-      if (aNull) {
-        return naPosition === "first" ? -1 : 1;
-      }
-      if (bNull) {
-        return naPosition === "first" ? 1 : -1;
-      }
-      const av = a.v as number | string | boolean;
-      const bv = b.v as number | string | boolean;
-      if (av === bv) {
-        return 0;
-      }
-      const cmp = av < bv ? -1 : 1;
-      return ascending ? cmp : -cmp;
-    });
+    pairs.sort((a, b) => compareScalars(a.v, b.v, ascending, naPosition));
     return new Series<T>({
       data: pairs.map(({ v }) => v),
       index: this.index.take(pairs.map(({ i }) => i)),
diff --git a/src/index.ts b/src/index.ts
index 7d4ae761..dc6b1c4e 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -29,7 +29,7 @@ export type {
 export { Index } from "./core/index.ts";
 export type { IndexOptions } from "./core/index.ts";
 export { RangeIndex } from "./core/index.ts";
-export { Dtype } from "./core/dtype.ts";
-export type { DtypeKind, ItemSize } from "./core/dtype.ts";
-export { Series } from "./core/series.ts";
-export type { SeriesOptions } from "./core/series.ts";
+export { Dtype } from "./core/index.ts";
+export type { DtypeKind, ItemSize } from "./core/index.ts";
+export { Series } from "./core/index.ts";
+export type { SeriesOptions } from "./core/index.ts";
diff --git a/tests/core/dtype.test.ts b/tests/core/dtype.test.ts
index 74755558..d1eafed3 100644
--- a/tests/core/dtype.test.ts
+++ b/tests/core/dtype.test.ts
@@ -2,7 +2,7 @@
  * Tests for the Dtype system.
  */
 import { describe, expect, it } from "bun:test";
-import { Dtype } from "../../src/core/index.ts";
+import { Dtype } from "../../src/index.ts";
 
 describe("Dtype", () => {
   describe("singletons", () => {
diff --git a/tests/core/series.test.ts b/tests/core/series.test.ts
index 30f24644..cfa26db5 100644
--- a/tests/core/series.test.ts
+++ b/tests/core/series.test.ts
@@ -2,7 +2,7 @@
  * Tests for Series.
  */
 import { describe, expect, it } from "bun:test";
-import { Dtype, Index, Series } from "../../src/core/index.ts";
+import { Dtype, Index, Series } from "../../src/index.ts";
 describe("Series", () => {
   describe("construction", () => {
     it("creates from numeric array with default RangeIndex", () => {

From 1ed567459878566749fd55439271544c393b9415 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sat, 4 Apr 2026 04:10:02 +0000
Subject: [PATCH 4/4] Widen Series method signatures to eliminate as-never
 casts in tests

Widen arithmetic methods to accept number | Series<Scalar> instead of
T | Series<T>, comparison methods to accept Scalar | Series<Scalar>,
and isin to accept readonly Scalar[]. This avoids literal type narrowing
issues that previously required as-never casts in tests.

Agent-Logs-Url: https://github.com/githubnext/tsessebe/sessions/8871403f-f41c-4311-a8fd-19f148d98d2d

Co-authored-by: mrjf <180956+mrjf@users.noreply.github.com>
---
 src/core/series.ts        | 48 ++++++++++++++++++++++-----------------
 tests/core/series.test.ts | 36 ++++++++++++++---------------
 2 files changed, 45 insertions(+), 39 deletions(-)

diff --git a/src/core/series.ts b/src/core/series.ts
index 5ff2b6e6..005e94ad 100644
--- a/src/core/series.ts
+++ b/src/core/series.ts
@@ -214,7 +214,10 @@ export class Series<T extends Scalar = Scalar> {
 
   // ─── arithmetic ───────────────────────────────────────────────────────────
 
-  private _scalarOp(other: T | Series<T>, fn: (a: number, b: number) => number): Series<number> {
+  private _scalarOp(
+    other: number | Series<Scalar>,
+    fn: (a: number, b: number) => number,
+  ): Series<number> {
     const isScalar = !(other instanceof Series);
     if (isScalar) {
       const b = other as number;
@@ -229,7 +232,7 @@ export class Series<T extends Scalar = Scalar> {
         name: this.name,
       });
     }
-    const o = other as Series<T>;
+    const o = other as Series<Scalar>;
     if (o.size !== this.size) {
       throw new RangeError(
         `Cannot operate on Series of different sizes: ${this.size} vs ${o.size}`,
@@ -249,46 +252,49 @@ export class Series<T extends Scalar = Scalar> {
   }
 
   /** Element-wise addition. */
-  add(other: T | Series<T>): Series<number> {
+  add(other: number | Series<Scalar>): Series<number> {
     return this._scalarOp(other, (a, b) => a + b);
   }
 
   /** Element-wise subtraction. */
-  sub(other: T | Series<T>): Series<number> {
+  sub(other: number | Series<Scalar>): Series<number> {
     return this._scalarOp(other, (a, b) => a - b);
   }
 
   /** Element-wise multiplication. */
-  mul(other: T | Series<T>): Series<number> {
+  mul(other: number | Series<Scalar>): Series<number> {
     return this._scalarOp(other, (a, b) => a * b);
   }
 
   /** Element-wise division (true division, returns float). */
-  div(other: T | Series<T>): Series<number> {
+  div(other: number | Series<Scalar>): Series<number> {
     return this._scalarOp(other, (a, b) => a / b);
   }
 
   /** Element-wise floor division. */
-  floordiv(other: T | Series<T>): Series<number> {
+  floordiv(other: number | Series<Scalar>): Series<number> {
     return this._scalarOp(other, (a, b) => Math.floor(a / b));
   }
 
   /** Element-wise modulo. */
-  mod(other: T | Series<T>): Series<number> {
+  mod(other: number | Series<Scalar>): Series<number> {
     return this._scalarOp(other, (a, b) => a % b);
   }
 
   /** Element-wise exponentiation. */
-  pow(other: T | Series<T>): Series<number> {
+  pow(other: number | Series<Scalar>): Series<number> {
     return this._scalarOp(other, (a, b) => a ** b);
   }
 
   // ─── comparison ───────────────────────────────────────────────────────────
 
-  private _cmpOp(other: T | Series<T>, fn: (a: T, b: T) => boolean): Series<boolean> {
+  private _cmpOp(
+    other: Scalar | Series<Scalar>,
+    fn: (a: Scalar, b: Scalar) => boolean,
+  ): Series<boolean> {
     const isScalar = !(other instanceof Series);
     if (isScalar) {
-      const b = other as T;
+      const b = other as Scalar;
       const newData = this._values.map((a) => fn(a, b));
       return new Series<boolean>({
         data: newData,
@@ -297,11 +303,11 @@ export class Series<T extends Scalar = Scalar> {
         name: this.name,
       });
     }
-    const o = other as Series<T>;
+    const o = other as Series<Scalar>;
     if (o.size !== this.size) {
       throw new RangeError(`Cannot compare Series of different sizes: ${this.size} vs ${o.size}`);
     }
-    const newData = this._values.map((a, i) => fn(a, o._values[i] as T));
+    const newData = this._values.map((a, i) => fn(a, o._values[i] as Scalar));
     return new Series<boolean>({
       data: newData,
       index: this.index,
@@ -310,15 +316,15 @@ export class Series<T extends Scalar = Scalar> {
     });
   }
 
-  eq(other: T | Series<T>): Series<boolean> {
+  eq(other: Scalar | Series<Scalar>): Series<boolean> {
     return this._cmpOp(other, (a, b) => a === b);
   }
 
-  ne(other: T | Series<T>): Series<boolean> {
+  ne(other: Scalar | Series<Scalar>): Series<boolean> {
     return this._cmpOp(other, (a, b) => a !== b);
   }
 
-  lt(other: T | Series<T>): Series<boolean> {
+  lt(other: Scalar | Series<Scalar>): Series<boolean> {
     return this._cmpOp(other, (a, b) => {
       if (a === null || b === null) {
         return false;
@@ -327,7 +333,7 @@ export class Series<T extends Scalar = Scalar> {
     });
   }
 
-  le(other: T | Series<T>): Series<boolean> {
+  le(other: Scalar | Series<Scalar>): Series<boolean> {
     return this._cmpOp(other, (a, b) => {
       if (a === null || b === null) {
         return false;
@@ -336,7 +342,7 @@ export class Series<T extends Scalar = Scalar> {
     });
   }
 
-  gt(other: T | Series<T>): Series<boolean> {
+  gt(other: Scalar | Series<Scalar>): Series<boolean> {
     return this._cmpOp(other, (a, b) => {
       if (a === null || b === null) {
         return false;
@@ -345,7 +351,7 @@ export class Series<T extends Scalar = Scalar> {
     });
   }
 
-  ge(other: T | Series<T>): Series<boolean> {
+  ge(other: Scalar | Series<Scalar>): Series<boolean> {
     return this._cmpOp(other, (a, b) => {
       if (a === null || b === null) {
         return false;
@@ -648,8 +654,8 @@ export class Series<T extends Scalar = Scalar> {
   // ─── set operations ───────────────────────────────────────────────────────
 
   /** True when `value` exists in this Series. */
-  isin(values: readonly T[]): Series<boolean> {
-    const set = new Set<T>(values);
+  isin(values: readonly Scalar[]): Series<boolean> {
+    const set = new Set<Scalar>(values);
     return new Series<boolean>({
       data: this._values.map((v) => set.has(v)),
       index: this.index,
diff --git a/tests/core/series.test.ts b/tests/core/series.test.ts
index cfa26db5..ca939fa7 100644
--- a/tests/core/series.test.ts
+++ b/tests/core/series.test.ts
@@ -99,30 +99,30 @@ describe("Series", () => {
     const a = new Series({ data: [1, 2, 3] });
     const b = new Series({ data: [4, 5, 6] });
 
-    it("add scalar", () => expect(a.add(10 as never).values).toEqual([11, 12, 13]));
-    it("add series", () => expect(a.add(b as never).values).toEqual([5, 7, 9]));
-    it("sub series", () => expect(b.sub(a as never).values).toEqual([3, 3, 3]));
-    it("mul scalar", () => expect(a.mul(2 as never).values).toEqual([2, 4, 6]));
-    it("div series", () => expect(b.div(a as never).values).toEqual([4, 2.5, 2]));
-    it("mod", () => expect(b.mod(a as never).values).toEqual([0, 1, 0]));
-    it("pow", () => expect(a.pow(2 as never).values).toEqual([1, 4, 9]));
-    it("floordiv", () => expect(b.floordiv(a as never).values).toEqual([4, 2, 2]));
+    it("add scalar", () => expect(a.add(10).values).toEqual([11, 12, 13]));
+    it("add series", () => expect(a.add(b).values).toEqual([5, 7, 9]));
+    it("sub series", () => expect(b.sub(a).values).toEqual([3, 3, 3]));
+    it("mul scalar", () => expect(a.mul(2).values).toEqual([2, 4, 6]));
+    it("div series", () => expect(b.div(a).values).toEqual([4, 2.5, 2]));
+    it("mod", () => expect(b.mod(a).values).toEqual([0, 1, 0]));
+    it("pow", () => expect(a.pow(2).values).toEqual([1, 4, 9]));
+    it("floordiv", () => expect(b.floordiv(a).values).toEqual([4, 2, 2]));
 
     it("throws when sizes differ", () => {
       const c = new Series({ data: [1, 2] });
-      expect(() => a.add(c as never)).toThrow(RangeError);
+      expect(() => a.add(c)).toThrow(RangeError);
     });
   });
 
   describe("comparison", () => {
     const s = new Series({ data: [1, 2, 3] });
 
-    it("eq", () => expect(s.eq(2 as never).values).toEqual([false, true, false]));
-    it("ne", () => expect(s.ne(2 as never).values).toEqual([true, false, true]));
-    it("lt", () => expect(s.lt(2 as never).values).toEqual([true, false, false]));
-    it("le", () => expect(s.le(2 as never).values).toEqual([true, true, false]));
-    it("gt", () => expect(s.gt(2 as never).values).toEqual([false, false, true]));
-    it("ge", () => expect(s.ge(2 as never).values).toEqual([false, true, true]));
+    it("eq", () => expect(s.eq(2).values).toEqual([false, true, false]));
+    it("ne", () => expect(s.ne(2).values).toEqual([true, false, true]));
+    it("lt", () => expect(s.lt(2).values).toEqual([true, false, false]));
+    it("le", () => expect(s.le(2).values).toEqual([true, true, false]));
+    it("gt", () => expect(s.gt(2).values).toEqual([false, false, true]));
+    it("ge", () => expect(s.ge(2).values).toEqual([false, true, true]));
   });
 
   describe("filter", () => {
@@ -134,7 +134,7 @@ describe("Series", () => {
     });
 
     it("filters by boolean Series", () => {
-      const mask = s.gt(2 as never);
+      const mask = s.gt(2);
       const result = s.filter(mask);
       expect(result.values).toEqual([3, 4, 5]);
     });
@@ -173,7 +173,7 @@ describe("Series", () => {
     it("nunique", () => expect(s.nunique()).toBe(5));
 
     it("sum with nulls skips them", () => {
-      const s2 = new Series({ data: [1, null, 2, null, 3] as never[] });
+      const s2 = new Series({ data: [1, null, 2, null, 3] });
       expect(s2.sum()).toBe(6);
     });
 
@@ -245,7 +245,7 @@ describe("Series", () => {
   describe("isin", () => {
     it("returns boolean mask", () => {
       const s = new Series({ data: [1, 2, 3, 4] });
-      expect(s.isin([2, 4] as never[]).values).toEqual([false, true, false, true]);
+      expect(s.isin([2, 4]).values).toEqual([false, true, false, true]);
     });
   });