@chronicle.app/schema 0.3.0 → 0.5.0

package/dist/datetime.d.ts

@@ -0,0 +1,10 @@
+/** Whether `value` is a full instant in UTC, such as `2024-03-02T14:05:00Z`. */
+export declare function isInstant(value: string): boolean;
+/**
+ * Whether `value` is a :DateTime string: a full instant in UTC
+ * (`2024-03-02T14:05:00Z`), or a date at year, month, or day precision that
+ * may leave trailing year digits, the month, or the day unspecified with `X`
+ * and may end in one qualifier (`?` uncertain, `~` approximate, `%` both).
+ */
+export declare function isDateTime(value: string): boolean;
+//# sourceMappingURL=datetime.d.ts.map

package/dist/datetime.js

@@ -0,0 +1,49 @@
+// A :DateTime string is one point in time, written in a subset of EDTF
+// (ISO 8601-2). See the :DateTime comment in chronicle.ttl for the forms.
+// A year with any trailing digits unspecified: 1987, 198X, 19XX, 1XXX, XXXX.
+const YEAR = String.raw `\d{4}|\d{3}X|\d{2}XX|\dXXX|XXXX`;
+const DATE = new RegExp(String.raw `^(?<year>${YEAR})(?:-(?<month>\d{2}|XX)(?:-(?<day>\d{2}|XX))?)?(?<qualifier>[?~%])?$`);
+const INSTANT = /^(?<year>\d{4})-(?<month>\d{2})-(?<day>\d{2})T(?<hour>\d{2}):(?<minute>\d{2}):(?<second>\d{2})(?:\.\d+)?Z$/;
+const daysIn = (year, month) => new Date(Date.UTC(year, month, 0)).getUTCDate();
+const validDay = (year, month, day) => {
+    if (month === 'XX' || day === 'XX')
+        return true;
+    const days = /X/.test(year) ? daysIn(2000, Number(month)) : daysIn(Number(year), Number(month));
+    return Number(day) >= 1 && Number(day) <= days;
+};
+/** Whether `value` is a full instant in UTC, such as `2024-03-02T14:05:00Z`. */
+export function isInstant(value) {
+    const instant = INSTANT.exec(value)?.groups;
+    if (!instant)
+        return false;
+    const { year, month, day, hour, minute, second } = instant;
+    return (Number(month) >= 1 &&
+        Number(month) <= 12 &&
+        validDay(year, month, day) &&
+        Number(hour) <= 23 &&
+        Number(minute) <= 59 &&
+        Number(second) <= 59);
+}
+/**
+ * Whether `value` is a :DateTime string: a full instant in UTC
+ * (`2024-03-02T14:05:00Z`), or a date at year, month, or day precision that
+ * may leave trailing year digits, the month, or the day unspecified with `X`
+ * and may end in one qualifier (`?` uncertain, `~` approximate, `%` both).
+ */
+export function isDateTime(value) {
+    if (INSTANT.test(value))
+        return isInstant(value);
+    const date = DATE.exec(value)?.groups;
+    if (!date)
+        return false;
+    const { year, month, day } = date;
+    // An unspecified month with a known day says nothing usable; neither does
+    // a value with no known digit at all.
+    if (month === 'XX' && day !== undefined && day !== 'XX')
+        return false;
+    if (year === 'XXXX' && (month === undefined || month === 'XX'))
+        return false;
+    if (month === undefined || month === 'XX')
+        return true;
+    return (Number(month) >= 1 && Number(month) <= 12 && (day === undefined || validDay(year, month, day)));
+}

package/dist/identity.d.ts

@@ -0,0 +1,59 @@
+import type { KeyField } from './schema.js';
+/**
+ * A node's identity as one string, whatever its source or the shape of its
+ * `@key`: the hash of its keyset, the values of the fields its `@key` names.
+ * Extractors and stores derive it the same way, so one node can name another
+ * by it, such as from its text, without knowing how the other is keyed. The
+ * hash must never change: every stored identity is one.
+ */
+/** A node, as far as its identity goes: its `@key` or `@id`, and the fields they name. */
+export interface KeyedNode {
+    '@type'?: unknown;
+    '@key'?: KeyField[];
+    '@id'?: unknown;
+}
+/**
+ * The source a node identified by nothing but its URL belongs to. A URL is a
+ * portable identifier, like an email address or a phone number, so it belongs
+ * to no product, whichever source saw it.
+ */
+export declare const URL_SOURCE = "url";
+/**
+ * Deep, recursive, stable-key canonicalization: object keys are sorted at
+ * every level and undefined values dropped, so equal content always produces
+ * identical bytes. Array order is kept, since it means something. A `Date` is
+ * the ISO string a store gets for it, once it's serialized.
+ */
+export declare function canonicalize(value: unknown): unknown;
+/** Canonical JSON: the same string whatever order the keys were added in. */
+export declare function canonicalJson(value: unknown): string;
+/**
+ * Lowercase base32 (RFC 4648, no padding) of the sha256 of the bytes: 52
+ * characters, shorter than hex and safe in URLs and on case-insensitive
+ * filesystems.
+ */
+export declare function base32Sha256(bytes: Uint8Array): string;
+/**
+ * The hash of a keyset: the base32 sha256 of its canonical JSON, the same
+ * however its keys are ordered.
+ */
+export declare function generateKeysetCID(keyset: Record<string, unknown>): string;
+/**
+ * The keyset a node's `@key` names: each field's value by its path, with dots
+ * and `[*]` splats followed into nested values and a list joined with commas.
+ * `source` is the source given, and an `action.` field is read from the action
+ * the node is in. A computed entry `{ key, value }` is `key:value`. Fields
+ * with no value are left out, and a keyset with none is null, so it never
+ * names one node shared by unrelated records. A key of nothing but `url` is
+ * the `url` source's, so it names the same node whichever source saw it.
+ */
+export declare function keysetOf(node: KeyedNode, source: string | undefined, actionContext?: Record<string, unknown>): Record<string, unknown> | null;
+/**
+ * A node's identity: the hash of the keyset its `@key` names, or its `@id`,
+ * which is that hash already. With both, they must agree. With neither, it's
+ * its `url`, as the `url` source's, or else its `attachmentCid`, the stored
+ * file it is. `source` is the node's own unless given, as for a node in a
+ * record of that source that names none.
+ */
+export declare function nodeKey(node: KeyedNode, source?: string | undefined, actionContext?: Record<string, unknown>): string;
+//# sourceMappingURL=identity.d.ts.map

package/dist/identity.js

@@ -0,0 +1,166 @@
+import { sha256 } from '@noble/hashes/sha2.js';
+/**
+ * The source a node identified by nothing but its URL belongs to. A URL is a
+ * portable identifier, like an email address or a phone number, so it belongs
+ * to no product, whichever source saw it.
+ */
+export const URL_SOURCE = 'url';
+/**
+ * Deep, recursive, stable-key canonicalization: object keys are sorted at
+ * every level and undefined values dropped, so equal content always produces
+ * identical bytes. Array order is kept, since it means something. A `Date` is
+ * the ISO string a store gets for it, once it's serialized.
+ */
+export function canonicalize(value) {
+    if (value instanceof Date) {
+        return value.toISOString();
+    }
+    if (Array.isArray(value)) {
+        return value.map(v => canonicalize(v));
+    }
+    if (value !== null && typeof value === 'object') {
+        const source = value;
+        const out = {};
+        for (const key of Object.keys(source).sort()) {
+            const v = canonicalize(source[key]);
+            if (v !== undefined)
+                out[key] = v;
+        }
+        return out;
+    }
+    return value;
+}
+/** Canonical JSON: the same string whatever order the keys were added in. */
+export function canonicalJson(value) {
+    return JSON.stringify(canonicalize(value));
+}
+const BASE32 = 'abcdefghijklmnopqrstuvwxyz234567';
+/**
+ * Lowercase base32 (RFC 4648, no padding) of the sha256 of the bytes: 52
+ * characters, shorter than hex and safe in URLs and on case-insensitive
+ * filesystems.
+ */
+export function base32Sha256(bytes) {
+    const bits = Array.from(sha256(bytes), byte => byte.toString(2).padStart(8, '0')).join('');
+    let out = '';
+    for (let i = 0; i < bits.length; i += 5) {
+        out += BASE32[Number.parseInt(bits.slice(i, i + 5).padEnd(5, '0'), 2)];
+    }
+    return out;
+}
+/**
+ * The hash of a keyset: the base32 sha256 of its canonical JSON, the same
+ * however its keys are ordered.
+ */
+export function generateKeysetCID(keyset) {
+    // An empty keyset would hash to one key shared by every record that has one.
+    if (Object.keys(keyset).length === 0) {
+        throw new Error('Cannot compute a content key for an empty object — it carries no identity.');
+    }
+    return base32Sha256(new TextEncoder().encode(canonicalJson(keyset)));
+}
+/**
+ * The keyset a node's `@key` names: each field's value by its path, with dots
+ * and `[*]` splats followed into nested values and a list joined with commas.
+ * `source` is the source given, and an `action.` field is read from the action
+ * the node is in. A computed entry `{ key, value }` is `key:value`. Fields
+ * with no value are left out, and a keyset with none is null, so it never
+ * names one node shared by unrelated records. A key of nothing but `url` is
+ * the `url` source's, so it names the same node whichever source saw it.
+ */
+export function keysetOf(node, source, actionContext) {
+    const keyFields = node['@key'];
+    if (!keyFields || keyFields.length === 0)
+        return null;
+    const keyset = {};
+    for (const field of keyFields) {
+        if (typeof field === 'string') {
+            if (field.startsWith('action.') && actionContext) {
+                const value = extractNestedValue(actionContext, field.slice(7));
+                if (value !== undefined && value !== null)
+                    keyset[field] = value;
+            }
+            else {
+                const value = field === 'source' ? source : extractNestedValue(node, field);
+                if (value !== undefined && value !== null) {
+                    keyset[field] = Array.isArray(value) ? value.join(',') : value;
+                }
+            }
+        }
+        else if (typeof field === 'object' && field.key && field.value !== undefined) {
+            keyset[`${field.key}:${field.value}`] = field.value;
+        }
+    }
+    if (Object.keys(keyset).length === 0)
+        return null;
+    if (Object.keys(keyset).length === 1 && typeof keyset.url === 'string') {
+        return { source: URL_SOURCE, url: keyset.url };
+    }
+    return keyset;
+}
+/**
+ * A node's identity: the hash of the keyset its `@key` names, or its `@id`,
+ * which is that hash already. With both, they must agree. With neither, it's
+ * its `url`, as the `url` source's, or else its `attachmentCid`, the stored
+ * file it is. `source` is the node's own unless given, as for a node in a
+ * record of that source that names none.
+ */
+export function nodeKey(node, source = fieldOf(node, 'source'), actionContext) {
+    const keyset = keysetOf(node, source, actionContext);
+    const derived = keyset ? generateKeysetCID(keyset) : undefined;
+    const id = typeof node['@id'] === 'string' && node['@id'] ? node['@id'] : undefined;
+    if (id && derived && id !== derived) {
+        throw new Error(`Entity @id (${id}) does not match the hash of its @key keyset (${derived}). ` +
+            `Entity type: ${String(node['@type'] ?? 'unknown')}, source: ${source}`);
+    }
+    const fallback = (field, keyset) => {
+        const value = fieldOf(node, field);
+        return value ? generateKeysetCID(keyset(value)) : undefined;
+    };
+    const key = id ??
+        derived ??
+        fallback('url', url => ({ source: URL_SOURCE, url })) ??
+        fallback('attachmentCid', attachmentCid => ({ attachmentCid }));
+    if (!key) {
+        throw new Error(`Entity carries neither @key nor @id — no usable identity. Entity type: ${String(node['@type'] ?? 'unknown')}, source: ${source}`);
+    }
+    return key;
+}
+/** A node's field, when it's a string. */
+function fieldOf(node, field) {
+    const value = node[field];
+    return typeof value === 'string' ? value : undefined;
+}
+function extractNestedValue(obj, path) {
+    if (!obj)
+        return undefined;
+    const parts = path.split('.');
+    let current = obj;
+    for (let i = 0; i < parts.length; i++) {
+        const part = parts[i];
+        if (part.includes('[*]')) {
+            const arrayProp = part.replace('[*]', '');
+            if (current && typeof current === 'object' && arrayProp in current) {
+                const arrayValue = current[arrayProp];
+                if (Array.isArray(arrayValue)) {
+                    const remainingPath = parts.slice(i + 1).join('.');
+                    if (remainingPath) {
+                        return arrayValue
+                            .map(item => extractNestedValue(item, remainingPath))
+                            .filter(val => val !== undefined);
+                    }
+                    return arrayValue;
+                }
+                return undefined;
+            }
+            return undefined;
+        }
+        if (current && typeof current === 'object' && part in current) {
+            current = current[part];
+        }
+        else {
+            return undefined;
+        }
+    }
+    return current;
+}

package/dist/index.d.ts

@@ -1,2 +1,4 @@
 export * from './schema.js';
+export { isDateTime, isInstant } from './datetime.js';
+export { type KeyedNode, URL_SOURCE, base32Sha256, canonicalJson, canonicalize, generateKeysetCID, keysetOf, nodeKey, } from './identity.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -1 +1,3 @@
 export * from './schema.js';
+export { isDateTime, isInstant } from './datetime.js';
+export { URL_SOURCE, base32Sha256, canonicalJson, canonicalize, generateKeysetCID, keysetOf, nodeKey, } from './identity.js';