@objectstack/metadata 17.1.0 → 17.3.0

package/dist/node.d.cts

@@ -1,5 +1,5 @@
-import { MetadataManager, MetadataManagerOptions, MetadataLoader, MetadataSerializer } from './index.cjs';
-export { DatabaseLoader, DatabaseLoaderOptions, HistoryCleanupManager, JSONSerializer, MemoryLoader, MetadataPlugin, Migration, RemoteLoader, SerializeOptions, TypeScriptSerializer, WatchCallback, YAMLSerializer, calculateChecksum, generateDiffSummary, generateSimpleDiff } from './index.cjs';
+import { MetadataManager, MetadataManagerOptions, MetadataLoader, MetadataSerializer, MetadataKeyedItem } from './index.cjs';
+export { DatabaseLoader, DatabaseLoaderOptions, HistoryCleanupManager, JSONSerializer, MemoryLoader, MetadataPlugin, Migration, RemoteLoader, SerializeOptions, TypeScriptSerializer, WatchCallback, YAMLSerializer, calculateChecksum, deriveViewContainerObject, generateDiffSummary, generateSimpleDiff } from './index.cjs';
 export { HistoryOptions, MetaRef, MetadataEvent, MetadataItem, MetadataItemHeader, MetadataRepository, SysMetadataHistoryObject, SysMetadataObject, WatchFilter } from '@objectstack/metadata-core';
 import { MetadataLoaderContract, MetadataFormat, MetadataLoadOptions, MetadataLoadResult, MetadataStats, MetadataSaveOptions, MetadataSaveResult } from '@objectstack/spec/system';
 export { MetadataCollectionInfo, MetadataDiffResult, MetadataFormat, MetadataHistoryQueryOptions, MetadataHistoryQueryResult, MetadataHistoryRecord, MetadataHistoryRetentionPolicy, MetadataLoadOptions, MetadataLoadResult, MetadataLoaderContract, MetadataManagerConfig, MetadataSaveOptions, MetadataSaveResult, MetadataStats, MetadataWatchEvent } from '@objectstack/spec/system';
@@ -37,10 +37,140 @@ declare class FilesystemLoader implements MetadataLoader {
     constructor(rootDir: string, serializers: Map<MetadataFormat, MetadataSerializer>, logger?: Logger | undefined);
     load(type: string, name: string, options?: MetadataLoadOptions): Promise<MetadataLoadResult>;
     loadMany<T = any>(type: string, options?: MetadataLoadOptions): Promise<T[]>;
+    /**
+     * [#14341] The keyed half of {@link loadMany} — see {@link MetadataKeyedItem}
+     * for why the store's key travels BESIDE the body instead of being folded
+     * into it.
+     *
+     * THE RULE, in one sentence: an item is keyed by this loader's own
+     * name-to-path derivation — {@link nameFromFilename}, the very basename
+     * derivation `list()` reports — ONLY where that derivation is a bijection for
+     * the file (it sits directly under `ROOT/TYPE/` and carries one of the
+     * extensions {@link findFile} tries, so `findFile(type, key)` resolves back to
+     * this same file); every other shape keeps the pre-#14205 behaviour verbatim,
+     * keyed by `body.name` when it has one and dropped when it has none.
+     *
+     * Why the rule stops there (PM ruling on #14341, 2026-09-02, knowingly over
+     * triage's "a nested path keeps whatever `list()` reports for it today"):
+     * `list()` and `findFile()` DISAGREE outside that shape. For
+     * `ROOT/TYPE/crm/account.json`, `list()` reports the bare `account`, but
+     * `findFile()` resolves that name against `ROOT/TYPE/account.json` and finds
+     * nothing — the only name reaching the file is `crm/account`, which nothing
+     * reports. An extension-less file is read by `loadMany()` and reported by
+     * `list()`, and `findFile()` resolves neither. Keying by either side would
+     * mint a name some other door cannot open, and two directories holding the
+     * same basename would collide in silence
+     * (`MetadataManager.admitLoaderItems()` keeps the first and says nothing).
+     * The card's own fence: "keying items under names nothing else uses … is
+     * worse than today's honest drop". So the drop stays exactly where the key is
+     * unsettled, and is pinned as a RECORD in
+     * `filesystem-loader-keyed-items.test.ts`.
+     *
+     * [#14486, partial] `list()` and {@link findFile} have since converged on
+     * {@link resolvableNameForPath} — the derivation this method already used —
+     * so a nested or extension-less file is now neither listed nor resolvable.
+     * What did NOT change is the WALK behind this method: `loadManyEntries()`
+     * still READS those files, so `loadMany()` still returns their bodies and
+     * this method still falls back to `body.name` for them. That half of the
+     * #14486 ruling ("nothing unlisted is returned by `loadMany()` either") is
+     * deliberately NOT taken here: it would invert the three landed #14341 pins
+     * in `filesystem-loader-keyed-items.test.ts:113,167,187` and the
+     * `loadMany()` CONTROL at `:196`, and that file was under a concurrent
+     * claim (PR #14627) when this landed. The remaining divergence — listed ⊂
+     * loaded — is pinned as a RECORD in
+     * `filesystem-loader-list-reachability.test.ts` rather than left implicit.
+     *
+     * One consequence, deliberate: a flat file whose `body.name` DISAGREES with
+     * its basename is now keyed by the BASENAME. That is #14205's rule (identity
+     * is the key the store holds an item under, not `body.name`) applied to this
+     * loader, and it aligns `MetadataManager.list()` with `listNames()` for that
+     * shape.
+     *
+     * The body is handed back by reference, unchanged: nothing is written into a
+     * body that deliberately has no `name`. `limit` bounds the items LOADED,
+     * exactly as `loadMany()` does — an entry the key rule drops has still been
+     * read and still counts against it.
+     */
+    loadManyKeyed<T = any>(type: string, options?: MetadataLoadOptions): Promise<MetadataKeyedItem<T>[]>;
+    /**
+     * The single walk behind {@link loadMany} and {@link loadManyKeyed}: one glob,
+     * one serializer pass, one `limit`. Shared so the two can never answer with
+     * different bodies for the same file — {@link MetadataLoader.loadManyKeyed}
+     * requires `data` to be "the same body `loadMany()` would return for the
+     * item", and a second copy of this walk is how that would quietly stop being
+     * true.
+     */
+    private loadManyEntries;
     exists(type: string, name: string): Promise<boolean>;
     stat(type: string, name: string): Promise<MetadataStats | null>;
+    /**
+     * [#14486] The names this loader can be asked for, and ONLY those: a file
+     * directly under `ROOT/TYPE/` carrying an extension one of this instance's
+     * REGISTERED serializers claims. Every name it reports resolves back through
+     * {@link findFile}, so `listNames()` and `get()` give the same answer.
+     *
+     * It used to report `path.basename(file, ext)` for every file the glob found,
+     * nested or not, extension or not — and {@link findFile} resolves neither
+     * shape. `ROOT/TYPE/crm/account.json` was listed as `account`, which resolves
+     * against `ROOT/TYPE/account.json` and finds nothing; an extension-less
+     * `ROOT/TYPE/noext` was listed as `noext`, which resolves under no appended
+     * extension at all. A name in the list that `get()` answers `null` for is the
+     * silent failure an author (human or AI) reads as their own typo, so they
+     * retry the same word: the list and the door now agree instead.
+     *
+     * Ruling (maintainer, via the director seat on #14486, 2026-09-02): narrow
+     * the list — direction A, over B (reverse-unify: report `crm/account` and
+     * teach `findFile()` path-shaped names), which would have made a slash inside
+     * a metadata name every consumer's permanent obligation with no measured
+     * demand for it. The two-segment layout follows ADR-0008 §10, which
+     * `metadata-fs`'s `parseItemPath()` already enforces for its own store; the
+     * EXTENSION set deliberately does NOT follow §10's `.json`-only rule — see
+     * {@link resolvableExtensions} for why.
+     */
     list(type: string): Promise<string[]>;
     save(type: string, name: string, data: any, options?: MetadataSaveOptions): Promise<MetadataSaveResult>;
+    /**
+     * The inverse of {@link detectFormat}: which file extensions carry which
+     * format. Fixed ORDER, because it is also {@link findFile}'s precedence when
+     * two files under one type directory share a stem — registration order must
+     * not be able to change which file `ROOT/TYPE/NAME` opens.
+     */
+    private static readonly EXTENSIONS_BY_FORMAT;
+    /**
+     * [#14486] The extensions a name can be resolved under, for THIS instance:
+     * the ones belonging to the serializer set it was constructed with. Shared by
+     * {@link findFile}, {@link resolvableNameForPath} and therefore {@link list},
+     * so the set a name can be RESOLVED under cannot drift from the set that is
+     * LISTED or the set {@link loadManyKeyed} is willing to KEY by.
+     *
+     * Registered, not hard-coded, and deliberately not ADR-0008 §10's `.json`
+     * only. §10 governs the `metadata-fs` store; applying it verbatim here would
+     * drop `.yaml` and `.ts` metadata out of `listNames()` — a breakage this card
+     * never asked for. Under the manager's DEFAULT format set
+     * (`typescript` / `json` / `yaml`, `metadata-manager.ts`) that leaves `.js`
+     * out, which is the card's row-4 membership mismatch closing for free: a `.js`
+     * file was listed and resolvable while `loadMany()` could never return it and
+     * `load()` threw `No serializer found for format: javascript`. Register
+     * `javascript` and it is listed, resolvable and loadable together.
+     */
+    private resolvableExtensions;
+    /**
+     * The metadata name this loader reports for a file: the basename with its
+     * extension stripped. One derivation, shared by {@link list} and
+     * {@link loadManyKeyed}, so the two cannot drift for the shape where they
+     * agree — `dotted.config.json` is `dotted.config` for both.
+     */
+    private static nameFromFilename;
+    /**
+     * The key for a file IF this loader's name-to-path mapping is a bijection for
+     * it: a file directly under `ROOT/TYPE/` carrying an extension
+     * {@link findFile} tries, so `findFile(type, key)` resolves back to this very
+     * file. `null` for every other shape — a nested path, an extension-less file,
+     * an extension spelled in a case `findFile()` does not compose — which is why
+     * {@link loadManyKeyed} falls back to `body.name` there rather than minting a
+     * key no other door can open.
+     */
+    private resolvableNameForPath;
     /**
      * Find file for a given type and name
      */
@@ -61,4 +191,4 @@ declare class FilesystemLoader implements MetadataLoader {
     private generateETag;
 }
 
-export { FilesystemLoader, MetadataLoader, MetadataManager, MetadataManagerOptions, MetadataSerializer, NodeMetadataManager };
+export { FilesystemLoader, MetadataKeyedItem, MetadataLoader, MetadataManager, MetadataManagerOptions, MetadataSerializer, NodeMetadataManager };

package/dist/node.d.ts

@@ -1,5 +1,5 @@
-import { MetadataManager, MetadataManagerOptions, MetadataLoader, MetadataSerializer } from './index.js';
-export { DatabaseLoader, DatabaseLoaderOptions, HistoryCleanupManager, JSONSerializer, MemoryLoader, MetadataPlugin, Migration, RemoteLoader, SerializeOptions, TypeScriptSerializer, WatchCallback, YAMLSerializer, calculateChecksum, generateDiffSummary, generateSimpleDiff } from './index.js';
+import { MetadataManager, MetadataManagerOptions, MetadataLoader, MetadataSerializer, MetadataKeyedItem } from './index.js';
+export { DatabaseLoader, DatabaseLoaderOptions, HistoryCleanupManager, JSONSerializer, MemoryLoader, MetadataPlugin, Migration, RemoteLoader, SerializeOptions, TypeScriptSerializer, WatchCallback, YAMLSerializer, calculateChecksum, deriveViewContainerObject, generateDiffSummary, generateSimpleDiff } from './index.js';
 export { HistoryOptions, MetaRef, MetadataEvent, MetadataItem, MetadataItemHeader, MetadataRepository, SysMetadataHistoryObject, SysMetadataObject, WatchFilter } from '@objectstack/metadata-core';
 import { MetadataLoaderContract, MetadataFormat, MetadataLoadOptions, MetadataLoadResult, MetadataStats, MetadataSaveOptions, MetadataSaveResult } from '@objectstack/spec/system';
 export { MetadataCollectionInfo, MetadataDiffResult, MetadataFormat, MetadataHistoryQueryOptions, MetadataHistoryQueryResult, MetadataHistoryRecord, MetadataHistoryRetentionPolicy, MetadataLoadOptions, MetadataLoadResult, MetadataLoaderContract, MetadataManagerConfig, MetadataSaveOptions, MetadataSaveResult, MetadataStats, MetadataWatchEvent } from '@objectstack/spec/system';
@@ -37,10 +37,140 @@ declare class FilesystemLoader implements MetadataLoader {
     constructor(rootDir: string, serializers: Map<MetadataFormat, MetadataSerializer>, logger?: Logger | undefined);
     load(type: string, name: string, options?: MetadataLoadOptions): Promise<MetadataLoadResult>;
     loadMany<T = any>(type: string, options?: MetadataLoadOptions): Promise<T[]>;
+    /**
+     * [#14341] The keyed half of {@link loadMany} — see {@link MetadataKeyedItem}
+     * for why the store's key travels BESIDE the body instead of being folded
+     * into it.
+     *
+     * THE RULE, in one sentence: an item is keyed by this loader's own
+     * name-to-path derivation — {@link nameFromFilename}, the very basename
+     * derivation `list()` reports — ONLY where that derivation is a bijection for
+     * the file (it sits directly under `ROOT/TYPE/` and carries one of the
+     * extensions {@link findFile} tries, so `findFile(type, key)` resolves back to
+     * this same file); every other shape keeps the pre-#14205 behaviour verbatim,
+     * keyed by `body.name` when it has one and dropped when it has none.
+     *
+     * Why the rule stops there (PM ruling on #14341, 2026-09-02, knowingly over
+     * triage's "a nested path keeps whatever `list()` reports for it today"):
+     * `list()` and `findFile()` DISAGREE outside that shape. For
+     * `ROOT/TYPE/crm/account.json`, `list()` reports the bare `account`, but
+     * `findFile()` resolves that name against `ROOT/TYPE/account.json` and finds
+     * nothing — the only name reaching the file is `crm/account`, which nothing
+     * reports. An extension-less file is read by `loadMany()` and reported by
+     * `list()`, and `findFile()` resolves neither. Keying by either side would
+     * mint a name some other door cannot open, and two directories holding the
+     * same basename would collide in silence
+     * (`MetadataManager.admitLoaderItems()` keeps the first and says nothing).
+     * The card's own fence: "keying items under names nothing else uses … is
+     * worse than today's honest drop". So the drop stays exactly where the key is
+     * unsettled, and is pinned as a RECORD in
+     * `filesystem-loader-keyed-items.test.ts`.
+     *
+     * [#14486, partial] `list()` and {@link findFile} have since converged on
+     * {@link resolvableNameForPath} — the derivation this method already used —
+     * so a nested or extension-less file is now neither listed nor resolvable.
+     * What did NOT change is the WALK behind this method: `loadManyEntries()`
+     * still READS those files, so `loadMany()` still returns their bodies and
+     * this method still falls back to `body.name` for them. That half of the
+     * #14486 ruling ("nothing unlisted is returned by `loadMany()` either") is
+     * deliberately NOT taken here: it would invert the three landed #14341 pins
+     * in `filesystem-loader-keyed-items.test.ts:113,167,187` and the
+     * `loadMany()` CONTROL at `:196`, and that file was under a concurrent
+     * claim (PR #14627) when this landed. The remaining divergence — listed ⊂
+     * loaded — is pinned as a RECORD in
+     * `filesystem-loader-list-reachability.test.ts` rather than left implicit.
+     *
+     * One consequence, deliberate: a flat file whose `body.name` DISAGREES with
+     * its basename is now keyed by the BASENAME. That is #14205's rule (identity
+     * is the key the store holds an item under, not `body.name`) applied to this
+     * loader, and it aligns `MetadataManager.list()` with `listNames()` for that
+     * shape.
+     *
+     * The body is handed back by reference, unchanged: nothing is written into a
+     * body that deliberately has no `name`. `limit` bounds the items LOADED,
+     * exactly as `loadMany()` does — an entry the key rule drops has still been
+     * read and still counts against it.
+     */
+    loadManyKeyed<T = any>(type: string, options?: MetadataLoadOptions): Promise<MetadataKeyedItem<T>[]>;
+    /**
+     * The single walk behind {@link loadMany} and {@link loadManyKeyed}: one glob,
+     * one serializer pass, one `limit`. Shared so the two can never answer with
+     * different bodies for the same file — {@link MetadataLoader.loadManyKeyed}
+     * requires `data` to be "the same body `loadMany()` would return for the
+     * item", and a second copy of this walk is how that would quietly stop being
+     * true.
+     */
+    private loadManyEntries;
     exists(type: string, name: string): Promise<boolean>;
     stat(type: string, name: string): Promise<MetadataStats | null>;
+    /**
+     * [#14486] The names this loader can be asked for, and ONLY those: a file
+     * directly under `ROOT/TYPE/` carrying an extension one of this instance's
+     * REGISTERED serializers claims. Every name it reports resolves back through
+     * {@link findFile}, so `listNames()` and `get()` give the same answer.
+     *
+     * It used to report `path.basename(file, ext)` for every file the glob found,
+     * nested or not, extension or not — and {@link findFile} resolves neither
+     * shape. `ROOT/TYPE/crm/account.json` was listed as `account`, which resolves
+     * against `ROOT/TYPE/account.json` and finds nothing; an extension-less
+     * `ROOT/TYPE/noext` was listed as `noext`, which resolves under no appended
+     * extension at all. A name in the list that `get()` answers `null` for is the
+     * silent failure an author (human or AI) reads as their own typo, so they
+     * retry the same word: the list and the door now agree instead.
+     *
+     * Ruling (maintainer, via the director seat on #14486, 2026-09-02): narrow
+     * the list — direction A, over B (reverse-unify: report `crm/account` and
+     * teach `findFile()` path-shaped names), which would have made a slash inside
+     * a metadata name every consumer's permanent obligation with no measured
+     * demand for it. The two-segment layout follows ADR-0008 §10, which
+     * `metadata-fs`'s `parseItemPath()` already enforces for its own store; the
+     * EXTENSION set deliberately does NOT follow §10's `.json`-only rule — see
+     * {@link resolvableExtensions} for why.
+     */
     list(type: string): Promise<string[]>;
     save(type: string, name: string, data: any, options?: MetadataSaveOptions): Promise<MetadataSaveResult>;
+    /**
+     * The inverse of {@link detectFormat}: which file extensions carry which
+     * format. Fixed ORDER, because it is also {@link findFile}'s precedence when
+     * two files under one type directory share a stem — registration order must
+     * not be able to change which file `ROOT/TYPE/NAME` opens.
+     */
+    private static readonly EXTENSIONS_BY_FORMAT;
+    /**
+     * [#14486] The extensions a name can be resolved under, for THIS instance:
+     * the ones belonging to the serializer set it was constructed with. Shared by
+     * {@link findFile}, {@link resolvableNameForPath} and therefore {@link list},
+     * so the set a name can be RESOLVED under cannot drift from the set that is
+     * LISTED or the set {@link loadManyKeyed} is willing to KEY by.
+     *
+     * Registered, not hard-coded, and deliberately not ADR-0008 §10's `.json`
+     * only. §10 governs the `metadata-fs` store; applying it verbatim here would
+     * drop `.yaml` and `.ts` metadata out of `listNames()` — a breakage this card
+     * never asked for. Under the manager's DEFAULT format set
+     * (`typescript` / `json` / `yaml`, `metadata-manager.ts`) that leaves `.js`
+     * out, which is the card's row-4 membership mismatch closing for free: a `.js`
+     * file was listed and resolvable while `loadMany()` could never return it and
+     * `load()` threw `No serializer found for format: javascript`. Register
+     * `javascript` and it is listed, resolvable and loadable together.
+     */
+    private resolvableExtensions;
+    /**
+     * The metadata name this loader reports for a file: the basename with its
+     * extension stripped. One derivation, shared by {@link list} and
+     * {@link loadManyKeyed}, so the two cannot drift for the shape where they
+     * agree — `dotted.config.json` is `dotted.config` for both.
+     */
+    private static nameFromFilename;
+    /**
+     * The key for a file IF this loader's name-to-path mapping is a bijection for
+     * it: a file directly under `ROOT/TYPE/` carrying an extension
+     * {@link findFile} tries, so `findFile(type, key)` resolves back to this very
+     * file. `null` for every other shape — a nested path, an extension-less file,
+     * an extension spelled in a case `findFile()` does not compose — which is why
+     * {@link loadManyKeyed} falls back to `body.name` there rather than minting a
+     * key no other door can open.
+     */
+    private resolvableNameForPath;
     /**
      * Find file for a given type and name
      */
@@ -61,4 +191,4 @@ declare class FilesystemLoader implements MetadataLoader {
     private generateETag;
 }
 
-export { FilesystemLoader, MetadataLoader, MetadataManager, MetadataManagerOptions, MetadataSerializer, NodeMetadataManager };
+export { FilesystemLoader, MetadataKeyedItem, MetadataLoader, MetadataManager, MetadataManagerOptions, MetadataSerializer, NodeMetadataManager };