keepset 0.28.0 → 0.29.0

package/dist/{categories-C7q-yLo-.d.ts → categories-DM2a8Esp.d.ts}

@@ -4,6 +4,8 @@ import { z } from "zod";
 /** A stable identifier: an entry id, a catalogue id. It starts with a letter or digit, so no id can be `__proto__` or any other name that begins with an underscore. Entry ids stay the same across forks, which is what lets two catalogues be compared entry by entry. */
 declare const IdSchema: z.ZodString;
 /** A key of an entry's `properties` or `expectedCounts` record: an identifier that starts with a letter, so it can never be `__proto__` or another name Object.prototype reacts to on assignment. */
+/** A subject: the field of study a dataset is relevant to, as a lowercase slug of words joined by hyphens, such as `operations-research`. It is separate from the entry's domain (its topic), its tags (the node fields it carries) and its namespace (the source it comes from), and it is the value a search filters by. */
+declare const SubjectSchema: z.ZodString;
 /** An alias: an id, or a path of ids joined by `/` such as `foo/graphs/bar`. A bare id is a name inside the entry's own namespace; a path is a name of its own, in the group its leading segments name. The segment pattern repeats the one in `IdSchema` so that each part of a path is an id. */
 declare const AliasSchema: z.ZodString;
 /** The path a dataset sits under in a collection, outermost segment first, such as `["suitesparse", "gset"]`. Each segment is an id, so a segment can never contain the `/` that joins a namespace to a name. */
@@ -401,7 +403,7 @@ type CrosswalkReference = z.infer<typeof CrosswalkReferenceSchema>;
 /** The meta keys a fetched result takes from the entry's own descriptor, which its `properties` therefore may not also set. */
 declare const RESERVED_META_KEYS: readonly ["id", "name"];
 /**
- * One catalogue entry: the descriptor (id, optional namespace and aliases, name, description, domain, tags), the category whose target the entry resolves to, where the bytes come from, the licence and citations, the recipe, the crosswalk, the counts a fetched result is expected to have and the dataset's recorded properties. The kind of data is the category's (`kindOf(category)`), never a second field that could disagree with it.
+ * One catalogue entry: the descriptor (id, optional namespace and aliases, name, description, domain, subjects, tags), the category whose target the entry resolves to, where the bytes come from, the licence and citations, the recipe, the crosswalk, the counts a fetched result is expected to have and the dataset's recorded properties. The kind of data is the category's (`kindOf(category)`), never a second field that could disagree with it.
  */
 declare const EntrySchema: z.ZodObject<{
   id: z.ZodString;
@@ -410,11 +412,11 @@ declare const EntrySchema: z.ZodObject<{
   name: z.ZodString;
   description: z.ZodOptional<z.ZodString>;
   domain: z.ZodOptional<z.ZodString>;
+  subjects: z.ZodOptional<z.ZodArray<z.ZodString>>;
   tags: z.ZodArray<z.ZodString>;
   category: z.ZodEnum<{
     "graph/v1": "graph/v1";
     "or/v1": "or/v1";
-    "or-set/v1": "or-set/v1";
   }>;
   sources: z.ZodArray<z.ZodObject<{
     url: z.ZodURL;
@@ -610,7 +612,7 @@ declare const EntrySchema: z.ZodObject<{
     id: string;
     name: string;
     tags: string[];
-    category: "graph/v1" | "or/v1" | "or-set/v1";
+    category: "graph/v1" | "or/v1";
     sources: {
       url: string;
       retrieved: string;
@@ -751,6 +753,7 @@ declare const EntrySchema: z.ZodObject<{
     aliases?: string[] | undefined;
     description?: string | undefined;
     domain?: string | undefined;
+    subjects?: string[] | undefined;
   };
 };
 type Entry = z.infer<typeof EntrySchema>;
@@ -853,11 +856,11 @@ declare const CatalogueIndexSchema: z.ZodObject<{
     name: z.ZodString;
     description: z.ZodOptional<z.ZodString>;
     domain: z.ZodOptional<z.ZodString>;
+    subjects: z.ZodOptional<z.ZodArray<z.ZodString>>;
     tags: z.ZodArray<z.ZodString>;
     category: z.ZodEnum<{
       "graph/v1": "graph/v1";
       "or/v1": "or/v1";
-      "or-set/v1": "or-set/v1";
     }>;
     sources: z.ZodArray<z.ZodObject<{
       url: z.ZodURL;
@@ -1053,7 +1056,7 @@ declare const CatalogueIndexSchema: z.ZodObject<{
       id: string;
       name: string;
       tags: string[];
-      category: "graph/v1" | "or/v1" | "or-set/v1";
+      category: "graph/v1" | "or/v1";
       sources: {
         url: string;
         retrieved: string;
@@ -1194,6 +1197,7 @@ declare const CatalogueIndexSchema: z.ZodObject<{
       aliases?: string[] | undefined;
       description?: string | undefined;
       domain?: string | undefined;
+      subjects?: string[] | undefined;
     };
   }>;
 }, z.core.$strict> & {
@@ -1216,7 +1220,7 @@ declare const CatalogueIndexSchema: z.ZodObject<{
       id: string;
       name: string;
       tags: string[];
-      category: "graph/v1" | "or/v1" | "or-set/v1";
+      category: "graph/v1" | "or/v1";
       sources: {
         url: string;
         retrieved: string;
@@ -1357,6 +1361,7 @@ declare const CatalogueIndexSchema: z.ZodObject<{
       aliases?: string[] | undefined;
       description?: string | undefined;
       domain?: string | undefined;
+      subjects?: string[] | undefined;
     }[];
   };
 };
@@ -1376,9 +1381,11 @@ interface DatasetQuery {
   readonly category?: string;
   /** The entry's domain, matched exactly. */
   readonly domain?: string;
+  /** A subject slug such as `operations-research`, matched exactly against the entry's subjects. */
+  readonly subject?: string;
   /** A group path such as `suitesparse` or `suitesparse/gset`, in which any segment may be an alias the manifest gives it: matches the entries in that group, in any group beneath it, and the entries a path alias files there. */
   readonly namespace?: string;
-  /** Text that must appear, ignoring case, in the entry's id, an alias, one of its groups, name, description, domain or one of its tags. */
+  /** Text that must appear, ignoring case, in the entry's id, an alias, one of its groups, name, description, domain, one of its subjects or one of its tags. */
   readonly text?: string;
 }
 /** One namespace in the tree of groups: its path, its last segment, and how many distinct entries sit in it or in any namespace beneath it. */
@@ -1465,84 +1472,29 @@ declare const GraphV1Schema: z.ZodObject<{
 };
 type GraphV1 = z.infer<typeof GraphV1Schema>;
 //#endregion
-//#region src/targets/or-set-v1.d.ts
-/** One instance of a set: an or/v1 instance, `{ meta, nodes }`, with the id that names it within the set (for a collection read from an archive, the member's path). */
-declare const OrInstanceSchema: z.ZodObject<{
-  id: z.ZodString;
-  meta: z.ZodPreprocess<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>, unknown>;
-  nodes: z.ZodArray<z.ZodObject<{
-    id: z.ZodString;
-    lat: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
-    lon: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
-    x: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
-    y: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
-    prize: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
-    prizeProbability: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
-    duration: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
-    travelTime: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
-    skill: z.ZodOptional<z.ZodNullable<z.ZodString>>;
-    territory: z.ZodOptional<z.ZodNullable<z.ZodString>>;
-    status: z.ZodOptional<z.ZodNullable<z.ZodString>>;
-    opened: z.ZodOptional<z.ZodNullable<z.ZodString>>;
-    closed: z.ZodOptional<z.ZodNullable<z.ZodString>>;
-    deadline: z.ZodOptional<z.ZodNullable<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>>;
-  }, z.core.$loose>>;
-}, z.core.$strict>;
-type OrInstance = z.infer<typeof OrInstanceSchema>;
+//#region src/targets/json-scalar.d.ts
+/** A JSON scalar: the only values a target's metadata may hold, so `meta` stays a flat record any consumer can tabulate. `z.number()` already rejects NaN and the infinities, which JSON cannot carry. */
+declare const JsonScalarSchema: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>;
+type JsonScalar = z.infer<typeof JsonScalarSchema>;
+//#endregion
+//#region src/targets/collection.d.ts
+/** One member of a collection: the id that names it within the set (for a collection read from an archive, the path of the member it came from) beside the fields of the category's own document, which are the instance's `meta`, nodes and so on. */
+type Instance<Document extends object> = {
+  readonly id: string;
+} & Document;
+/** A collection of documents of one category: `{ meta, instances }`, where `meta` is the entry's own metadata and each instance is a document of the category under an id. */
+interface Collection<Document extends object> {
+  readonly meta: Readonly<Record<string, JsonScalar>>;
+  readonly instances: readonly Instance<Document>[];
+}
 /**
- * The or-set/v1 normalisation target: `{ meta, instances }`, a collection of operations-research instances such as a benchmark suite, each instance an or/v1 document (`{ meta, nodes }`) under an id of its own. Beyond the shapes it checks that instance ids are unique in the set and node ids unique within each instance. A node id need not be unique across instances, because every instance numbers its own nodes.
+ * The schema of a collection of documents of a category, derived from the category's own document schema, so a category needs nothing of its own to be collected. Beyond each instance being a valid document, the instance ids must be unique in the set; node ids and the like stay unique only within an instance, because every instance numbers its own.
+ * @param document - The category's document schema.
+ * @returns The collection schema, with the attached type guard.
  */
-declare const OrSetV1Schema: z.ZodObject<{
-  meta: z.ZodPreprocess<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>, unknown>;
-  instances: z.ZodArray<z.ZodObject<{
-    id: z.ZodString;
-    meta: z.ZodPreprocess<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>, unknown>;
-    nodes: z.ZodArray<z.ZodObject<{
-      id: z.ZodString;
-      lat: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
-      lon: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
-      x: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
-      y: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
-      prize: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
-      prizeProbability: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
-      duration: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
-      travelTime: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
-      skill: z.ZodOptional<z.ZodNullable<z.ZodString>>;
-      territory: z.ZodOptional<z.ZodNullable<z.ZodString>>;
-      status: z.ZodOptional<z.ZodNullable<z.ZodString>>;
-      opened: z.ZodOptional<z.ZodNullable<z.ZodString>>;
-      closed: z.ZodOptional<z.ZodNullable<z.ZodString>>;
-      deadline: z.ZodOptional<z.ZodNullable<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>>;
-    }, z.core.$loose>>;
-  }, z.core.$strict>>;
-}, z.core.$strict> & {
-  is: (value: unknown) => value is {
-    meta: Record<string, string | number | boolean | null>;
-    instances: {
-      id: string;
-      meta: Record<string, string | number | boolean | null>;
-      nodes: {
-        [x: string]: unknown;
-        id: string;
-        lat?: number | null | undefined;
-        lon?: number | null | undefined;
-        x?: number | null | undefined;
-        y?: number | null | undefined;
-        prize?: number | null | undefined;
-        prizeProbability?: number | null | undefined;
-        duration?: number | null | undefined;
-        travelTime?: number | null | undefined;
-        skill?: string | null | undefined;
-        territory?: string | null | undefined;
-        status?: string | null | undefined;
-        opened?: string | null | undefined;
-        closed?: string | null | undefined;
-        deadline?: string | number | null | undefined;
-      }[];
-    }[];
-  };
+declare function collectionOf<Document extends object>(document: z.ZodType<Document>): z.ZodType<Collection<Document>> & {
+  is: (value: unknown) => value is Collection<Document>;
 };
-type OrSetV1 = z.infer<typeof OrSetV1Schema>;
 //#endregion
 //#region src/targets/or-v1.d.ts
 /**
@@ -1618,27 +1570,25 @@ type OrV1 = z.infer<typeof OrV1Schema>;
 declare const CategoryIdSchema: z.ZodEnum<{
   "graph/v1": "graph/v1";
   "or/v1": "or/v1";
-  "or-set/v1": "or-set/v1";
 }>;
 type CategoryId = z.infer<typeof CategoryIdSchema>;
 /** The normalisation target each category resolves to, keyed by category id. */
 interface CategoryTargets {
   readonly "graph/v1": GraphV1;
   readonly "or/v1": OrV1;
-  readonly "or-set/v1": OrSetV1;
 }
 /** The normalised shape of any category: what `fetchDataset` can resolve to. */
 type CategoryTarget = CategoryTargets[CategoryId];
 /** The keys of a target whose values are arrays: the collections an entry's `expectedCounts` may name. */
 type CountedKey<Target> = { readonly [Key in keyof Target]: Target[Key] extends readonly unknown[] ? Key : never; }[keyof Target] & string;
-/** What one fetch of an entry in a category reads: a single document, or a set of documents, one per member of the archive the source unpacks to. */
-type CategoryShape = "document" | "collection";
-/** One category: its id, what it holds, whether an entry is one document or a collection of them, the schema of its normalisation target, and which of the target's arrays an entry may record expected counts for. */
+/** What a fetch of a collection entry resolves to: the entry's metadata and one instance per archive member, each a document of the entry's category. */
+type CollectionTarget<Id extends CategoryId = CategoryId> = Id extends CategoryId ? Collection<CategoryTargets[Id]> : never;
+/** One category: its id, what it holds, the schema of its normalisation target (one document), the schema of a collection of such documents derived from it, and which of the target's arrays an entry may record expected counts for. */
 interface CategoryOf<Id extends CategoryId> {
   readonly id: Id;
   readonly description: string;
-  readonly shape: CategoryShape;
   readonly target: z.ZodType<CategoryTargets[Id]>;
+  readonly collection: z.ZodType<Collection<CategoryTargets[Id]>>;
   readonly counted: readonly CountedKey<CategoryTargets[Id]>[];
 }
 /** A category, or with no argument any of them: a union over the ids, so each category keeps its own target and counted keys. */
@@ -1659,6 +1609,13 @@ declare function getCategory(id: string): Category;
  */
 declare function getTarget<Id extends CategoryId>(id: Id): z.ZodType<CategoryTargets[Id]>;
 declare function getTarget(id: string): z.ZodType<CategoryTarget>;
+/**
+ * Returns the schema of a collection of documents of a category: `{ meta, instances }`, each instance a document of the category under an id, derived from the category's own target schema.
+ * @param id - Any string, as for `getCategory`.
+ * @returns The collection schema.
+ * @throws UnknownCategoryError when no category has that id.
+ */
+declare function getCollectionTarget(id: string): z.ZodType<CollectionTarget>;
 /**
  * The kind of data a category holds: the part of its id before the version.
  * @param id - A category id.
@@ -1668,11 +1625,18 @@ declare function kindOf(id: CategoryId): string;
 /** @returns Every registered category, in id order. */
 declare function listCategories(): readonly Category[];
 /**
- * Counts the collections an entry may record expected counts for, in a resolved target.
+ * The keys of a resolved target an entry may record expected counts for: a document's own arrays, or for a collection its instances.
+ * @param id - The target's category.
+ * @param collection - Whether the entry's recipe reads a collection.
+ * @returns The countable keys.
+ */
+declare function countedKeys(id: CategoryId, collection: boolean): readonly string[];
+/**
+ * Counts the arrays an entry may record expected counts for, in a resolved target.
  * @param id - The target's category.
- * @param target - A resolved target of that category.
+ * @param target - A resolved document of that category, or a collection of them.
  * @returns The length of each counted array, by key.
  */
-declare function countTarget(id: CategoryId, target: CategoryTarget): ReadonlyMap<string, number>;
+declare function countTarget(id: CategoryId, target: CategoryTarget | CollectionTarget): ReadonlyMap<string, number>;
 //#endregion
-export { Entry as $, Dataset as A, AliasSchema as B, GraphNode as C, Catalogue as D, GraphV1Schema as E, LineageSchema as F, Citation as G, ArchiveMember as H, Manifest as I, CollectionArchiveSchema as J, CitationSchema as K, ManifestSchema as L, NamespaceNode as M, createCatalogue as N, CatalogueIndex as O, Lineage as P, DocumentArchive as Q, SemVerSchema as R, GraphEdgeSchema as S, GraphV1 as T, ArchiveMemberSchema as U, Archive as V, ArchiveSchema as W, CrosswalkReference as X, ColumnNameSchema as Y, CrosswalkReferenceSchema as Z, OrInstance as _, WaybackTimestampSchema as _t, CategoryTarget as a, Namespace as at, OrSetV1Schema as b, countTarget as c, ParserSchema as ct, kindOf as d, RecipeSchema as dt, EntrySchema as et, listCategories as f, RelativePathSchema as ft, OrV1Schema as g, SourceSchema as gt, OrV1 as h, Source as ht, CategoryShape as i, LicenceSchema as it, DatasetQuery as j, CatalogueIndexSchema as k, getCategory as l, RESERVED_META_KEYS as lt, OrNodeSchema as m, SnapshotSchema as mt, CategoryId as n, IdSchema as nt, CategoryTargets as o, NamespaceSchema as ot, OrNode as p, Snapshot as pt, CollectionArchive as q, CategoryIdSchema as r, Licence as rt, CountedKey as s, Parser as st, Category as t, HttpUrlSchema as tt, getTarget as u, Recipe as ut, OrInstanceSchema as v, parseEntry as vt, GraphNodeSchema as w, GraphEdge as x, OrSetV1 as y, waybackUrl as yt, parseManifest as z };
+export { CrosswalkReference as $, Catalogue as A, ManifestSchema as B, JsonScalarSchema as C, waybackUrl as Ct, GraphNodeSchema as D, GraphNode as E, NamespaceNode as F, ArchiveMember as G, parseManifest as H, createCatalogue as I, Citation as J, ArchiveMemberSchema as K, Lineage as L, CatalogueIndexSchema as M, Dataset as N, GraphV1 as O, DatasetQuery as P, ColumnNameSchema as Q, LineageSchema as R, JsonScalar as S, parseEntry as St, GraphEdgeSchema as T, AliasSchema as U, SemVerSchema as V, Archive as W, CollectionArchive as X, CitationSchema as Y, CollectionArchiveSchema as Z, OrV1 as _, SnapshotSchema as _t, CategoryTargets as a, IdSchema as at, Instance as b, SubjectSchema as bt, countTarget as c, Namespace as ct, getCollectionTarget as d, ParserSchema as dt, CrosswalkReferenceSchema as et, getTarget as f, RESERVED_META_KEYS as ft, OrNodeSchema as g, Snapshot as gt, OrNode as h, RelativePathSchema as ht, CategoryTarget as i, HttpUrlSchema as it, CatalogueIndex as j, GraphV1Schema as k, countedKeys as l, NamespaceSchema as lt, listCategories as m, RecipeSchema as mt, CategoryId as n, Entry as nt, CollectionTarget as o, Licence as ot, kindOf as p, Recipe as pt, ArchiveSchema as q, CategoryIdSchema as r, EntrySchema as rt, CountedKey as s, LicenceSchema as st, Category as t, DocumentArchive as tt, getCategory as u, Parser as ut, OrV1Schema as v, Source as vt, GraphEdge as w, collectionOf as x, WaybackTimestampSchema as xt, Collection as y, SourceSchema as yt, Manifest as z };

package/dist/index.d.ts

@@ -1,6 +1,5 @@
-import { $ as Entry, A as Dataset, B as AliasSchema, C as GraphNode, D as Catalogue, E as GraphV1Schema, F as LineageSchema, G as Citation, H as ArchiveMember, I as Manifest, J as CollectionArchiveSchema, K as CitationSchema, L as ManifestSchema, M as NamespaceNode, N as createCatalogue, O as CatalogueIndex, P as Lineage, Q as DocumentArchive, R as SemVerSchema, S as GraphEdgeSchema, T as GraphV1, U as ArchiveMemberSchema, V as Archive, W as ArchiveSchema, X as CrosswalkReference, Y as ColumnNameSchema, Z as CrosswalkReferenceSchema, _ as OrInstance, _t as WaybackTimestampSchema, a as CategoryTarget, at as Namespace, b as OrSetV1Schema, c as countTarget, ct as ParserSchema, d as kindOf, dt as RecipeSchema, et as EntrySchema, f as listCategories, ft as RelativePathSchema, g as OrV1Schema, gt as SourceSchema, h as OrV1, ht as Source, i as CategoryShape, it as LicenceSchema, j as DatasetQuery, k as CatalogueIndexSchema, l as getCategory, lt as RESERVED_META_KEYS, m as OrNodeSchema, mt as SnapshotSchema, n as CategoryId, nt as IdSchema, o as CategoryTargets, ot as NamespaceSchema, p as OrNode, pt as Snapshot, q as CollectionArchive, r as CategoryIdSchema, rt as Licence, s as CountedKey, st as Parser, t as Category, tt as HttpUrlSchema, u as getTarget, ut as Recipe, v as OrInstanceSchema, vt as parseEntry, w as GraphNodeSchema, x as GraphEdge, y as OrSetV1, yt as waybackUrl, z as parseManifest } from "./categories-C7q-yLo-.js";
+import { $ as CrosswalkReference, A as Catalogue, B as ManifestSchema, C as JsonScalarSchema, Ct as waybackUrl, D as GraphNodeSchema, E as GraphNode, F as NamespaceNode, G as ArchiveMember, H as parseManifest, I as createCatalogue, J as Citation, K as ArchiveMemberSchema, L as Lineage, M as CatalogueIndexSchema, N as Dataset, O as GraphV1, P as DatasetQuery, Q as ColumnNameSchema, R as LineageSchema, S as JsonScalar, St as parseEntry, T as GraphEdgeSchema, U as AliasSchema, V as SemVerSchema, W as Archive, X as CollectionArchive, Y as CitationSchema, Z as CollectionArchiveSchema, _ as OrV1, _t as SnapshotSchema, a as CategoryTargets, at as IdSchema, b as Instance, bt as SubjectSchema, c as countTarget, ct as Namespace, d as getCollectionTarget, dt as ParserSchema, et as CrosswalkReferenceSchema, f as getTarget, ft as RESERVED_META_KEYS, g as OrNodeSchema, gt as Snapshot, h as OrNode, ht as RelativePathSchema, i as CategoryTarget, it as HttpUrlSchema, j as CatalogueIndex, k as GraphV1Schema, l as countedKeys, lt as NamespaceSchema, m as listCategories, mt as RecipeSchema, n as CategoryId, nt as Entry, o as CollectionTarget, ot as Licence, p as kindOf, pt as Recipe, q as ArchiveSchema, r as CategoryIdSchema, rt as EntrySchema, s as CountedKey, st as LicenceSchema, t as Category, tt as DocumentArchive, u as getCategory, ut as Parser, v as OrV1Schema, vt as Source, w as GraphEdge, x as collectionOf, xt as WaybackTimestampSchema, y as Collection, yt as SourceSchema, z as Manifest } from "./categories-DM2a8Esp.js";
 import { Crosswalk } from "twindex";
-import { z } from "zod";
 //#region src/errors.d.ts
 /** The root of this package's error taxonomy: every error keepset throws is a `KeepsetError`, so callers can catch the family with one check. */
 export declare class KeepsetError extends Error {
@@ -110,11 +109,6 @@ export declare function namesOf(entry: Addressed, segmentAliases?: SegmentAliase
  */
 export declare function serialise(doc: Entry | Manifest | Crosswalk): string;
 //#endregion
-//#region src/targets/json-scalar.d.ts
-/** A JSON scalar: the only values a target's metadata may hold, so `meta` stays a flat record any consumer can tabulate. `z.number()` already rejects NaN and the infinities, which JSON cannot carry. */
-export declare const JsonScalarSchema: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>;
-type JsonScalar = z.infer<typeof JsonScalarSchema>;
-//#endregion
 //#region src/validate.d.ts
 /**
  * Checks a dataset as the catalogue holds it: the entry against the entry schema, and its crosswalk against twindex's structural validation and the entry's category. A catalogue index is checked the same way when it is built, so a bundled dataset is valid unless the package itself is broken; the check is what a contributor runs on an entry they are writing.
@@ -123,4 +117,4 @@ type JsonScalar = z.infer<typeof JsonScalarSchema>;
  */
 export declare function validateDataset(dataset: Dataset): SyntaxIssue[];
 //#endregion
-export { AliasSchema, type Archive, type ArchiveMember, ArchiveMemberSchema, ArchiveSchema, type Catalogue, type CatalogueIndex, CatalogueIndexSchema, type Category, type CategoryId, CategoryIdSchema, type CategoryShape, type CategoryTarget, type CategoryTargets, type Citation, CitationSchema, type CollectionArchive, CollectionArchiveSchema, ColumnNameSchema, type CountedKey, type CrosswalkReference, CrosswalkReferenceSchema, type Dataset, type DatasetQuery, type DocumentArchive, type Entry, type EntryNames, EntrySchema, type GraphEdge, GraphEdgeSchema, type GraphNode, GraphNodeSchema, type GraphV1, GraphV1Schema, HttpUrlSchema, IdSchema, type JsonScalar, type Licence, LicenceSchema, type Lineage, LineageSchema, type Manifest, ManifestSchema, type Namespace, type NamespaceNode, NamespaceSchema, type OrInstance, OrInstanceSchema, type OrNode, OrNodeSchema, type OrSetV1, OrSetV1Schema, type OrV1, OrV1Schema, type Parser, ParserSchema, RESERVED_META_KEYS, type Recipe, RecipeSchema, type RecipeStep, RelativePathSchema, type SegmentAliases, SemVerSchema, type Snapshot, SnapshotSchema, type Source, SourceSchema, type SyntaxIssue, WaybackTimestampSchema, countTarget, createCatalogue, getCategory, getTarget, kindOf, listCategories, parseEntry, parseManifest, waybackUrl };
+export { AliasSchema, type Archive, type ArchiveMember, ArchiveMemberSchema, ArchiveSchema, type Catalogue, type CatalogueIndex, CatalogueIndexSchema, type Category, type CategoryId, CategoryIdSchema, type CategoryTarget, type CategoryTargets, type Citation, CitationSchema, type Collection, type CollectionArchive, CollectionArchiveSchema, type CollectionTarget, ColumnNameSchema, type CountedKey, type CrosswalkReference, CrosswalkReferenceSchema, type Dataset, type DatasetQuery, type DocumentArchive, type Entry, type EntryNames, EntrySchema, type GraphEdge, GraphEdgeSchema, type GraphNode, GraphNodeSchema, type GraphV1, GraphV1Schema, HttpUrlSchema, IdSchema, type Instance, type JsonScalar, JsonScalarSchema, type Licence, LicenceSchema, type Lineage, LineageSchema, type Manifest, ManifestSchema, type Namespace, type NamespaceNode, NamespaceSchema, type OrNode, OrNodeSchema, type OrV1, OrV1Schema, type Parser, ParserSchema, RESERVED_META_KEYS, type Recipe, RecipeSchema, type RecipeStep, RelativePathSchema, type SegmentAliases, SemVerSchema, type Snapshot, SnapshotSchema, type Source, SourceSchema, SubjectSchema, type SyntaxIssue, WaybackTimestampSchema, collectionOf, countTarget, countedKeys, createCatalogue, getCategory, getCollectionTarget, getTarget, kindOf, listCategories, parseEntry, parseManifest, waybackUrl };

package/dist/index.js

@@ -1,4 +1,4 @@
-import { $ as DatasetAmbiguousError, A as parseEntry, B as getTarget, C as ParserSchema, D as SnapshotSchema, E as RelativePathSchema, F as namesOf, G as OrNodeSchema, H as listCategories, J as GraphNodeSchema, K as OrV1Schema, L as CategoryIdSchema, M as waybackUrl, N as NAME_SEPARATOR, O as SourceSchema, P as groupsOf, Q as CatalogueSyntaxError, R as countTarget, S as NamespaceSchema, T as RecipeSchema, U as OrInstanceSchema, V as kindOf, W as OrSetV1Schema, X as JsonScalarSchema, Y as GraphV1Schema, Z as ArchiveError, _ as CrosswalkReferenceSchema, a as CatalogueIndexSchema, b as IdSchema, c as ManifestSchema, d as AliasSchema, et as DatasetNotFoundError, f as ArchiveMemberSchema, g as ColumnNameSchema, h as CollectionArchiveSchema, i as listNamespaces, it as UnknownCategoryError, j as toIssues, k as WaybackTimestampSchema, l as SemVerSchema, m as CitationSchema, n as getManifest, nt as NativeParseError, o as createCatalogue, p as ArchiveSchema, q as GraphEdgeSchema, r as listDatasets, rt as RecipeError, s as LineageSchema, t as getDataset, tt as KeepsetError, u as parseManifest, v as EntrySchema, w as RESERVED_META_KEYS, x as LicenceSchema, y as HttpUrlSchema, z as getCategory } from "./bundled-C52vPmf3.js";
+import { $ as ArchiveError, A as WaybackTimestampSchema, B as countedKeys, C as ParserSchema, D as SnapshotSchema, E as RelativePathSchema, F as groupsOf, G as listCategories, H as getCollectionTarget, I as namesOf, J as collectionOf, K as OrNodeSchema, M as toIssues, N as waybackUrl, O as SourceSchema, P as NAME_SEPARATOR, Q as JsonScalarSchema, R as CategoryIdSchema, S as NamespaceSchema, T as RecipeSchema, U as getTarget, V as getCategory, W as kindOf, X as GraphNodeSchema, Y as GraphEdgeSchema, Z as GraphV1Schema, _ as CrosswalkReferenceSchema, a as CatalogueIndexSchema, at as RecipeError, b as IdSchema, c as ManifestSchema, d as AliasSchema, et as CatalogueSyntaxError, f as ArchiveMemberSchema, g as ColumnNameSchema, h as CollectionArchiveSchema, i as listNamespaces, it as NativeParseError, j as parseEntry, k as SubjectSchema, l as SemVerSchema, m as CitationSchema, n as getManifest, nt as DatasetNotFoundError, o as createCatalogue, ot as UnknownCategoryError, p as ArchiveSchema, q as OrV1Schema, r as listDatasets, rt as KeepsetError, s as LineageSchema, t as getDataset, tt as DatasetAmbiguousError, u as parseManifest, v as EntrySchema, w as RESERVED_META_KEYS, x as LicenceSchema, y as HttpUrlSchema, z as countTarget } from "./bundled-4MeSniHX.js";
 import { validateCrosswalk } from "twindex";
 //#region src/serialise.ts
 /**
@@ -57,4 +57,4 @@ function validateDataset(dataset) {
 	return issues;
 }
 //#endregion
-export { AliasSchema, ArchiveError, ArchiveMemberSchema, ArchiveSchema, CatalogueIndexSchema, CatalogueSyntaxError, CategoryIdSchema, CitationSchema, CollectionArchiveSchema, ColumnNameSchema, CrosswalkReferenceSchema, DatasetAmbiguousError, DatasetNotFoundError, EntrySchema, GraphEdgeSchema, GraphNodeSchema, GraphV1Schema, HttpUrlSchema, IdSchema, JsonScalarSchema, KeepsetError, LicenceSchema, LineageSchema, ManifestSchema, NAME_SEPARATOR, NamespaceSchema, NativeParseError, OrInstanceSchema, OrNodeSchema, OrSetV1Schema, OrV1Schema, ParserSchema, RESERVED_META_KEYS, RecipeError, RecipeSchema, RelativePathSchema, SemVerSchema, SnapshotSchema, SourceSchema, UnknownCategoryError, WaybackTimestampSchema, countTarget, createCatalogue, getCategory, getDataset, getManifest, getTarget, groupsOf, kindOf, listCategories, listDatasets, listNamespaces, namesOf, parseEntry, parseManifest, serialise, validateDataset, waybackUrl };
+export { AliasSchema, ArchiveError, ArchiveMemberSchema, ArchiveSchema, CatalogueIndexSchema, CatalogueSyntaxError, CategoryIdSchema, CitationSchema, CollectionArchiveSchema, ColumnNameSchema, CrosswalkReferenceSchema, DatasetAmbiguousError, DatasetNotFoundError, EntrySchema, GraphEdgeSchema, GraphNodeSchema, GraphV1Schema, HttpUrlSchema, IdSchema, JsonScalarSchema, KeepsetError, LicenceSchema, LineageSchema, ManifestSchema, NAME_SEPARATOR, NamespaceSchema, NativeParseError, OrNodeSchema, OrV1Schema, ParserSchema, RESERVED_META_KEYS, RecipeError, RecipeSchema, RelativePathSchema, SemVerSchema, SnapshotSchema, SourceSchema, SubjectSchema, UnknownCategoryError, WaybackTimestampSchema, collectionOf, countTarget, countedKeys, createCatalogue, getCategory, getCollectionTarget, getDataset, getManifest, getTarget, groupsOf, kindOf, listCategories, listDatasets, listNamespaces, namesOf, parseEntry, parseManifest, serialise, validateDataset, waybackUrl };

package/dist/node/fetch-dataset.d.ts

@@ -1,4 +1,4 @@
-import { $ as Entry, A as Dataset, a as CategoryTarget, ht as Source, pt as Snapshot } from "../categories-C7q-yLo-.js";
+import { N as Dataset, gt as Snapshot, i as CategoryTarget, nt as Entry, o as CollectionTarget, vt as Source } from "../categories-DM2a8Esp.js";
 //#region src/node/fetch-dataset.d.ts
 /** The network port a recipe downloads through: `downloadRaw` by default, which returns the bytes exactly as served, or a stand-in under test. */
 export type FetchPort = (url: string, init: {
@@ -29,10 +29,10 @@ export interface Provenance {
   /** The archive members a collection was read from, in the order they were read. */
   readonly members?: readonly string[];
 }
-/** A fetched dataset: the resolved category target, the provenance of the bytes it came from, and any warnings, such as a count that differs from the one the entry records. */
+/** A fetched dataset: the resolved category target (one document, or for a recipe that selects archive members a collection of them), the provenance of the bytes it came from, and any warnings, such as a count that differs from the one the entry records. */
 export interface FetchedDataset {
   readonly dataset: Dataset;
-  readonly data: CategoryTarget;
+  readonly data: CategoryTarget | CollectionTarget;
   readonly provenance: Provenance;
   readonly warnings: readonly string[];
 }

package/dist/node/fetch-dataset.js

@@ -1,4 +1,4 @@
-import { B as getTarget, I as getOwn, R as countTarget, Z as ArchiveError, nt as NativeParseError, rt as RecipeError, t as getDataset, tt as KeepsetError } from "../bundled-C52vPmf3.js";
+import { $ as ArchiveError, H as getCollectionTarget, L as getOwn, U as getTarget, at as RecipeError, it as NativeParseError, rt as KeepsetError, t as getDataset, z as countTarget } from "../bundled-4MeSniHX.js";
 import { RoundTripMismatchError, assertRoundTrip, encode } from "twindex";
 import { z } from "zod";
 import { createHash } from "node:crypto";
@@ -2858,10 +2858,22 @@ function metaOf(entry) {
 	};
 }
 /**
-* Runs a recipe's download, extract and parse steps, and builds the native document the crosswalk receives: the parser's output with `meta` built from the entry.
+* Puts an instance's id beside the fields of its encoded document. A document that is not an object is left as it is, for the collection schema to refuse.
+* @param document - The crosswalk's output for one member.
+* @param id - The member's path.
+* @returns The instance.
+*/
+function withId(document, id) {
+	return typeof document === "object" && document !== null && !Array.isArray(document) ? {
+		...document,
+		id
+	} : document;
+}
+/**
+* Runs a recipe's download, extract and parse steps, and builds the native documents the crosswalk receives.
 * @param dataset - The dataset.
 * @param options - The network port, abort signal and clock.
-* @returns The native document and the provenance of its bytes.
+* @returns The native documents and the provenance of their bytes.
 */
 async function runToNative(dataset, options) {
 	const { entry } = dataset;
@@ -2896,35 +2908,39 @@ async function runToNative(dataset, options) {
 	const { archive } = recipe;
 	if ("members" in archive) {
 		const files = await step(entry.id, "extract", () => unpackMembers(bytes, archive));
-		const members = await step(entry.id, "parse", () => files.map((file) => {
-			try {
-				return {
-					id: file.path,
-					meta: {},
-					...parseNative(file.bytes, recipe.parser)
-				};
-			} catch (error) {
-				throw new KeepsetError(`member ${file.path}: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
-			}
-		}));
 		return {
-			native: {
-				meta: metaOf(entry),
-				members
-			},
+			collection: true,
+			documents: await step(entry.id, "parse", () => files.map((file) => {
+				try {
+					const parsed = parseNative(file.bytes, recipe.parser);
+					return {
+						id: file.path,
+						native: {
+							...parsed,
+							meta: "meta" in parsed ? parsed.meta : {}
+						}
+					};
+				} catch (error) {
+					throw new KeepsetError(`member ${file.path}: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+				}
+			})),
 			provenance: provenanceOf({ members: files.map((file) => file.path) })
 		};
 	}
 	const unpacked = await step(entry.id, "extract", () => unpack(bytes, archive));
 	const parsed = await step(entry.id, "parse", () => parseNative(unpacked.bytes, recipe.parser));
 	return {
-		native: {
-			...parsed,
-			meta: {
-				..."meta" in parsed ? parsed.meta : {},
-				...metaOf(entry)
+		collection: false,
+		documents: [{
+			id: void 0,
+			native: {
+				...parsed,
+				meta: {
+					..."meta" in parsed ? parsed.meta : {},
+					...metaOf(entry)
+				}
 			}
-		},
+		}],
 		provenance: provenanceOf(unpacked.member === void 0 ? {} : { member: unpacked.member })
 	};
 }
@@ -2937,11 +2953,22 @@ async function runToNative(dataset, options) {
 */
 async function fetchEntry(dataset, options = {}) {
 	const { entry, crosswalk } = dataset;
-	const { native, provenance } = await runToNative(dataset, options);
-	const encoded = await step(entry.id, "crosswalk", () => encode(crosswalk, native));
+	const { collection, documents, provenance } = await runToNative(dataset, options);
+	const encoded = await step(entry.id, "crosswalk", () => documents.map(({ id, native }) => {
+		try {
+			return encode(crosswalk, native);
+		} catch (error) {
+			throw new KeepsetError(`${id === void 0 ? "" : `member ${id}: `}${error instanceof Error ? error.message : String(error)}`, { cause: error });
+		}
+	}));
 	const data = await step(entry.id, "validate", () => {
-		const result = getTarget(entry.category).safeParse(encoded);
-		if (!result.success) throw new KeepsetError(`the result is not ${entry.category}: ${result.error.issues.map((issue) => `${issue.path.map(String).join(".") || "(root)"}: ${issue.message}`).join("; ")}`);
+		const [only] = encoded;
+		const whole = collection ? {
+			meta: metaOf(entry),
+			instances: encoded.map((document, index) => withId(document, documents[index]?.id))
+		} : only;
+		const result = (collection ? getCollectionTarget(entry.category) : getTarget(entry.category)).safeParse(whole);
+		if (!result.success) throw new KeepsetError(`the result is not ${collection ? "a collection of " : ""}${entry.category}: ${result.error.issues.map((issue) => `${issue.path.map(String).join(".") || "(root)"}: ${issue.message}`).join("; ")}`);
 		return result.data;
 	});
 	const counts = countTarget(entry.category, data);
@@ -2970,9 +2997,9 @@ async function fetchDataset(id, options = {}) {
 * @throws RecipeError naming the entry and the failing step when the recipe fails before the comparison, or when the crosswalk cannot run.
 */
 async function roundTripEntry(dataset, options = {}) {
-	const { native, provenance } = await runToNative(dataset, options);
+	const { documents, provenance } = await runToNative(dataset, options);
 	try {
-		assertRoundTrip(dataset.crosswalk, [native]);
+		assertRoundTrip(dataset.crosswalk, documents.map(({ native }) => native));
 	} catch (error) {
 		if (error instanceof RoundTripMismatchError) return {
 			holds: false,

package/dist-cli/keepset.mjs

@@ -4,7 +4,7 @@ import { KeepsetError, NAME_SEPARATOR, countTarget, getDataset, listDatasets, li
 import { fetchDataset, roundTripDataset } from "keepset/node";
 import { parseArgs } from "node:util";
 //#region package.json
-var version = "0.28.0";
+var version = "0.29.0";
 //#endregion
 //#region cli/run.ts
 /**
@@ -19,11 +19,11 @@ function selectorText(selector) {
 const usage = `Usage: keepset <command> [options]
 
 Commands:
-  search [text] [--kind <kind>] [--domain <domain>] [--namespace <path>]
-         [--category <id>] [--json]
+  search [text] [--kind <kind>] [--domain <domain>] [--subject <subject>]
+         [--namespace <path>] [--category <id>] [--json]
                       list the datasets whose id, alias, namespace, name,
-                      description, domain or tags contain the text, filtered by
-                      kind, domain, namespace (and every namespace beneath it,
+                      description, domain, subjects or tags contain the text,
+                      filtered by kind, domain, subject, namespace (and every namespace beneath it,
                       segment aliases allowed) or category
   namespaces [path] [--json]
                       list the namespaces directly beneath a path, or the
@@ -61,6 +61,7 @@ function parseCommandLine(args) {
 		options: {
 			kind: { type: "string" },
 			domain: { type: "string" },
+			subject: { type: "string" },
 			namespace: { type: "string" },
 			category: { type: "string" },
 			json: { type: "boolean" },
@@ -112,6 +113,7 @@ function formatShow(dataset) {
 	lines.push("", `category: ${entry.category} (kind ${dataset.kind})`, `catalogue: ${dataset.catalogue.id} ${dataset.catalogue.version}`);
 	if (entry.namespace !== void 0) lines.push(`namespace: ${entry.namespace.join(NAME_SEPARATOR)}`);
 	if (entry.aliases !== void 0) lines.push(`aliases: ${entry.aliases.join(", ")}`);
+	if (entry.subjects !== void 0) lines.push(`subjects: ${entry.subjects.join(", ")}`);
 	if (entry.domain !== void 0) lines.push(`domain: ${entry.domain}`);
 	if (entry.tags.length > 0) lines.push(`tags: ${entry.tags.join(", ")}`);
 	const { licence } = entry;
@@ -198,6 +200,7 @@ async function run(args, library, io) {
 				...text === void 0 ? {} : { text },
 				...values.kind === void 0 ? {} : { kind: values.kind },
 				...values.domain === void 0 ? {} : { domain: values.domain },
+				...values.subject === void 0 ? {} : { subject: values.subject },
 				...values.namespace === void 0 ? {} : { namespace: values.namespace },
 				...values.category === void 0 ? {} : { category: values.category }
 			};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "keepset",
   "description": "Library, CLI and statically generated catalogue for dataset fetch-and-normalise recipes",
-  "version": "0.28.0",
+  "version": "0.29.0",
   "bin": {
     "keepset": "./dist-cli/keepset.mjs"
   },