@@ -0,0 +1,23 @@
+---
+"@objectstack/metadata": patch
+---
+
+`sortKeys` — a declared `MetadataSaveOptions` field, already honoured by the `json` and `yaml`
+formats — is now honoured by the `typescript` / `javascript` formats too (#19872).
+
+`TypeScriptSerializer` wraps a JSON body in `export const metadata = { … };`. Both its public
+`serialize()` and the package-internal `serializeTypeScriptForMetadataType()` (the one
+`FilesystemLoader.save()` calls for the built-in `typescript` serializer, `save()`'s default
+format) share one `renderModule()` code path, and neither read `options.sortKeys` — so a caller
+saving metadata to the filesystem with `sortKeys: true` got unsorted keys in the default format,
+silently. `javascript` shares the same `TypeScriptSerializer` class and the same path, so it was
+affected too and is fixed the same way.
+
+The body is now sorted with the exact recursive (deep) key sort `JSONSerializer` already applies
+— extracted into one shared, package-internal helper (`sort-object-keys.ts`, not published from
+any `@objectstack/metadata` `exports` entry) so there is one sort implementation, not two.
+`sortKeys` absent or `false` is unchanged: byte-identical output to before this fix, for every
+format, including through `FilesystemLoader.save()`.
+
+No public API changes — `SerializeOptions` already declared `sortKeys`; this closes the gap
+between the declaration and the `typescript`/`javascript` formats' enforcement of it.
@@ -9,6 +9,7 @@
 import type { z } from 'zod';
 import type { MetadataFormat } from '@objectstack/spec/system';
 import type { MetadataSerializer, SerializeOptions } from './serializer-interface.js';
+import { sortObjectKeys } from './sort-object-keys.js';
 
 export class JSONSerializer implements MetadataSerializer {
   serialize<T>(item: T, options?: SerializeOptions): string {
@@ -51,23 +52,14 @@ export class JSONSerializer implements MetadataSerializer {
 
   /**
    * Recursively sort object keys
+   *
+   * #19872: the shared implementation moved to `./sort-object-keys.js`, so
+   * `TypeScriptSerializer` can reuse the exact same sort instead of a second
+   * one — this method is now a thin delegate, kept (rather than inlined at
+   * the call site) so this class's declared shape, private members included,
+   * is unchanged in the package's emitted `.d.ts`.
    */
   private sortObjectKeys(obj: any): any {
-    if (obj === null || typeof obj !== 'object') {
-      return obj;
-    }
-
-    if (Array.isArray(obj)) {
-      return obj.map(item => this.sortObjectKeys(item));
-    }
-
-    const sorted: Record<string, any> = {};
-    const keys = Object.keys(obj).sort();
-
-    for (const key of keys) {
-      sorted[key] = this.sortObjectKeys(obj[key]);
-    }
-
-    return sorted;
+    return sortObjectKeys(obj);
   }
 }
@@ -206,5 +206,96 @@ describe('Serializers', () => {
       const js = new TypeScriptSerializer('javascript');
       expect(js.getExtension()).toBe('.js');
     });
+
+    // #19872: `sortKeys` was declared (`MetadataSaveOptionsSchema`), honoured
+    // by `json`/`yaml`, and silently ignored by `typescript` (the default
+    // format `FilesystemLoader.save()` routes to) — and by `javascript`, the
+    // same class on the same `renderModule()` code path.
+    describe('sortKeys (#19872)', () => {
+      // Deliberately unsorted at BOTH levels, so a top-level-only sort would
+      // pass while a deep one is the only one this can't fake: the nested
+      // `fields` object's own keys are unsorted too.
+      const unsortedObject = {
+        name: 'account',
+        label: 'Account',
+        fields: {
+          zeta_field: { type: 'text', label: 'Zeta' },
+          alpha_field: { type: 'text', label: 'Alpha' },
+        },
+      };
+      const jsonSerializer = new JSONSerializer();
+
+      it('the public serialize() sorts the JSON body deep, byte-identical to JSONSerializer\'s own sort — reused, not reimplemented', () => {
+        const sortedBody = jsonSerializer.serialize(unsortedObject, { sortKeys: true });
+        expect(serializer.serialize(unsortedObject, { sortKeys: true })).toBe(
+          `export const metadata = ${sortedBody};\n\nexport default metadata;\n`
+        );
+      });
+
+      it('serializeTypeScriptForMetadataType() sorts the JSON body deep too, annotated', () => {
+        const sortedBody = jsonSerializer.serialize(unsortedObject, { sortKeys: true });
+        expect(serializeTypeScriptForMetadataType(unsortedObject, 'object', { sortKeys: true })).toBe(
+          `import type { ServiceObject } from '@objectstack/spec/data';\n\n` +
+          `export const metadata: ServiceObject = ${sortedBody};\n\n` +
+          `export default metadata;\n`
+        );
+      });
+
+      it('the javascript format honours it too — A1: same TypeScriptSerializer class, same renderModule() path', () => {
+        const sortedBody = jsonSerializer.serialize(unsortedObject, { sortKeys: true });
+        expect(new TypeScriptSerializer('javascript').serialize(unsortedObject, { sortKeys: true })).toBe(
+          `export const metadata = ${sortedBody};\n\nexport default metadata;\n`
+        );
+      });
+
+      it('sortKeys absent or false: byte-identical to origin/main, through both serialize() and serializeTypeScriptForMetadataType()', () => {
+        expect(serializer.serialize(object)).toBe(plain(object));
+        expect(serializer.serialize(object, { sortKeys: false })).toBe(plain(object));
+        expect(serializeTypeScriptForMetadataType(object, 'object')).toBe(annotatedObject);
+        expect(serializeTypeScriptForMetadataType(object, 'object', { sortKeys: false })).toBe(annotatedObject);
+      });
+
+      it('round-trips a view and an object with sortKeys: true, through both paths', () => {
+        for (const [metadataType, item] of [['view', view], ['object', object]] as const) {
+          expect(
+            serializer.deserialize(serializeTypeScriptForMetadataType(item, metadataType, { sortKeys: true }))
+          ).toEqual(item);
+          expect(serializer.deserialize(serializer.serialize(item, { sortKeys: true }))).toEqual(item);
+        }
+      });
+
+      it('FilesystemLoader.save() honours sortKeys: true for object, through the loader path (A3)', async () => {
+        const rootDir = await fs.mkdtemp(path.join(os.tmpdir(), 'objectstack-ts-serializer-sortkeys-on-'));
+        try {
+          const manager = new NodeMetadataManager({ rootDir, watch: false });
+          await manager.save('object', 'account', unsortedObject, { sortKeys: true });
+          const objectFile = await fs.readFile(path.join(rootDir, 'object', 'account.ts'), 'utf-8');
+          const sortedBody = jsonSerializer.serialize(unsortedObject, { sortKeys: true });
+          expect(objectFile).toBe(
+            `import type { ServiceObject } from '@objectstack/spec/data';\n\n` +
+            `export const metadata: ServiceObject = ${sortedBody};\n\n` +
+            `export default metadata;\n`
+          );
+        } finally {
+          await fs.rm(rootDir, { recursive: true, force: true });
+        }
+      });
+
+      it('FilesystemLoader.save() with sortKeys absent or explicitly false is byte-identical to origin/main, for object, through the loader path (A3)', async () => {
+        const rootDir = await fs.mkdtemp(path.join(os.tmpdir(), 'objectstack-ts-serializer-sortkeys-off-'));
+        try {
+          const manager = new NodeMetadataManager({ rootDir, watch: false });
+          await manager.save('object', 'account', object);
+          const noOptionFile = await fs.readFile(path.join(rootDir, 'object', 'account.ts'), 'utf-8');
+          expect(noOptionFile).toBe(annotatedObject);
+
+          await manager.save('object', 'account2', object, { sortKeys: false });
+          const explicitFalseFile = await fs.readFile(path.join(rootDir, 'object', 'account2.ts'), 'utf-8');
+          expect(explicitFalseFile).toBe(annotatedObject);
+        } finally {
+          await fs.rm(rootDir, { recursive: true, force: true });
+        }
+      });
+    });
   });
 });
@@ -0,0 +1,30 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * The ONE `sortKeys` sort every serializer that honours it as a plain-JSON
+ * key sort (not a format-native one, like `js-yaml`'s own `sortKeys` option)
+ * shares — `JSONSerializer` and the `typescript`/`javascript` module body
+ * `TypeScriptSerializer` wraps. Recursive: every nested object's keys sort
+ * too, not just the top level. Arrays keep their element order; only object
+ * keys sort. Not published from any `@objectstack/metadata` `exports` entry
+ * — an internal helper two in-package serializers share, never a second
+ * implementation of the same sort.
+ */
+export function sortObjectKeys(obj: any): any {
+  if (obj === null || typeof obj !== 'object') {
+    return obj;
+  }
+
+  if (Array.isArray(obj)) {
+    return obj.map(item => sortObjectKeys(item));
+  }
+
+  const sorted: Record<string, any> = {};
+  const keys = Object.keys(obj).sort();
+
+  for (const key of keys) {
+    sorted[key] = sortObjectKeys(obj[key]);
+  }
+
+  return sorted;
+}
@@ -9,6 +9,7 @@
 import type { z } from 'zod';
 import type { MetadataFormat } from '@objectstack/spec/system';
 import type { MetadataSerializer, SerializeOptions } from './serializer-interface.js';
+import { sortObjectKeys } from './sort-object-keys.js';
 
 /**
  * The spec type a `typescript`-format file's `metadata` constant is annotated
@@ -79,9 +80,13 @@ function renderModule(
   options: SerializeOptions | undefined,
   annotation: readonly [typeName: string, subpath: string] | undefined,
 ): string {
-  const { prettify = true, indent = 2 } = options || {};
+  const { prettify = true, indent = 2, sortKeys = false } = options || {};
 
-  const jsonStr = JSON.stringify(item, null, prettify ? indent : 0);
+  // Same sort `JSONSerializer` applies (recursive, ⛔ not a second
+  // implementation) — the JSON body this format wraps is otherwise the one
+  // place `sortKeys: true` silently produced unsorted keys (#19872).
+  const body = sortKeys ? sortObjectKeys(item) : item;
+  const jsonStr = JSON.stringify(body, null, prettify ? indent : 0);
 
   if (annotation) {
     const [typeName, subpath] = annotation;