@object-ui/data-objectstack 16.1.0 → 17.2.0

package/src/metadata-client.ts

@@ -75,7 +75,21 @@ export interface MetadataDraftHeader {
   updatedBy: string | null;
 }
 
-export interface MetadataSaveOptions {
+/**
+ * Options for {@link MetadataClient.save} — a WRITE OVER HTTP to
+ * `/api/v1/meta/:type/:name`.
+ *
+ * NOT the spec's `MetadataSaveOptions` (`@objectstack/spec/system` and
+ * `/kernel`), whose name this interface wore until objectui#3160
+ * (objectstack#4115 ledger batch 6). Both spec copies describe writing a
+ * metadata item to a FILE — `format: json|yaml|ts`, `path`, `indent`,
+ * `prettify`, `sortKeys`, `backup`, `atomic`, `loader`. Not one of those keys
+ * exists here, and not one of these exists there: this is the REST client's
+ * request envelope — optimistic concurrency (`ifMatch` → `If-Match`), actor
+ * attribution, the destructive-change override, the ADR-0033 draft/publish
+ * mode, and the owning package. Same words, different layer.
+ */
+export interface MetadataClientSaveOptions {
   /**
    * Optimistic concurrency token (the `checksum` returned by the last
    * read). When present, sent as the `If-Match` header so concurrent
@@ -122,7 +136,7 @@ export interface MetadataGetOptions {
   packageId?: string;
 }
 
-export interface MetadataDeleteOptions extends MetadataSaveOptions {
+export interface MetadataDeleteOptions extends MetadataClientSaveOptions {
   /**
    * Target state. `'draft'` discards the pending draft (keeps the
    * published overlay intact). Omit to reset the active overlay back
@@ -527,7 +541,7 @@ export class MetadataClient {
     type: string,
     name: string,
     item: unknown,
-    options: MetadataSaveOptions = {},
+    options: MetadataClientSaveOptions = {},
   ): Promise<T> {
     if (!name || !String(name).trim()) {
       // The `PUT /meta/:type/:name` route rejects a missing `:name` segment

package/src/onMutation.test.ts

@@ -23,7 +23,7 @@ import {
   clearSharedDiscoveryCache,
   readTransactionalBatchCapability,
 } from './index';
-import type { MutationEvent } from '@object-ui/types';
+import type { DataSourceMutationEvent } from '@object-ui/types';
 
 function makeDS(stub: Record<string, any>) {
   const ds: any = new ObjectStackAdapter({
@@ -49,8 +49,8 @@ describe('ObjectStackAdapter.onMutation', () => {
       .mockResolvedValue({ record: { id: 'r1', account: 'acc-1' } });
     const ds = makeDS({ update });
 
-    const events: MutationEvent[] = [];
-    const unsub = ds.onMutation((e: MutationEvent) => events.push(e));
+    const events: DataSourceMutationEvent[] = [];
+    const unsub = ds.onMutation((e: DataSourceMutationEvent) => events.push(e));
 
     await ds.update('showcase_project', 'r1', { account: 'acc-1' });
 
@@ -67,8 +67,8 @@ describe('ObjectStackAdapter.onMutation', () => {
   it('emits a create event with the new record', async () => {
     const create = vi.fn().mockResolvedValue({ record: { id: 'new', name: 'X' } });
     const ds = makeDS({ create });
-    const events: MutationEvent[] = [];
-    ds.onMutation((e: MutationEvent) => events.push(e));
+    const events: DataSourceMutationEvent[] = [];
+    ds.onMutation((e: DataSourceMutationEvent) => events.push(e));
 
     await ds.create('showcase_project', { name: 'X' });
 
@@ -83,8 +83,8 @@ describe('ObjectStackAdapter.onMutation', () => {
       .mockResolvedValueOnce({ deleted: true })
       .mockResolvedValueOnce({ deleted: false });
     const ds = makeDS({ delete: del });
-    const events: MutationEvent[] = [];
-    ds.onMutation((e: MutationEvent) => events.push(e));
+    const events: DataSourceMutationEvent[] = [];
+    ds.onMutation((e: DataSourceMutationEvent) => events.push(e));
 
     await ds.delete('showcase_project', 'r1');
     await ds.delete('showcase_project', 'r2');
@@ -97,8 +97,8 @@ describe('ObjectStackAdapter.onMutation', () => {
   it('emits a single bulk event per bulkUpdate call (not per id)', async () => {
     const updateMany = vi.fn().mockResolvedValue({ succeeded: 3, failed: 0, results: [] });
     const ds = makeDS({ updateMany });
-    const events: MutationEvent[] = [];
-    ds.onMutation((e: MutationEvent) => events.push(e));
+    const events: DataSourceMutationEvent[] = [];
+    ds.onMutation((e: DataSourceMutationEvent) => events.push(e));
 
     await ds.bulkUpdate('showcase_project', ['a', 'b', 'c'], { archived: true });
 
@@ -108,8 +108,8 @@ describe('ObjectStackAdapter.onMutation', () => {
   it('does not emit when a bulk operation affected zero rows', async () => {
     const updateMany = vi.fn().mockResolvedValue({ succeeded: 0, failed: 0, results: [] });
     const ds = makeDS({ updateMany });
-    const events: MutationEvent[] = [];
-    ds.onMutation((e: MutationEvent) => events.push(e));
+    const events: DataSourceMutationEvent[] = [];
+    ds.onMutation((e: DataSourceMutationEvent) => events.push(e));
 
     await ds.bulkUpdate('showcase_project', ['a'], { archived: true });
 
@@ -160,8 +160,8 @@ describe('ObjectStackAdapter.batchTransaction mutation events', () => {
         { status: 200, headers: { 'Content-Type': 'application/json' } },
       ),
     );
-    const events: MutationEvent[] = [];
-    ds.onMutation((e: MutationEvent) => events.push(e));
+    const events: DataSourceMutationEvent[] = [];
+    ds.onMutation((e: DataSourceMutationEvent) => events.push(e));
 
     await ds.batchTransaction([
       { object: 'ehr_task_version', action: 'create', data: { name: 'Task version A' } },
@@ -183,8 +183,8 @@ describe('ObjectStackAdapter.batchTransaction mutation events', () => {
         { status: 200, headers: { 'Content-Type': 'application/json' } },
       ),
     );
-    const events: MutationEvent[] = [];
-    ds.onMutation((e: MutationEvent) => events.push(e));
+    const events: DataSourceMutationEvent[] = [];
+    ds.onMutation((e: DataSourceMutationEvent) => events.push(e));
 
     await ds.batchTransaction([
       { object: 'ehr_task_version', action: 'update', id: 'p1', data: { name: 'Renamed' } },
@@ -208,8 +208,8 @@ describe('ObjectStackAdapter.batchTransaction mutation events', () => {
         headers: { 'Content-Type': 'application/json' },
       }),
     );
-    const events: MutationEvent[] = [];
-    ds.onMutation((e: MutationEvent) => events.push(e));
+    const events: DataSourceMutationEvent[] = [];
+    ds.onMutation((e: DataSourceMutationEvent) => events.push(e));
 
     await ds.batchTransaction([{ object: 'ehr_task_version', data: { name: 'X' } }]);
 
@@ -225,8 +225,8 @@ describe('ObjectStackAdapter.batchTransaction mutation events', () => {
         headers: { 'Content-Type': 'application/json' },
       }),
     );
-    const events: MutationEvent[] = [];
-    ds.onMutation((e: MutationEvent) => events.push(e));
+    const events: DataSourceMutationEvent[] = [];
+    ds.onMutation((e: DataSourceMutationEvent) => events.push(e));
 
     await expect(
       ds.batchTransaction([{ object: 'ehr_task_version', action: 'create', data: {} }]),
@@ -265,8 +265,8 @@ describe('ObjectStackAdapter.batchTransaction fallback (no server atomicity)', (
     const create = vi.fn(async (_o: string, d: any) => ({ record: { id: 'p1', ...d } }));
     const { ds, batchTransaction } = makeFallbackDS({ batchStatus: 404, clientData: { create } });
     const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
-    const events: MutationEvent[] = [];
-    ds.onMutation((e: MutationEvent) => events.push(e));
+    const events: DataSourceMutationEvent[] = [];
+    ds.onMutation((e: DataSourceMutationEvent) => events.push(e));
 
     const res = await ds.batchTransaction([{ object: 'proj', action: 'create', data: { name: 'A' } }]);
 
@@ -311,8 +311,8 @@ describe('ObjectStackAdapter.batchTransaction fallback (no server atomicity)', (
     ds.connected = true;
     ds.connectionState = 'connected';
     ds.client = { data: { batchTransaction: sdkBatch } };
-    const events: MutationEvent[] = [];
-    ds.onMutation((e: MutationEvent) => events.push(e));
+    const events: DataSourceMutationEvent[] = [];
+    ds.onMutation((e: DataSourceMutationEvent) => events.push(e));
 
     const res = await ds.batchTransaction([{ object: 'proj', action: 'create', data: { name: 'A' } }]);
 
@@ -335,8 +335,8 @@ describe('ObjectStackAdapter.bulk mutation events', () => {
   it('emits a single create event per bulk create call', async () => {
     const createMany = vi.fn().mockResolvedValue([{ id: 'c1' }, { id: 'c2' }]);
     const ds = makeDS({ createMany });
-    const events: MutationEvent[] = [];
-    ds.onMutation((e: MutationEvent) => events.push(e));
+    const events: DataSourceMutationEvent[] = [];
+    ds.onMutation((e: DataSourceMutationEvent) => events.push(e));
 
     await ds.bulk('ehr_task_check_item', 'create', [{ label: 'a' }, { label: 'b' }]);
 
@@ -346,8 +346,8 @@ describe('ObjectStackAdapter.bulk mutation events', () => {
   it('does not emit when a bulk create returned zero records', async () => {
     const createMany = vi.fn().mockResolvedValue([]);
     const ds = makeDS({ createMany });
-    const events: MutationEvent[] = [];
-    ds.onMutation((e: MutationEvent) => events.push(e));
+    const events: DataSourceMutationEvent[] = [];
+    ds.onMutation((e: DataSourceMutationEvent) => events.push(e));
 
     await ds.bulk('ehr_task_check_item', 'create', [{ label: 'a' }]);
 
@@ -357,8 +357,8 @@ describe('ObjectStackAdapter.bulk mutation events', () => {
   it('emits a single delete event per bulk delete call', async () => {
     const deleteMany = vi.fn().mockResolvedValue(undefined);
     const ds = makeDS({ deleteMany });
-    const events: MutationEvent[] = [];
-    ds.onMutation((e: MutationEvent) => events.push(e));
+    const events: DataSourceMutationEvent[] = [];
+    ds.onMutation((e: DataSourceMutationEvent) => events.push(e));
 
     await ds.bulk('ehr_task_check_item', 'delete', [{ id: 'c1' }, { id: 'c2' }] as any);
 
@@ -368,8 +368,8 @@ describe('ObjectStackAdapter.bulk mutation events', () => {
   it('emits a single update event per bulk update call', async () => {
     const updateMany = vi.fn().mockResolvedValue([{ id: 'c1' }]);
     const ds = makeDS({ updateMany });
-    const events: MutationEvent[] = [];
-    ds.onMutation((e: MutationEvent) => events.push(e));
+    const events: DataSourceMutationEvent[] = [];
+    ds.onMutation((e: DataSourceMutationEvent) => events.push(e));
 
     await ds.bulk('ehr_task_check_item', 'update', [{ id: 'c1', label: 'x' }] as any);
 
@@ -379,8 +379,8 @@ describe('ObjectStackAdapter.bulk mutation events', () => {
   it('bulk create failure emits nothing', async () => {
     const createMany = vi.fn().mockRejectedValue(new Error('boom'));
     const ds = makeDS({ createMany });
-    const events: MutationEvent[] = [];
-    ds.onMutation((e: MutationEvent) => events.push(e));
+    const events: DataSourceMutationEvent[] = [];
+    ds.onMutation((e: DataSourceMutationEvent) => events.push(e));
 
     await expect(ds.bulk('ehr_task_check_item', 'create', [{ label: 'a' }])).rejects.toThrow();
 
@@ -481,8 +481,8 @@ describe('ObjectStackAdapter.batchTransaction capability gate (#2693 / framework
       batchStatus: 200,
       batchBody: { results: [{ id: 'p1', name: 'A' }, { id: 'c1', proj: 'p1' }] },
     });
-    const events: MutationEvent[] = [];
-    ds.onMutation((e: MutationEvent) => events.push(e));
+    const events: DataSourceMutationEvent[] = [];
+    ds.onMutation((e: DataSourceMutationEvent) => events.push(e));
 
     const res = await ds.batchTransaction([
       { object: 'proj', action: 'create', data: { name: 'A' } },

package/src/onWriteWarning.test.ts

@@ -0,0 +1,172 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+/**
+ * ObjectStackAdapter must surface the framework's write-observability channel
+ * (#3431/#3455): when a create/update response carries `droppedFields` — fields
+ * the backend LEGALLY stripped (read-only / locked-by-state) — the adapter emits
+ * a WriteWarningEvent so the app shell can toast the user instead of letting the
+ * dropped value vanish silently. The write itself still succeeded.
+ */
+import { describe, it, expect, vi } from 'vitest';
+import { ObjectStackAdapter } from './index';
+import type { WriteWarningEvent } from './index';
+
+function makeDS(stub: Record<string, any>) {
+  const ds: any = new ObjectStackAdapter({
+    baseUrl: 'http://test.local',
+    fetch: vi.fn(async () =>
+      new Response(JSON.stringify({ success: true, data: { capabilities: {}, routes: {} } }), {
+        status: 200,
+        headers: { 'Content-Type': 'application/json' },
+      }),
+    ),
+  });
+  ds.connected = true;
+  ds.connectionState = 'connected';
+  ds.client = { data: stub };
+  return ds;
+}
+
+const ONE_DROP = [{ object: 'approval_case', fields: ['approval_status'], reason: 'readonly' }];
+
+describe('ObjectStackAdapter.onWriteWarning', () => {
+  it('emits a create write-warning carrying the dropped fields and the new id', async () => {
+    const create = vi.fn().mockResolvedValue({ record: { id: 'r1', title: 'A' }, droppedFields: ONE_DROP });
+    const ds = makeDS({ create });
+    const events: WriteWarningEvent[] = [];
+    ds.onWriteWarning((e: WriteWarningEvent) => events.push(e));
+
+    const rec = await ds.create('approval_case', { title: 'A', approval_status: 'approved' });
+
+    // The write still returns the plain record (unchanged behaviour).
+    expect(rec).toEqual({ id: 'r1', title: 'A' });
+    expect(events).toEqual([
+      { operation: 'create', resource: 'approval_case', id: 'r1', droppedFields: ONE_DROP },
+    ]);
+  });
+
+  it('emits an update write-warning carrying the target id', async () => {
+    const update = vi.fn().mockResolvedValue({ record: { id: 'r1' }, droppedFields: ONE_DROP });
+    const ds = makeDS({ update });
+    const events: WriteWarningEvent[] = [];
+    ds.onWriteWarning((e: WriteWarningEvent) => events.push(e));
+
+    await ds.update('approval_case', 'r1', { approval_status: 'approved' });
+
+    expect(events).toEqual([
+      { operation: 'update', resource: 'approval_case', id: 'r1', droppedFields: ONE_DROP },
+    ]);
+  });
+
+  it('does NOT emit when the response carries no droppedFields (the common case)', async () => {
+    const create = vi.fn().mockResolvedValue({ record: { id: 'r1', title: 'A' } });
+    const update = vi.fn().mockResolvedValue({ record: { id: 'r1' } });
+    const ds = makeDS({ create, update });
+    const events: WriteWarningEvent[] = [];
+    ds.onWriteWarning((e: WriteWarningEvent) => events.push(e));
+
+    await ds.create('approval_case', { title: 'A' });
+    await ds.update('approval_case', 'r1', { title: 'B' });
+
+    expect(events).toEqual([]);
+  });
+
+  it('does NOT emit for an empty or malformed droppedFields payload', async () => {
+    const create = vi
+      .fn()
+      .mockResolvedValueOnce({ record: { id: 'r1' }, droppedFields: [] })
+      .mockResolvedValueOnce({ record: { id: 'r2' }, droppedFields: 'nope' })
+      .mockResolvedValueOnce({ record: { id: 'r3' }, droppedFields: [{ object: 'x', fields: [] }] });
+    const ds = makeDS({ create });
+    const events: WriteWarningEvent[] = [];
+    ds.onWriteWarning((e: WriteWarningEvent) => events.push(e));
+
+    await ds.create('x', {});
+    await ds.create('x', {});
+    await ds.create('x', {}); // event present but its fields[] is empty → filtered out
+
+    expect(events).toEqual([]);
+  });
+
+  // ── cross-object batch (framework #3794) ─────────────────────────────────
+  //
+  // `batchTransaction` is the console record form's save path for a
+  // master-detail record, so this is where a `readonlyWhen` strip actually
+  // reaches a user editing a form. Its response tags each event with the index
+  // of the operation that produced it.
+
+  it('emits a write-warning per event on a cross-object batch, resolving the op', async () => {
+    const batchTransaction = vi.fn().mockResolvedValue({
+      results: [{ id: 'acc1' }, { id: 'inv1' }],
+      droppedFields: [
+        { object: 'invoice', fields: ['tax_rate'], reason: 'readonly_when', index: 1 },
+      ],
+    });
+    const ds = makeDS({ batchTransaction });
+    ds.atomicBatchCapability = true;
+    const events: WriteWarningEvent[] = [];
+    ds.onWriteWarning((e: WriteWarningEvent) => events.push(e));
+
+    await ds.batchTransaction([
+      { object: 'account', action: 'create', data: { name: 'Acme' } },
+      { object: 'invoice', action: 'update', id: 'inv1', data: { status: 'paid', tax_rate: 9 } },
+    ]);
+
+    expect(events).toEqual([
+      {
+        operation: 'update',
+        resource: 'invoice',
+        id: 'inv1',
+        droppedFields: [{ object: 'invoice', fields: ['tax_rate'], reason: 'readonly_when' }],
+      },
+    ]);
+  });
+
+  it('does NOT emit for a clean batch or a malformed droppedFields list', async () => {
+    const batchTransaction = vi
+      .fn()
+      .mockResolvedValueOnce({ results: [{ id: 'a' }] })
+      .mockResolvedValueOnce({ results: [{ id: 'a' }], droppedFields: [{ object: 'x', fields: [], index: 0 }] });
+    const ds = makeDS({ batchTransaction });
+    ds.atomicBatchCapability = true;
+    const events: WriteWarningEvent[] = [];
+    ds.onWriteWarning((e: WriteWarningEvent) => events.push(e));
+
+    await ds.batchTransaction([{ object: 'x', action: 'create', data: {} }]);
+    await ds.batchTransaction([{ object: 'x', action: 'create', data: {} }]);
+
+    expect(events).toEqual([]);
+  });
+
+  it('stops delivering after unsubscribe', async () => {
+    const create = vi.fn().mockResolvedValue({ record: { id: 'r1' }, droppedFields: ONE_DROP });
+    const ds = makeDS({ create });
+    const events: WriteWarningEvent[] = [];
+    const unsub = ds.onWriteWarning((e: WriteWarningEvent) => events.push(e));
+
+    await ds.create('approval_case', {});
+    unsub();
+    await ds.create('approval_case', {});
+
+    expect(events).toHaveLength(1);
+  });
+
+  it('isolates a throwing listener so the write still resolves and other listeners fire', async () => {
+    const update = vi.fn().mockResolvedValue({ record: { id: 'r1' }, droppedFields: ONE_DROP });
+    const ds = makeDS({ update });
+    const good = vi.fn();
+    ds.onWriteWarning(() => { throw new Error('boom'); });
+    ds.onWriteWarning(good);
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+
+    await expect(ds.update('approval_case', 'r1', { approval_status: 'x' })).resolves.toBeTruthy();
+    expect(good).toHaveBeenCalledTimes(1);
+    warn.mockRestore();
+  });
+});

package/src/orderby-serialization.test.ts

@@ -0,0 +1,115 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+/**
+ * Every shape `QueryParams['$orderby']` declares reaches the wire as a sort.
+ *
+ * `find()` has TWO routes to the server — a plain read goes through
+ * `convertQueryParams` and the client SDK, a read with `$expand`/`$search`
+ * through `rawFindWithPopulate` — and each used to carry its own copy of the
+ * "which `$orderby` shape is this?" fold. Both copies handled three of the four
+ * declared shapes; both missed the bare string, and missed it the same
+ * spectacular way: the string fell into the `Record<field, direction>` branch,
+ * where `Object.entries('name asc')` enumerates character indices and the
+ * request went out as `sort=0,1,2,3,4,5,6,7`.
+ *
+ * That is not a cosmetic mistranslation. Since objectstack#4226 the server
+ * refuses a sort it cannot read (`400 INVALID_SORT`) rather than dropping it,
+ * so the whole list fails to load — and `"${field} ${order}"` is exactly what a
+ * standalone `ObjectGrid` builds from its view metadata's `sort`.
+ *
+ * Both routes are asserted for every shape, because "the two routes agree" is
+ * the property that was actually missing; one serializer now backs both.
+ */
+
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { ObjectStackAdapter, clearSharedDiscoveryCache, serializeOrderBy } from './index';
+
+function makeAdapter() {
+  const calls: string[] = [];
+  const fetchImpl = vi.fn(async (url: any) => {
+    const u = String(url);
+    calls.push(u);
+    if (u.includes('/api/v1/discovery')) {
+      return {
+        ok: true, status: 200, statusText: 'OK',
+        json: async () => ({ success: true, data: { version: 'v1', routes: {} } }),
+      } as any;
+    }
+    return {
+      ok: true, status: 200, statusText: 'OK',
+      json: async () => ({ success: true, data: { object: 'account', records: [], total: 0 } }),
+    } as any;
+  });
+  const adapter = new ObjectStackAdapter({
+    baseUrl: 'http://localhost:3000', token: 't', autoReconnect: false, fetch: fetchImpl as any,
+  });
+  return { adapter, calls };
+}
+
+/** The `sort=` this `$orderby` produced on the wire, or `undefined` if none was sent. */
+async function sortOnWire($orderby: unknown, route: 'plain' | 'expand'): Promise<string | undefined> {
+  const { adapter, calls } = makeAdapter();
+  await adapter.find('account', {
+    $orderby,
+    ...(route === 'expand' ? { $expand: ['owner'] } : {}),
+  } as any);
+  const dataCall = calls.filter((u) => u.includes('/data/account')).pop();
+  const raw = dataCall ? new URL(dataCall).searchParams.get('sort') : null;
+  return raw === null ? undefined : raw;
+}
+
+/** Run one input down both `find()` routes and assert they agree. */
+function bothRoutes(name: string, $orderby: unknown, expected: string | undefined) {
+  for (const route of ['plain', 'expand'] as const) {
+    it(`${name} (${route} route)`, async () => {
+      expect(await sortOnWire($orderby, route)).toBe(expected);
+    });
+  }
+}
+
+describe('$orderby reaches the wire for every declared shape', () => {
+  beforeEach(() => clearSharedDiscoveryCache());
+
+  // The regression: ObjectGrid's own `"${field} ${order}"`.
+  bothRoutes('a bare "field order" string', 'name asc', 'name asc');
+  bothRoutes('a bare string with a descending key', 'created_at desc', 'created_at desc');
+  bothRoutes('a bare string already in `-field` shorthand', '-created_at', '-created_at');
+  bothRoutes('a bare multi-key string', 'status asc,-created_at', 'status asc,-created_at');
+
+  bothRoutes('a SortNode[]', [{ field: 'name', order: 'asc' }], 'name');
+  bothRoutes(
+    'a SortNode[] with a descending key',
+    [{ field: 'status', order: 'asc' }, { field: 'created_at', order: 'desc' }],
+    'status,-created_at',
+  );
+  bothRoutes('a string[]', ['name', '-age'], 'name,-age');
+  bothRoutes('a Record<field, direction>', { name: 'asc', age: 'desc' }, 'name,-age');
+
+  bothRoutes('no sort at all', undefined, undefined);
+  bothRoutes('an empty array', [], undefined);
+  bothRoutes('an empty object', {}, undefined);
+  bothRoutes('a whitespace-only string', '   ', undefined);
+});
+
+describe('serializeOrderBy', () => {
+  it('never enumerates a string as an object — the defect this replaced', () => {
+    // `Object.entries('name asc')` → [['0','n'],['1','a'],…]. The old fold
+    // reached that branch for every string input.
+    expect(serializeOrderBy('name asc')).toBe('name asc');
+    expect(serializeOrderBy('name asc')).not.toMatch(/^0,1,2/);
+  });
+
+  it('reads `order` case-insensitively', () => {
+    expect(serializeOrderBy([{ field: 'name', order: 'DESC' as any }])).toBe('-name');
+  });
+
+  it('defaults a missing direction to ascending', () => {
+    expect(serializeOrderBy([{ field: 'name' }])).toBe('name');
+  });
+});

package/src/queryDataset.test.ts

@@ -7,7 +7,11 @@
  */
 
 import { describe, it, expect, beforeEach, vi } from 'vitest';
-import { ObjectStackAdapter, clearSharedDiscoveryCache } from './index';
+import {
+  ObjectStackAdapter,
+  clearSharedDiscoveryCache,
+  isAnalyticsNotInstalledError,
+} from './index';
 
 /** A fetch mock that answers discovery + records the dataset-query POST. */
 function makeFetch(datasetResponse: { ok: boolean; status?: number; body: unknown }) {
@@ -80,4 +84,49 @@ describe('ObjectStackAdapter.queryDataset', () => {
     const adapter = new ObjectStackAdapter({ baseUrl: 'http://localhost:3000', autoReconnect: false, fetch: fetchImpl as any });
     await expect(adapter.queryDataset(inlineDataset as any, selection)).rejects.toThrow(/relationship not declared/);
   });
+
+  // framework#3891 retired the degraded in-kernel analytics fallback, so a
+  // deployment without @objectstack/service-analytics answers 501 (REST route
+  // present, no service) or 404 (framework#4019 stopped mounting the routes).
+  // Neither is an authoring mistake — the caller gets a typed, readable error
+  // instead of `Dataset query failed: 501 Not Implemented — …`.
+  describe('analytics capability absent', () => {
+    it('maps 501 NOT_IMPLEMENTED to a readable ANALYTICS_NOT_INSTALLED error', async () => {
+      const { fetchImpl } = makeFetch({
+        ok: false,
+        status: 501,
+        body: {
+          code: 'NOT_IMPLEMENTED',
+          message: 'Analytics dataset query is not available on this deployment (no analytics service with queryDataset).',
+        },
+      });
+      const adapter = new ObjectStackAdapter({ baseUrl: 'http://localhost:3000', autoReconnect: false, fetch: fetchImpl as any });
+
+      const err = await adapter.queryDataset(inlineDataset as any, selection).catch((e) => e);
+
+      expect(isAnalyticsNotInstalledError(err)).toBe(true);
+      expect(err.code).toBe('ANALYTICS_NOT_INSTALLED');
+      expect(err.message).toContain('Analytics capability is not installed');
+      expect(err.message).toContain('@objectstack/service-analytics');
+    });
+
+    it('maps a 404 (routes not mounted) the same way', async () => {
+      const { fetchImpl } = makeFetch({ ok: false, status: 404, body: { error: 'Not found' } });
+      const adapter = new ObjectStackAdapter({ baseUrl: 'http://localhost:3000', autoReconnect: false, fetch: fetchImpl as any });
+
+      const err = await adapter.queryDataset(inlineDataset as any, selection).catch((e) => e);
+
+      expect(isAnalyticsNotInstalledError(err)).toBe(true);
+    });
+
+    it('leaves a real compile error alone (it is NOT a missing capability)', async () => {
+      const { fetchImpl } = makeFetch({ ok: false, status: 400, body: { message: 'relationship not declared in include' } });
+      const adapter = new ObjectStackAdapter({ baseUrl: 'http://localhost:3000', autoReconnect: false, fetch: fetchImpl as any });
+
+      const err = await adapter.queryDataset(inlineDataset as any, selection).catch((e) => e);
+
+      expect(isAnalyticsNotInstalledError(err)).toBe(false);
+      expect(String(err.message)).toContain('relationship not declared');
+    });
+  });
 });