@byline/core 3.1.0 → 3.1.1

package/dist/@types/db-types.d.ts

@@ -478,6 +478,13 @@ export interface IDocumentQueries {
      * contexts without widening `getCurrentVersionMetadata`.
      *
      * Returns `null` when the document has no path row (or does not exist).
+     *
+     * Source-locale only: this resolves the single canonical slug, which is the
+     * only path row a document has today. When per-locale paths land (see
+     * docs/DOCUMENT-PATHS.md → "Phase — per-locale paths"), the write-side hook
+     * contexts that consume this must be enriched to carry the locale each path
+     * was derived under (or the full `locale → path` set) — a single canonical
+     * `path` is no longer sufficient for per-localised-URL cache/CDN purges.
      */
     getCurrentPath(params: {
         collection_id: string;

package/dist/config/config.d.ts

@@ -16,5 +16,28 @@ export declare function defineClientConfig(config: ClientConfig): void;
 export declare function defineServerConfig(config: ServerConfig): void;
 export declare function getClientConfig(): ClientConfig;
 export declare function getServerConfig(): ServerConfig;
+/**
+ * Order a set of locale codes by their position in the configured content
+ * locale list. The order source is `i18n.content.locales` — the authoritative,
+ * always-complete configured set — **not** `i18n.content.localeDefinitions`,
+ * which is an optional labels overlay a host may provide for only *some*
+ * codes (ordering off it would drop unlabelled content locales to the end).
+ *
+ * Codes absent from that order fall to the end, ordered alphabetically among
+ * themselves, so the result is always deterministic and never throws. This is
+ * deliberately origin-agnostic: a code that isn't a configured content
+ * locale — an interface-only locale, a stale/removed code, a typo — is
+ * preserved and sorted last rather than dropped or thrown. The function only
+ * sorts; it never filters, so set membership is never changed. The same holds
+ * when no server config is registered (the order is empty → plain a–z sort).
+ *
+ * `availableLocales` (and `_availableVersionLocales`) are *sets* — their
+ * array order carries no meaning — so this makes that order stable and
+ * config-driven at the read source. The payoff is canonical downstream
+ * ordering (display switcher, hreflang `alternates`, sitemap) regardless of
+ * the order a document declared its locales in. Read-time projection only;
+ * nothing persisted changes. See docs/I18N.md.
+ */
+export declare function orderByContentLocale(codes: string[]): string[];
 export declare function defineBylineCore(core: unknown): void;
 export declare function getBylineCoreUnsafe(): unknown;

package/dist/config/config.js

@@ -93,6 +93,43 @@ export function getServerConfig() {
     }
     return serverConfig;
 }
+/**
+ * Order a set of locale codes by their position in the configured content
+ * locale list. The order source is `i18n.content.locales` — the authoritative,
+ * always-complete configured set — **not** `i18n.content.localeDefinitions`,
+ * which is an optional labels overlay a host may provide for only *some*
+ * codes (ordering off it would drop unlabelled content locales to the end).
+ *
+ * Codes absent from that order fall to the end, ordered alphabetically among
+ * themselves, so the result is always deterministic and never throws. This is
+ * deliberately origin-agnostic: a code that isn't a configured content
+ * locale — an interface-only locale, a stale/removed code, a typo — is
+ * preserved and sorted last rather than dropped or thrown. The function only
+ * sorts; it never filters, so set membership is never changed. The same holds
+ * when no server config is registered (the order is empty → plain a–z sort).
+ *
+ * `availableLocales` (and `_availableVersionLocales`) are *sets* — their
+ * array order carries no meaning — so this makes that order stable and
+ * config-driven at the read source. The payoff is canonical downstream
+ * ordering (display switcher, hreflang `alternates`, sitemap) regardless of
+ * the order a document declared its locales in. Read-time projection only;
+ * nothing persisted changes. See docs/I18N.md.
+ */
+export function orderByContentLocale(codes) {
+    const content = getServerConfigInstance()?.i18n?.content;
+    const order = content?.locales ?? content?.localeDefinitions?.map((l) => l.code) ?? [];
+    const index = new Map(order.map((code, i) => [code, i]));
+    return [...codes].sort((a, b) => {
+        const ia = index.get(a) ?? Number.POSITIVE_INFINITY;
+        const ib = index.get(b) ?? Number.POSITIVE_INFINITY;
+        if (ia !== ib)
+            return ia - ib;
+        // Stable, deterministic tiebreak for codes that share a rank — i.e.
+        // multiple unknown codes (both +Infinity), or the no-config fallback
+        // where every code is unknown and this degrades to a plain a–z sort.
+        return a < b ? -1 : a > b ? 1 : 0;
+    });
+}
 // ---------------------------------------------------------------------------
 // BylineCore singleton — the composed runtime returned by `initBylineCore`.
 // Server-side packages that need post-init state (the abilities registry,

package/dist/config/order-by-content-locale.test.node.d.ts

@@ -0,0 +1,8 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+export {};

package/dist/config/order-by-content-locale.test.node.js

@@ -0,0 +1,91 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+import { beforeAll, describe, expect, it } from 'vitest';
+import { defineServerConfig, orderByContentLocale } from './config.js';
+/**
+ * `orderByContentLocale` sorts a set of locale codes by the configured
+ * content-locale order (`i18n.content.locales`), with unknown codes last.
+ * The advertised set's array order is meaningless,
+ * so this is what makes it deterministic and config-driven at the read
+ * source. Content locales here are configured `en, fr, es, de`.
+ */
+describe('orderByContentLocale', () => {
+    beforeAll(() => {
+        // Only `collections` is validated by `defineServerConfig`; the rest of
+        // the shape is irrelevant to this helper, so a minimal cast is enough.
+        defineServerConfig({
+            serverURL: 'http://test.local',
+            i18n: {
+                interface: { defaultLocale: 'en', locales: ['en'] },
+                content: { defaultLocale: 'en', locales: ['en', 'fr', 'es', 'de'] },
+            },
+            collections: [],
+        });
+    });
+    it('orders codes by configured content-locale order', () => {
+        expect(orderByContentLocale(['de', 'en', 'es'])).toEqual(['en', 'es', 'de']);
+    });
+    it('keeps unknown codes present, ordered last', () => {
+        // `xx` is absent from the content config — it survives the read but sorts
+        // after every known code rather than throwing.
+        expect(orderByContentLocale(['de', 'xx', 'en'])).toEqual(['en', 'de', 'xx']);
+    });
+    it('is independent of the input (advertise-declaration) order', () => {
+        const expected = ['en', 'es', 'de'];
+        expect(orderByContentLocale(['es', 'de', 'en'])).toEqual(expected);
+        expect(orderByContentLocale(['de', 'es', 'en'])).toEqual(expected);
+        expect(orderByContentLocale(['en', 'de', 'es'])).toEqual(expected);
+    });
+    it('orders multiple unknown codes deterministically (alphabetical tiebreak)', () => {
+        expect(orderByContentLocale(['zz', 'en', 'aa'])).toEqual(['en', 'aa', 'zz']);
+    });
+    it('does not mutate the input array', () => {
+        const input = ['de', 'en'];
+        orderByContentLocale(input);
+        expect(input).toEqual(['de', 'en']);
+    });
+});
+/**
+ * Robustness around the configured-set boundary (raised by: interface locales
+ * are a *different* set from content locales — see `apps/webapp/byline/locales.ts`
+ * — and `localeDefinitions` may be partial). The order is taken from the
+ * authoritative `content.locales`; anything outside it sorts last but is never
+ * dropped.
+ */
+describe('orderByContentLocale — boundary robustness', () => {
+    beforeAll(() => {
+        defineServerConfig({
+            serverURL: 'http://test.local',
+            i18n: {
+                // Interface set (`en`, `de`) deliberately overlaps content only on `en`
+                // — `de` is interface-only here, NOT a content locale.
+                interface: { defaultLocale: 'en', locales: ['en', 'de'] },
+                content: {
+                    defaultLocale: 'en',
+                    locales: ['en', 'fr', 'es'],
+                    // Partial labels overlay — only `en`/`fr`. `es` is a content locale
+                    // with no label; it must still order correctly (not fall to the end).
+                    localeDefinitions: [
+                        { code: 'en', nativeName: 'English' },
+                        { code: 'fr', nativeName: 'Français' },
+                    ],
+                },
+            },
+            collections: [],
+        });
+    });
+    it('orders by content.locales even when localeDefinitions is partial', () => {
+        // `es` (unlabelled content locale) must keep its content-order slot, not
+        // be treated as unknown.
+        expect(orderByContentLocale(['es', 'en', 'fr'])).toEqual(['en', 'fr', 'es']);
+    });
+    it('sorts an interface-only locale (not in content) last, never dropping it', () => {
+        // `de` is an interface locale but not a content locale — preserved, last.
+        expect(orderByContentLocale(['de', 'en', 'fr'])).toEqual(['en', 'fr', 'de']);
+    });
+});

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 export * from './@types/index.js';
 export { applyBeforeRead, assertActorCanPerform, COLLECTION_ABILITY_VERBS, type CollectionAbilityVerb, collectionAbilityKey, registerCollectionAbilities, } from './auth/index.js';
-export { defineClientConfig, defineServerConfig, getClientConfig, getCollectionAdminConfig, getCollectionDefinition, getServerConfig, } from './config/config.js';
+export { defineClientConfig, defineServerConfig, getClientConfig, getCollectionAdminConfig, getCollectionDefinition, getServerConfig, orderByContentLocale, } from './config/config.js';
 export { resolveRoutes } from './config/routes.js';
 export { validateAdminConfigs } from './config/validate-admin-configs.js';
 export { RESERVED_FIELD_NAMES } from './config/validate-collections.js';

package/dist/index.js

@@ -16,7 +16,7 @@
 // ---------------------------------------------------------------------------
 export * from './@types/index.js';
 export { applyBeforeRead, assertActorCanPerform, COLLECTION_ABILITY_VERBS, collectionAbilityKey, registerCollectionAbilities, } from './auth/index.js';
-export { defineClientConfig, defineServerConfig, getClientConfig, getCollectionAdminConfig, getCollectionDefinition, getServerConfig, } from './config/config.js';
+export { defineClientConfig, defineServerConfig, getClientConfig, getCollectionAdminConfig, getCollectionDefinition, getServerConfig, orderByContentLocale, } from './config/config.js';
 export { resolveRoutes } from './config/routes.js';
 export { validateAdminConfigs } from './config/validate-admin-configs.js';
 export { RESERVED_FIELD_NAMES } from './config/validate-collections.js';

package/package.json

@@ -2,7 +2,7 @@
   "name": "@byline/core",
   "private": false,
   "license": "MPL-2.0",
-  "version": "3.1.0",
+  "version": "3.1.1",
   "engines": {
     "node": ">=20.9.0"
   },
@@ -79,7 +79,7 @@
     "sharp": "^0.34.5",
     "uuid": "^14.0.0",
     "zod": "^4.4.3",
-    "@byline/auth": "3.1.0"
+    "@byline/auth": "3.1.1"
   },
   "devDependencies": {
     "@biomejs/biome": "2.4.15",