@atscript/db-memory 0.1.152 → 0.1.154

package/dist/index.cjs

@@ -428,8 +428,8 @@ function buildMemoryPredicate(filter, relationSets) {
 * there is exactly ONE implementation. Everything here is a pure function over
 * plain `Record<string, unknown>` rows — no adapter/table state — so other
 * consumers (e.g. moost-db's value-help controller) can reuse the SAME engine
-* instead of hand-rolling a second copy. The adapter wires its own PK-derived
-* tie-break / physical-PK fields in as parameters.
+* instead of hand-rolling a second copy. The adapter appends its own
+* physical primary-key fields to `$sort` before calling in.
 *
 * The dot-path READ / DELETE helpers (`getPath` / `deletePath`) are the
 * core's (`@atscript/db`); the dot-path WRITE helper ({@link setPath}) lives
@@ -455,6 +455,24 @@ function compareLeaves(a, b) {
 	return as < bs ? -1 : as > bs ? 1 : 0;
 }
 /**
+* {@link compareLeaves} with a NULL placement: `'first'` / `'last'` put
+* `null`/`undefined` before / after every value, and `desc` reverses only the
+* comparison of two values (since 0.1.153). Without `nulls`, nil is the
+* smallest value and `desc` reverses everything, as before.
+*/
+function compareSortKey(a, b, desc, nulls) {
+	if (nulls) {
+		const aNil = a === null || a === void 0;
+		const bNil = b === null || b === void 0;
+		if (aNil || bNil) {
+			if (aNil && bNil) return 0;
+			return (aNil ? -1 : 1) * (nulls === "first" ? 1 : -1);
+		}
+	}
+	const cmp = compareLeaves(a, b);
+	return desc ? -cmp : cmp;
+}
+/**
 * Dot-path setter used by inclusion projection. Creates intermediate plain
 * objects as needed; overwrites a non-object intermediate. Top-level keys and
 * nested dot-paths both work.
@@ -479,24 +497,29 @@ function setSegments(target, segments, value) {
 * - No `$sort` (or an empty one) → returns the input array UNCHANGED (same
 *   reference, insertion order preserved) — the fast path for an unsorted read.
 * - `tieBreak`, when supplied, is the FINAL deterministic tie-break key for a
-*   TOTAL order — the adapter injects its {@link MemoryAdapter.pkKey} here so
-*   rows with equal sort keys still order deterministically. When ABSENT the
+*   TOTAL order, so rows with equal sort keys still order deterministically
+*   (the adapter instead appends its primary-key fields to `$sort`, compared
+*   by value like every other key — since 0.1.153). When ABSENT the
 *   sort falls back to preserving input order among equal keys (via each row's
 *   original index), so a consumer with no primary key keeps insertion order.
 * - `topK` (since 0.1.151), when supplied, asks for only the first `topK` rows
 *   of that order (e.g. `$skip + $limit`): a small one is selected in one pass
 *   instead of sorting everything. The rows returned are exactly the head of
 *   the full sort — same comparator, same stable tie handling.
+* - `nulls` (since 0.1.153) — the `$nulls` control: a `$sort` key with an
+*   entry puts `null`/missing values `'first'` or `'last'` in either
+*   direction; a key without one keeps them smallest.
 *
 * NEVER mutates the input array. Each row's sort keys are read ONCE (O(n)) and
 * its `tieBreak` only when two rows tie on every key — not inside the
 * O(n log n) comparator.
 */
-function sortRows(rows, $sort, tieBreak, topK) {
+function sortRows(rows, $sort, tieBreak, topK, nulls) {
 	const keys = $sort ? Object.entries($sort) : [];
 	if (keys.length === 0) return rows;
 	const readers = keys.map(([field]) => pathReader(field));
 	const desc = keys.map(([, dir]) => dir === -1);
+	const placement = nulls ? keys.map(([field]) => Object.hasOwn(nulls, field) ? nulls[field] : void 0) : [];
 	const decorated = rows.map((row, index) => ({
 		row,
 		index,
@@ -508,8 +531,8 @@ function sortRows(rows, $sort, tieBreak, topK) {
 	}));
 	const compare = (a, b) => {
 		for (let i = 0; i < desc.length; i++) {
-			const cmp = compareLeaves(a.keys[i], b.keys[i]);
-			if (cmp !== 0) return desc[i] ? -cmp : cmp;
+			const cmp = compareSortKey(a.keys[i], b.keys[i], desc[i], placement[i]);
+			if (cmp !== 0) return cmp;
 		}
 		if (tieBreak) {
 			const at = a.tie ??= tieBreak(a.row);
@@ -790,7 +813,7 @@ function aggregateRows(rows, controls) {
 	const having = controls.$having;
 	if (having) out = out.filter(buildMemoryPredicate(having));
 	if (controls.$count) return [{ count: out.length }];
-	const paged = paginate(sortRows(out, controls.$sort), controls.$skip, controls.$limit);
+	const paged = paginate(sortRows(out, controls.$sort, void 0, void 0, controls.$nulls), controls.$skip, controls.$limit);
 	const fields = ($select === void 0 ? groupBy : $select.asArray ?? []).map((field) => [field, pathReader(field)]);
 	const outputAliases = $select === void 0 ? [] : [...($select.buckets ?? []).map((b) => b.alias), ...$select.computedAliases];
 	return paged.map((row) => {
@@ -866,18 +889,19 @@ function exprAccumulatorFactory(e) {
 /**
 * `first` / `last`: the value of `fl.column` on the group's representative
 * row — the least (`first`) or greatest (`last`) row by `rowOrder` (NULL
-* smallest; the primary key is the final key, so the pick is deterministic).
+* smallest unless the key carries a `nulls` placement; the primary key is the final key, so the pick is deterministic).
 */
 function firstLastFactory(fl, rowOrder) {
 	const keys = rowOrder.map((k) => ({
 		read: pathReader(k.column),
-		sign: k.desc ? -1 : 1
+		desc: k.desc,
+		nulls: k.nulls
 	}));
 	const read = pathReader(fl.column);
 	const sign = fl.fn === "first" ? -1 : 1;
 	const compare = (a, b) => {
 		for (const k of keys) {
-			const c = compareLeaves(k.read(a), k.read(b)) * k.sign;
+			const c = compareSortKey(k.read(a), k.read(b), k.desc, k.nulls);
 			if (c !== 0) return c;
 		}
 		return 0;
@@ -1581,14 +1605,28 @@ var MemoryAdapter = class MemoryAdapter extends _atscript_db.BaseDbAdapter {
 		return { deletedCount: 1 };
 	}
 	/**
-	* Stable multi-key comparator from `$sort`, with a final tie-break on
-	* {@link pkKey} for a deterministic total order. Returns the input unchanged
+	* Stable multi-key comparator from `$sort`, with the primary-key fields it
+	* leaves out appended in the direction of its LAST key and compared by
+	* value (numbers numerically, `Date`s by instant) — the same tie-breaker
+	* the core appends before a read reaches any adapter (since 0.1.153), so a
+	* direct adapter call orders ties the same way. Returns the input unchanged
 	* (insertion order) when there is no `$sort`. Delegates to the shared pure
-	* {@link sortRows}, injecting {@link pkKey} as the total-order tie-break;
-	* `topK` asks for the head of that order only (`$skip + $limit`).
+	* {@link sortRows}; `topK` asks for the head of that order only
+	* (`$skip + $limit`).
 	*/
-	_sortRows(rows, $sort, topK) {
-		return sortRows(rows, $sort, (r) => this.pkKey(r), topK);
+	_sortRows(rows, $sort, $nulls, topK) {
+		return sortRows(rows, this._withPkTieBreak($sort), void 0, topK, $nulls);
+	}
+	/** `$sort` plus the primary-key fields it leaves out, in its last key's direction. */
+	_withPkTieBreak($sort) {
+		if (!$sort || !hasSort($sort)) return $sort;
+		const keys = Object.keys($sort);
+		const missing = this._physicalPkFields().filter((field) => !(field in $sort));
+		if (missing.length === 0) return $sort;
+		const dir = $sort[keys[keys.length - 1]];
+		const next = { ...$sort };
+		for (const field of missing) next[field] = dir;
+		return next;
 	}
 	/**
 	* Compiles the `$select` projection of one read: each returned row is a
@@ -1616,6 +1654,7 @@ var MemoryAdapter = class MemoryAdapter extends _atscript_db.BaseDbAdapter {
 	_readControls(controls) {
 		return {
 			$sort: controls.$sort,
+			$nulls: controls.$nulls,
 			$skip: controls.$skip,
 			$limit: controls.$limit,
 			$select: controls.$select
@@ -1652,9 +1691,9 @@ var MemoryAdapter = class MemoryAdapter extends _atscript_db.BaseDbAdapter {
 		return (await own).filter(buildMemoryPredicate(query.filter, sets));
 	}
 	async findOne(query) {
-		const { $sort, $skip, $select } = this._readControls(query.controls ?? {});
+		const { $sort, $nulls, $skip, $select } = this._readControls(query.controls ?? {});
 		const index = $skip ?? 0;
-		const row = (hasSort($sort) ? this._sortRows(await this._filteredRows(query), $sort, index + 1) : await this._filteredRows(query, index + 1))[index];
+		const row = (hasSort($sort) ? this._sortRows(await this._filteredRows(query), $sort, $nulls, index + 1) : await this._filteredRows(query, index + 1))[index];
 		return row ? this._projector($select)(row) : null;
 	}
 	async findMany(query) {
@@ -1672,10 +1711,10 @@ var MemoryAdapter = class MemoryAdapter extends _atscript_db.BaseDbAdapter {
 	*/
 	async findManyWithCount(query) {
 		const filtered = await this._filteredRows(query);
-		const { $sort, $skip, $limit, $select } = this._readControls(query.controls ?? {});
+		const { $sort, $nulls, $skip, $limit, $select } = this._readControls(query.controls ?? {});
 		const topK = $limit === void 0 ? void 0 : ($skip ?? 0) + $limit;
 		return {
-			data: paginate(this._sortRows(filtered, $sort, topK), $skip, $limit).map(this._projector($select)),
+			data: paginate(this._sortRows(filtered, $sort, $nulls, topK), $skip, $limit).map(this._projector($select)),
 			count: filtered.length
 		};
 	}
@@ -1709,6 +1748,10 @@ var MemoryAdapter = class MemoryAdapter extends _atscript_db.BaseDbAdapter {
 	supportsAggregateExpressions() {
 		return true;
 	}
+	/** NULL placement (`$nulls`, `@db.sort.nulls`) — `sortRows` honours it per key. */
+	supportsNullsPlacement() {
+		return true;
+	}
 	/** Managed views render nothing (non-goal) — both are accepted like `aggregateFns()`. */
 	viewCapabilities() {
 		return _atscript_db.ALL_VIEW_CAPABILITIES;

package/dist/index.d.cts

@@ -1,5 +1,6 @@
 import { AggregateFn, BaseDbAdapter, BucketUnit, DbQuery, DbSpace, FilterExpr, ResolvedRelationFilter, TDbDeleteResult, TDbFieldMeta, TDbInsertIgnoreSlot, TDbInsertManyResult, TDbInsertResult, TDbObjectKind, TDbUpdateOptions, TDbUpdateResult, TFieldOps, TViewCapability } from "@atscript/db";
 import { TAtscriptAnnotatedType } from "@atscript/typescript/utils";
+import { NullsPlacement } from "@uniqu/core";
 
 //#region src/lib/memory-adapter.d.ts
 /**
@@ -368,13 +369,18 @@ declare class MemoryAdapter extends BaseDbAdapter {
   updateOne(filter: FilterExpr, data: Record<string, unknown>, ops?: TFieldOps, expectedVersion?: number, opts?: TDbUpdateOptions): Promise<TDbUpdateResult>;
   deleteOne(filter: FilterExpr): Promise<TDbDeleteResult>;
   /**
-   * Stable multi-key comparator from `$sort`, with a final tie-break on
-   * {@link pkKey} for a deterministic total order. Returns the input unchanged
+   * Stable multi-key comparator from `$sort`, with the primary-key fields it
+   * leaves out appended in the direction of its LAST key and compared by
+   * value (numbers numerically, `Date`s by instant) — the same tie-breaker
+   * the core appends before a read reaches any adapter (since 0.1.153), so a
+   * direct adapter call orders ties the same way. Returns the input unchanged
    * (insertion order) when there is no `$sort`. Delegates to the shared pure
-   * {@link sortRows}, injecting {@link pkKey} as the total-order tie-break;
-   * `topK` asks for the head of that order only (`$skip + $limit`).
+   * {@link sortRows}; `topK` asks for the head of that order only
+   * (`$skip + $limit`).
    */
   private _sortRows;
+  /** `$sort` plus the primary-key fields it leaves out, in its last key's direction. */
+  private _withPkTieBreak;
   /**
    * Compiles the `$select` projection of one read: each returned row is a
    * fresh, deep-cloned object so the store can never be mutated through it.
@@ -444,6 +450,8 @@ declare class MemoryAdapter extends BaseDbAdapter {
   aggregateFns(): ReadonlySet<AggregateFn>;
   /** Arithmetic in an aggregate `$select` (`{ $expr }`, `{ $fn, $expr }`). */
   supportsAggregateExpressions(): boolean;
+  /** NULL placement (`$nulls`, `@db.sort.nulls`) — `sortRows` honours it per key. */
+  supportsNullsPlacement(): boolean;
   /** Managed views render nothing (non-goal) — both are accepted like `aggregateFns()`. */
   viewCapabilities(): ReadonlySet<TViewCapability>;
   updateMany(filter: FilterExpr, data: Record<string, unknown>, ops?: TFieldOps, opts?: TDbUpdateOptions): Promise<TDbUpdateResult>;
@@ -547,20 +555,24 @@ declare function buildMemoryPredicate(filter: FilterExpr, relationSets?: Relatio
  * - No `$sort` (or an empty one) → returns the input array UNCHANGED (same
  *   reference, insertion order preserved) — the fast path for an unsorted read.
  * - `tieBreak`, when supplied, is the FINAL deterministic tie-break key for a
- *   TOTAL order — the adapter injects its {@link MemoryAdapter.pkKey} here so
- *   rows with equal sort keys still order deterministically. When ABSENT the
+ *   TOTAL order, so rows with equal sort keys still order deterministically
+ *   (the adapter instead appends its primary-key fields to `$sort`, compared
+ *   by value like every other key — since 0.1.153). When ABSENT the
  *   sort falls back to preserving input order among equal keys (via each row's
  *   original index), so a consumer with no primary key keeps insertion order.
  * - `topK` (since 0.1.151), when supplied, asks for only the first `topK` rows
  *   of that order (e.g. `$skip + $limit`): a small one is selected in one pass
  *   instead of sorting everything. The rows returned are exactly the head of
  *   the full sort — same comparator, same stable tie handling.
+ * - `nulls` (since 0.1.153) — the `$nulls` control: a `$sort` key with an
+ *   entry puts `null`/missing values `'first'` or `'last'` in either
+ *   direction; a key without one keeps them smallest.
  *
  * NEVER mutates the input array. Each row's sort keys are read ONCE (O(n)) and
  * its `tieBreak` only when two rows tie on every key — not inside the
  * O(n log n) comparator.
  */
-declare function sortRows(rows: Record<string, unknown>[], $sort?: Partial<Record<string, 1 | -1>>, tieBreak?: (row: Record<string, unknown>) => string | number, topK?: number): Record<string, unknown>[];
+declare function sortRows(rows: Record<string, unknown>[], $sort?: Partial<Record<string, 1 | -1>>, tieBreak?: (row: Record<string, unknown>) => string | number, topK?: number, nulls?: Partial<Record<string, NullsPlacement>>): Record<string, unknown>[];
 /** Options for {@link projectRow}. */
 interface ProjectRowOptions {
   /**

package/dist/index.d.mts

@@ -1,4 +1,5 @@
 import { AggregateFn, BaseDbAdapter, BucketUnit, DbQuery, DbSpace, FilterExpr, ResolvedRelationFilter, TDbDeleteResult, TDbFieldMeta, TDbInsertIgnoreSlot, TDbInsertManyResult, TDbInsertResult, TDbObjectKind, TDbUpdateOptions, TDbUpdateResult, TFieldOps, TViewCapability } from "@atscript/db";
+import { NullsPlacement } from "@uniqu/core";
 import { TAtscriptAnnotatedType } from "@atscript/typescript/utils";
 
 //#region src/lib/memory-adapter.d.ts
@@ -368,13 +369,18 @@ declare class MemoryAdapter extends BaseDbAdapter {
   updateOne(filter: FilterExpr, data: Record<string, unknown>, ops?: TFieldOps, expectedVersion?: number, opts?: TDbUpdateOptions): Promise<TDbUpdateResult>;
   deleteOne(filter: FilterExpr): Promise<TDbDeleteResult>;
   /**
-   * Stable multi-key comparator from `$sort`, with a final tie-break on
-   * {@link pkKey} for a deterministic total order. Returns the input unchanged
+   * Stable multi-key comparator from `$sort`, with the primary-key fields it
+   * leaves out appended in the direction of its LAST key and compared by
+   * value (numbers numerically, `Date`s by instant) — the same tie-breaker
+   * the core appends before a read reaches any adapter (since 0.1.153), so a
+   * direct adapter call orders ties the same way. Returns the input unchanged
    * (insertion order) when there is no `$sort`. Delegates to the shared pure
-   * {@link sortRows}, injecting {@link pkKey} as the total-order tie-break;
-   * `topK` asks for the head of that order only (`$skip + $limit`).
+   * {@link sortRows}; `topK` asks for the head of that order only
+   * (`$skip + $limit`).
    */
   private _sortRows;
+  /** `$sort` plus the primary-key fields it leaves out, in its last key's direction. */
+  private _withPkTieBreak;
   /**
    * Compiles the `$select` projection of one read: each returned row is a
    * fresh, deep-cloned object so the store can never be mutated through it.
@@ -444,6 +450,8 @@ declare class MemoryAdapter extends BaseDbAdapter {
   aggregateFns(): ReadonlySet<AggregateFn>;
   /** Arithmetic in an aggregate `$select` (`{ $expr }`, `{ $fn, $expr }`). */
   supportsAggregateExpressions(): boolean;
+  /** NULL placement (`$nulls`, `@db.sort.nulls`) — `sortRows` honours it per key. */
+  supportsNullsPlacement(): boolean;
   /** Managed views render nothing (non-goal) — both are accepted like `aggregateFns()`. */
   viewCapabilities(): ReadonlySet<TViewCapability>;
   updateMany(filter: FilterExpr, data: Record<string, unknown>, ops?: TFieldOps, opts?: TDbUpdateOptions): Promise<TDbUpdateResult>;
@@ -547,20 +555,24 @@ declare function buildMemoryPredicate(filter: FilterExpr, relationSets?: Relatio
  * - No `$sort` (or an empty one) → returns the input array UNCHANGED (same
  *   reference, insertion order preserved) — the fast path for an unsorted read.
  * - `tieBreak`, when supplied, is the FINAL deterministic tie-break key for a
- *   TOTAL order — the adapter injects its {@link MemoryAdapter.pkKey} here so
- *   rows with equal sort keys still order deterministically. When ABSENT the
+ *   TOTAL order, so rows with equal sort keys still order deterministically
+ *   (the adapter instead appends its primary-key fields to `$sort`, compared
+ *   by value like every other key — since 0.1.153). When ABSENT the
  *   sort falls back to preserving input order among equal keys (via each row's
  *   original index), so a consumer with no primary key keeps insertion order.
  * - `topK` (since 0.1.151), when supplied, asks for only the first `topK` rows
  *   of that order (e.g. `$skip + $limit`): a small one is selected in one pass
  *   instead of sorting everything. The rows returned are exactly the head of
  *   the full sort — same comparator, same stable tie handling.
+ * - `nulls` (since 0.1.153) — the `$nulls` control: a `$sort` key with an
+ *   entry puts `null`/missing values `'first'` or `'last'` in either
+ *   direction; a key without one keeps them smallest.
  *
  * NEVER mutates the input array. Each row's sort keys are read ONCE (O(n)) and
  * its `tieBreak` only when two rows tie on every key — not inside the
  * O(n log n) comparator.
  */
-declare function sortRows(rows: Record<string, unknown>[], $sort?: Partial<Record<string, 1 | -1>>, tieBreak?: (row: Record<string, unknown>) => string | number, topK?: number): Record<string, unknown>[];
+declare function sortRows(rows: Record<string, unknown>[], $sort?: Partial<Record<string, 1 | -1>>, tieBreak?: (row: Record<string, unknown>) => string | number, topK?: number, nulls?: Partial<Record<string, NullsPlacement>>): Record<string, unknown>[];
 /** Options for {@link projectRow}. */
 interface ProjectRowOptions {
   /**

package/dist/index.mjs

@@ -427,8 +427,8 @@ function buildMemoryPredicate(filter, relationSets) {
 * there is exactly ONE implementation. Everything here is a pure function over
 * plain `Record<string, unknown>` rows — no adapter/table state — so other
 * consumers (e.g. moost-db's value-help controller) can reuse the SAME engine
-* instead of hand-rolling a second copy. The adapter wires its own PK-derived
-* tie-break / physical-PK fields in as parameters.
+* instead of hand-rolling a second copy. The adapter appends its own
+* physical primary-key fields to `$sort` before calling in.
 *
 * The dot-path READ / DELETE helpers (`getPath` / `deletePath`) are the
 * core's (`@atscript/db`); the dot-path WRITE helper ({@link setPath}) lives
@@ -454,6 +454,24 @@ function compareLeaves(a, b) {
 	return as < bs ? -1 : as > bs ? 1 : 0;
 }
 /**
+* {@link compareLeaves} with a NULL placement: `'first'` / `'last'` put
+* `null`/`undefined` before / after every value, and `desc` reverses only the
+* comparison of two values (since 0.1.153). Without `nulls`, nil is the
+* smallest value and `desc` reverses everything, as before.
+*/
+function compareSortKey(a, b, desc, nulls) {
+	if (nulls) {
+		const aNil = a === null || a === void 0;
+		const bNil = b === null || b === void 0;
+		if (aNil || bNil) {
+			if (aNil && bNil) return 0;
+			return (aNil ? -1 : 1) * (nulls === "first" ? 1 : -1);
+		}
+	}
+	const cmp = compareLeaves(a, b);
+	return desc ? -cmp : cmp;
+}
+/**
 * Dot-path setter used by inclusion projection. Creates intermediate plain
 * objects as needed; overwrites a non-object intermediate. Top-level keys and
 * nested dot-paths both work.
@@ -478,24 +496,29 @@ function setSegments(target, segments, value) {
 * - No `$sort` (or an empty one) → returns the input array UNCHANGED (same
 *   reference, insertion order preserved) — the fast path for an unsorted read.
 * - `tieBreak`, when supplied, is the FINAL deterministic tie-break key for a
-*   TOTAL order — the adapter injects its {@link MemoryAdapter.pkKey} here so
-*   rows with equal sort keys still order deterministically. When ABSENT the
+*   TOTAL order, so rows with equal sort keys still order deterministically
+*   (the adapter instead appends its primary-key fields to `$sort`, compared
+*   by value like every other key — since 0.1.153). When ABSENT the
 *   sort falls back to preserving input order among equal keys (via each row's
 *   original index), so a consumer with no primary key keeps insertion order.
 * - `topK` (since 0.1.151), when supplied, asks for only the first `topK` rows
 *   of that order (e.g. `$skip + $limit`): a small one is selected in one pass
 *   instead of sorting everything. The rows returned are exactly the head of
 *   the full sort — same comparator, same stable tie handling.
+* - `nulls` (since 0.1.153) — the `$nulls` control: a `$sort` key with an
+*   entry puts `null`/missing values `'first'` or `'last'` in either
+*   direction; a key without one keeps them smallest.
 *
 * NEVER mutates the input array. Each row's sort keys are read ONCE (O(n)) and
 * its `tieBreak` only when two rows tie on every key — not inside the
 * O(n log n) comparator.
 */
-function sortRows(rows, $sort, tieBreak, topK) {
+function sortRows(rows, $sort, tieBreak, topK, nulls) {
 	const keys = $sort ? Object.entries($sort) : [];
 	if (keys.length === 0) return rows;
 	const readers = keys.map(([field]) => pathReader(field));
 	const desc = keys.map(([, dir]) => dir === -1);
+	const placement = nulls ? keys.map(([field]) => Object.hasOwn(nulls, field) ? nulls[field] : void 0) : [];
 	const decorated = rows.map((row, index) => ({
 		row,
 		index,
@@ -507,8 +530,8 @@ function sortRows(rows, $sort, tieBreak, topK) {
 	}));
 	const compare = (a, b) => {
 		for (let i = 0; i < desc.length; i++) {
-			const cmp = compareLeaves(a.keys[i], b.keys[i]);
-			if (cmp !== 0) return desc[i] ? -cmp : cmp;
+			const cmp = compareSortKey(a.keys[i], b.keys[i], desc[i], placement[i]);
+			if (cmp !== 0) return cmp;
 		}
 		if (tieBreak) {
 			const at = a.tie ??= tieBreak(a.row);
@@ -789,7 +812,7 @@ function aggregateRows(rows, controls) {
 	const having = controls.$having;
 	if (having) out = out.filter(buildMemoryPredicate(having));
 	if (controls.$count) return [{ count: out.length }];
-	const paged = paginate(sortRows(out, controls.$sort), controls.$skip, controls.$limit);
+	const paged = paginate(sortRows(out, controls.$sort, void 0, void 0, controls.$nulls), controls.$skip, controls.$limit);
 	const fields = ($select === void 0 ? groupBy : $select.asArray ?? []).map((field) => [field, pathReader(field)]);
 	const outputAliases = $select === void 0 ? [] : [...($select.buckets ?? []).map((b) => b.alias), ...$select.computedAliases];
 	return paged.map((row) => {
@@ -865,18 +888,19 @@ function exprAccumulatorFactory(e) {
 /**
 * `first` / `last`: the value of `fl.column` on the group's representative
 * row — the least (`first`) or greatest (`last`) row by `rowOrder` (NULL
-* smallest; the primary key is the final key, so the pick is deterministic).
+* smallest unless the key carries a `nulls` placement; the primary key is the final key, so the pick is deterministic).
 */
 function firstLastFactory(fl, rowOrder) {
 	const keys = rowOrder.map((k) => ({
 		read: pathReader(k.column),
-		sign: k.desc ? -1 : 1
+		desc: k.desc,
+		nulls: k.nulls
 	}));
 	const read = pathReader(fl.column);
 	const sign = fl.fn === "first" ? -1 : 1;
 	const compare = (a, b) => {
 		for (const k of keys) {
-			const c = compareLeaves(k.read(a), k.read(b)) * k.sign;
+			const c = compareSortKey(k.read(a), k.read(b), k.desc, k.nulls);
 			if (c !== 0) return c;
 		}
 		return 0;
@@ -1580,14 +1604,28 @@ var MemoryAdapter = class MemoryAdapter extends BaseDbAdapter {
 		return { deletedCount: 1 };
 	}
 	/**
-	* Stable multi-key comparator from `$sort`, with a final tie-break on
-	* {@link pkKey} for a deterministic total order. Returns the input unchanged
+	* Stable multi-key comparator from `$sort`, with the primary-key fields it
+	* leaves out appended in the direction of its LAST key and compared by
+	* value (numbers numerically, `Date`s by instant) — the same tie-breaker
+	* the core appends before a read reaches any adapter (since 0.1.153), so a
+	* direct adapter call orders ties the same way. Returns the input unchanged
 	* (insertion order) when there is no `$sort`. Delegates to the shared pure
-	* {@link sortRows}, injecting {@link pkKey} as the total-order tie-break;
-	* `topK` asks for the head of that order only (`$skip + $limit`).
+	* {@link sortRows}; `topK` asks for the head of that order only
+	* (`$skip + $limit`).
 	*/
-	_sortRows(rows, $sort, topK) {
-		return sortRows(rows, $sort, (r) => this.pkKey(r), topK);
+	_sortRows(rows, $sort, $nulls, topK) {
+		return sortRows(rows, this._withPkTieBreak($sort), void 0, topK, $nulls);
+	}
+	/** `$sort` plus the primary-key fields it leaves out, in its last key's direction. */
+	_withPkTieBreak($sort) {
+		if (!$sort || !hasSort($sort)) return $sort;
+		const keys = Object.keys($sort);
+		const missing = this._physicalPkFields().filter((field) => !(field in $sort));
+		if (missing.length === 0) return $sort;
+		const dir = $sort[keys[keys.length - 1]];
+		const next = { ...$sort };
+		for (const field of missing) next[field] = dir;
+		return next;
 	}
 	/**
 	* Compiles the `$select` projection of one read: each returned row is a
@@ -1615,6 +1653,7 @@ var MemoryAdapter = class MemoryAdapter extends BaseDbAdapter {
 	_readControls(controls) {
 		return {
 			$sort: controls.$sort,
+			$nulls: controls.$nulls,
 			$skip: controls.$skip,
 			$limit: controls.$limit,
 			$select: controls.$select
@@ -1651,9 +1690,9 @@ var MemoryAdapter = class MemoryAdapter extends BaseDbAdapter {
 		return (await own).filter(buildMemoryPredicate(query.filter, sets));
 	}
 	async findOne(query) {
-		const { $sort, $skip, $select } = this._readControls(query.controls ?? {});
+		const { $sort, $nulls, $skip, $select } = this._readControls(query.controls ?? {});
 		const index = $skip ?? 0;
-		const row = (hasSort($sort) ? this._sortRows(await this._filteredRows(query), $sort, index + 1) : await this._filteredRows(query, index + 1))[index];
+		const row = (hasSort($sort) ? this._sortRows(await this._filteredRows(query), $sort, $nulls, index + 1) : await this._filteredRows(query, index + 1))[index];
 		return row ? this._projector($select)(row) : null;
 	}
 	async findMany(query) {
@@ -1671,10 +1710,10 @@ var MemoryAdapter = class MemoryAdapter extends BaseDbAdapter {
 	*/
 	async findManyWithCount(query) {
 		const filtered = await this._filteredRows(query);
-		const { $sort, $skip, $limit, $select } = this._readControls(query.controls ?? {});
+		const { $sort, $nulls, $skip, $limit, $select } = this._readControls(query.controls ?? {});
 		const topK = $limit === void 0 ? void 0 : ($skip ?? 0) + $limit;
 		return {
-			data: paginate(this._sortRows(filtered, $sort, topK), $skip, $limit).map(this._projector($select)),
+			data: paginate(this._sortRows(filtered, $sort, $nulls, topK), $skip, $limit).map(this._projector($select)),
 			count: filtered.length
 		};
 	}
@@ -1708,6 +1747,10 @@ var MemoryAdapter = class MemoryAdapter extends BaseDbAdapter {
 	supportsAggregateExpressions() {
 		return true;
 	}
+	/** NULL placement (`$nulls`, `@db.sort.nulls`) — `sortRows` honours it per key. */
+	supportsNullsPlacement() {
+		return true;
+	}
 	/** Managed views render nothing (non-goal) — both are accepted like `aggregateFns()`. */
 	viewCapabilities() {
 		return ALL_VIEW_CAPABILITIES;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atscript/db-memory",
-  "version": "0.1.152",
+  "version": "0.1.154",
   "description": "In-memory adapter for atscript-db.",
   "keywords": [
     "atscript",
@@ -36,16 +36,16 @@
     "access": "public"
   },
   "devDependencies": {
-    "@atscript/core": "^0.1.102",
-    "@atscript/typescript": "^0.1.102",
-    "@uniqu/core": "^0.1.14",
-    "unplugin-atscript": "^0.1.102"
+    "@atscript/core": "^0.1.103",
+    "@atscript/typescript": "^0.1.103",
+    "@uniqu/core": "^0.1.15",
+    "unplugin-atscript": "^0.1.103"
   },
   "peerDependencies": {
-    "@atscript/core": "^0.1.102",
-    "@atscript/typescript": "^0.1.102",
-    "@uniqu/core": "^0.1.14",
-    "@atscript/db": "^0.1.152"
+    "@atscript/core": "^0.1.103",
+    "@atscript/typescript": "^0.1.103",
+    "@uniqu/core": "^0.1.15",
+    "@atscript/db": "^0.1.154"
   },
   "scripts": {
     "postinstall": "asc -f dts",