@daihum/record-formats 0.1.0 → 0.1.1

package/README.md

@@ -7,6 +7,7 @@ The package is intentionally modular and tree-shakeable. Consumers import only t
 ```ts
 import { parseXml } from '@daihum/record-formats/xml';
 import { parseEad3Xml } from '@daihum/record-formats/ead3';
+import { parseArchiveDescriptionJson } from '@daihum/record-formats/archive-description';
 ```
 
 ## Initial scope
@@ -14,6 +15,8 @@ import { parseEad3Xml } from '@daihum/record-formats/ead3';
 - Common result and issue contracts for parse, serialize, and validation workflows.
 - XML parse/build helpers backed by `fast-xml-parser`.
 - EAD3 finding-aid projection helpers adapted from Carrel's initial XML/EAD starter.
+- `archive-description.v1`, the canonical recursive Archive record, with JSON Schema,
+  DACS profile validation, and explicit EAD3 projection diagnostics.
 
 Future modules can add TEI, MARC/MARCXML, MODS, Dublin Core, EAC-CPF, and crosswalk helpers under explicit subpaths without forcing consumers to import the whole surface.
 
@@ -31,6 +34,24 @@ Future modules can add TEI, MARC/MARCXML, MODS, Dublin Core, EAC-CPF, and crossw
 
 This means the adapter validates DAIHUM's common finding-aid projection fields and parser/serializer invariants. It does not run official EAD3 RNG, XSD, DTD, or Schematron schema validation yet. Consumers should surface the adapter profile when exporting or importing EAD XML so users can distinguish projection output from full schema validation.
 
+## Archive Description
+
+`@daihum/record-formats/archive-description` owns the canonical Archive-domain
+record. One `archive-description.v1` record represents one finding aid. Its
+stable node ids and recursive `subItems` tree keep hierarchy and description in
+one versioned truth while opaque target refs connect nodes to external material,
+page, representation, or annotation records.
+
+EAD3 is a bidirectional projection of that record, not the canonical store.
+Projection results include structured warnings whenever a canonical fact cannot
+be represented. DACS checks are a separate conformance profile; they do not
+change the structural parser. The JSON Schema id and revision are exported for
+storage envelopes and exchange validation.
+
+Cross-tree node-id uniqueness is enforced by the package runtime validator.
+JSON Schema validates the recursive shape and collection root but cannot express
+that global uniqueness invariant.
+
 ## Boundaries
 
 This package owns format adapters and reusable record mappings. Product storage, UI, CLI, import jobs, copy, and downstream persistence remain in Carrel, ONTAL, or other consuming apps.

package/dist/archive-description/index.d.ts

@@ -0,0 +1,163 @@
+import { i as FormatResult, l as SerializeResult, n as FormatIssue, s as ParseResult } from "../result-D7vcrlFh.js";
+import { k as Ead3FindingAid, w as Ead3Component } from "../index-DxjnI5KZ.js";
+import "../index-BNudmNFx.js";
+
+//#region src/archive-description/types.d.ts
+declare const ARCHIVE_DESCRIPTION_SCHEMA: "archive-description.v1";
+type ArchiveDescriptionSchema = typeof ARCHIVE_DESCRIPTION_SCHEMA;
+type ArchiveDescriptionLevel = 'collection' | 'series' | 'subseries' | 'file' | 'item' | 'otherlevel';
+type ArchiveDescriptionMaintenanceStatus = 'new' | 'revised' | 'deleted' | 'derived' | 'unknown';
+type ArchiveDescriptionDate = Readonly<{
+  expression: string;
+  normalized?: string;
+  type?: string;
+  certainty?: string;
+}>;
+type ArchiveDescriptionAccessPointType = 'person' | 'family' | 'organization' | 'place' | 'subject' | 'documentaryForm' | 'occupation' | 'function' | (string & Record<never, never>);
+type ArchiveDescriptionAccessPoint = Readonly<{
+  type: ArchiveDescriptionAccessPointType;
+  label: string;
+  identifier?: string;
+  source?: string;
+}>;
+/** A product-neutral reference to material, a representation, or an annotation. */
+type ArchiveDescriptionTargetRef = Readonly<{
+  kind: string;
+  id: string;
+  href?: string;
+  label?: string;
+  role?: string;
+  locator?: Readonly<Record<string, unknown>>;
+  metadata?: Readonly<Record<string, unknown>>;
+}>;
+type ArchiveDescriptionReviewStatus = 'unreviewed' | 'needs_review' | 'accepted' | 'rejected';
+type ArchiveDescriptionProvenance = Readonly<{
+  createdBy: string;
+  createdAt: string;
+  method: string;
+  rules?: readonly string[];
+  tool?: string;
+  model?: string;
+  reviewStatus?: ArchiveDescriptionReviewStatus;
+  reviewedBy?: string;
+  reviewedAt?: string;
+}>;
+type ArchiveDescriptionSourceDiagnostic = Readonly<{
+  severity: 'error' | 'warning' | 'info';
+  code: string;
+  message: string;
+  path?: readonly string[];
+}>;
+type ArchiveDescriptionSourceRecord = Readonly<{
+  id: string;
+  producer: string;
+  format?: string;
+  source?: string;
+  retrievedAt?: string;
+  raw?: unknown;
+  mappedFields?: readonly string[];
+  unmappedFields?: unknown;
+  diagnostics?: readonly ArchiveDescriptionSourceDiagnostic[];
+}>;
+type ArchiveDescriptionVendorExtension = Readonly<{
+  namespace: string;
+  name: string;
+  value: unknown;
+}>;
+type ArchiveDescriptionExtensions = Readonly<{
+  ead3?: Readonly<Record<string, unknown>>;
+  vendor?: readonly ArchiveDescriptionVendorExtension[];
+}>;
+type ArchiveDescriptionNode = Readonly<{
+  /** Stable identity. It must not be derived from array position. */
+  id: string;
+  level: ArchiveDescriptionLevel;
+  otherLevel?: string;
+  title: string;
+  referenceCode?: string;
+  repository?: string;
+  dates?: readonly ArchiveDescriptionDate[];
+  extent?: string;
+  creator?: string;
+  creatorStatus?: 'known' | 'unknown' | 'not_applicable';
+  abstract?: string;
+  scopeContent?: string;
+  arrangement?: string;
+  accessRestriction?: string;
+  useRestriction?: string;
+  language?: string;
+  biographicalHistory?: string;
+  custodialHistory?: string;
+  acquisitionInformation?: string;
+  appraisal?: string;
+  processingInformation?: string;
+  relatedMaterial?: string;
+  separatedMaterial?: string;
+  preferredCitation?: string;
+  notes?: readonly string[];
+  accessPoints?: readonly ArchiveDescriptionAccessPoint[];
+  targets?: readonly ArchiveDescriptionTargetRef[];
+  provenance?: ArchiveDescriptionProvenance;
+  subItems?: readonly ArchiveDescriptionNode[];
+  extensions?: ArchiveDescriptionExtensions;
+}>;
+type ArchiveDescriptionRecord = Readonly<{
+  schema: ArchiveDescriptionSchema;
+  recordId: string;
+  title: string;
+  maintenanceStatus?: ArchiveDescriptionMaintenanceStatus;
+  language?: string;
+  agencyName?: string;
+  description: ArchiveDescriptionNode;
+  provenance: ArchiveDescriptionProvenance;
+  sourceRecords?: readonly ArchiveDescriptionSourceRecord[];
+  extensions?: ArchiveDescriptionExtensions;
+}>;
+type ArchiveDescriptionSerializeOptions = Readonly<{
+  format?: boolean;
+}>;
+//#endregion
+//#region src/archive-description/archive-description.d.ts
+declare const ARCHIVE_DESCRIPTION_FORMAT_ID = "archive-description";
+declare function validateArchiveDescription(value: unknown): readonly FormatIssue[];
+declare function parseArchiveDescriptionJson(input: string): ParseResult<ArchiveDescriptionRecord>;
+declare function serializeArchiveDescriptionJson(record: ArchiveDescriptionRecord, options?: ArchiveDescriptionSerializeOptions): SerializeResult<string>;
+declare const archiveDescriptionAdapter: {
+  format: string;
+  parse: typeof parseArchiveDescriptionJson;
+  serialize: typeof serializeArchiveDescriptionJson;
+  validate: typeof validateArchiveDescription;
+  detect(input: string): boolean;
+};
+//#endregion
+//#region src/archive-description/dacs.d.ts
+declare const DACS_PROFILE_ID = "daihum.record-formats.archive-description.dacs.v1";
+type DacsValidationOptions = Readonly<{
+  requireMinimumAtEveryLevel?: boolean;
+}>;
+declare function validateDacsArchiveDescription(record: ArchiveDescriptionRecord, options?: DacsValidationOptions): readonly FormatIssue[];
+//#endregion
+//#region src/archive-description/ead3-projection.d.ts
+declare const ARCHIVE_DESCRIPTION_EAD3_PROJECTION_ID = "daihum.record-formats.archive-description.ead3.v1";
+type ArchiveDescriptionFromEad3Options = Readonly<{
+  provenance: ArchiveDescriptionProvenance;
+  sourceRecord?: ArchiveDescriptionSourceRecord;
+  nodeId?: (component: Ead3Component, path: string) => string | undefined;
+}>;
+declare function archiveDescriptionToEad3(record: ArchiveDescriptionRecord): FormatResult<Ead3FindingAid>;
+declare function archiveDescriptionFromEad3(findingAid: Ead3FindingAid, options: ArchiveDescriptionFromEad3Options): FormatResult<ArchiveDescriptionRecord>;
+//#endregion
+//#region src/archive-description/identity.d.ts
+declare const ARCHIVE_DESCRIPTION_SCHEMA_ID = "https://daihum.dev/schema/record-formats/archive-description.v1.json";
+declare const ARCHIVE_DESCRIPTION_SCHEMA_TITLE = "DAIHUM Archive Description";
+declare const ARCHIVE_DESCRIPTION_SCHEMA_VERSION: "archive-description.v1";
+declare function canonicalJson(value: unknown): string;
+declare function contentHash(input: string): string;
+//#endregion
+//#region src/archive-description/json-schema.d.ts
+declare function buildArchiveDescriptionJsonSchema(): Record<string, unknown>;
+declare const archiveDescriptionJsonSchema: Record<string, unknown>;
+declare const ARCHIVE_DESCRIPTION_SCHEMA_REVISION: string;
+//#endregion
+export { ARCHIVE_DESCRIPTION_EAD3_PROJECTION_ID, ARCHIVE_DESCRIPTION_FORMAT_ID, ARCHIVE_DESCRIPTION_SCHEMA, ARCHIVE_DESCRIPTION_SCHEMA_ID, ARCHIVE_DESCRIPTION_SCHEMA_REVISION, ARCHIVE_DESCRIPTION_SCHEMA_TITLE, ARCHIVE_DESCRIPTION_SCHEMA_VERSION, type ArchiveDescriptionAccessPoint, type ArchiveDescriptionAccessPointType, type ArchiveDescriptionDate, type ArchiveDescriptionExtensions, type ArchiveDescriptionFromEad3Options, type ArchiveDescriptionLevel, type ArchiveDescriptionMaintenanceStatus, type ArchiveDescriptionNode, type ArchiveDescriptionProvenance, type ArchiveDescriptionRecord, type ArchiveDescriptionReviewStatus, type ArchiveDescriptionSchema, type ArchiveDescriptionSerializeOptions, type ArchiveDescriptionSourceDiagnostic, type ArchiveDescriptionSourceRecord, type ArchiveDescriptionTargetRef, type ArchiveDescriptionVendorExtension, DACS_PROFILE_ID, type DacsValidationOptions, archiveDescriptionAdapter, archiveDescriptionFromEad3, archiveDescriptionJsonSchema, archiveDescriptionToEad3, buildArchiveDescriptionJsonSchema, canonicalJson, contentHash, parseArchiveDescriptionJson, serializeArchiveDescriptionJson, validateArchiveDescription, validateDacsArchiveDescription };
+//# sourceMappingURL=index.d.ts.map

package/dist/archive-description/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/archive-description/types.ts","../../src/archive-description/archive-description.ts","../../src/archive-description/dacs.ts","../../src/archive-description/ead3-projection.ts","../../src/archive-description/identity.ts","../../src/archive-description/json-schema.ts"],"sourcesContent":[],"mappings":"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"}