silosdk 0.0.6 → 0.0.7

package/README.md

@@ -25,14 +25,14 @@ TanStack owns:
 yarn add silosdk @tanstack/react-db @tanstack/react-query expo-crypto expo-sqlite expo-file-system
 ```
 
-## Sources
+## Datastores
 
-Sources are SQLite-backed document stores that produce options for TanStack DB
-collections.
+Datastores define SQLite-backed document collections and a link collection for
+relationships between them. They produce options for TanStack DB collections.
 
 ```ts
 import { createCollection } from '@tanstack/react-db'
-import { createID, source } from 'silosdk/source'
+import { createDatastore, createID } from 'silosdk/source'
 
 type Post = {
   title: string
@@ -41,14 +41,28 @@ type Post = {
   coverImage: string | null
 }
 
-export const postsSource = source<Post>('posts', {
-  title: '',
-  body: '',
-  published: false,
-  coverImage: null,
+type Tag = {
+  name: string
+}
+
+export const datastore = createDatastore<{
+  posts: Post
+  tags: Tag
+}>({
+  posts: {
+    title: '',
+    body: '',
+    published: false,
+    coverImage: null,
+  },
+  tags: {
+    name: '',
+  },
 })
 
-export const posts = createCollection(postsSource.collectionOptions())
+export const posts = createCollection(datastore.collectionOptions('posts'))
+export const tags = createCollection(datastore.collectionOptions('tags'))
+export const links = createCollection(datastore.linkCollectionOptions())
 ```
 
 Query and mutate with TanStack DB directly:
@@ -95,6 +109,49 @@ Source rows are intentionally flat. Field values must be:
 type FieldValue = string | number | boolean | null
 ```
 
+Create links with the link collection utilities:
+
+```ts
+await links.utils.link('posts', postId, 'tags', tagId)
+await links.utils.unlink('posts', postId, 'tags', tagId)
+
+const isLinked = links.utils.has('posts', postId, 'tags', tagId)
+```
+
+Link storage is flat and directionless. Collection names are sorted
+lexicographically and IDs are stored in the same order. Query rows expose nested
+paths for each collection pair:
+
+```tsx
+import { eq, useLiveQuery } from '@tanstack/react-db'
+
+const { data: taggedPosts = [] } = useLiveQuery((q) =>
+  q
+    .from({ posts })
+    .join({ links }, ({ posts, links }) =>
+      eq(posts.id, links.tags.posts.id),
+    )
+    .join({ tags }, ({ links, tags }) =>
+      eq(links.posts.tags.id, tags.id),
+    ),
+)
+```
+
+For a `posts` to `tags` link:
+
+```ts
+links.tags.posts.id // post id
+links.posts.tags.id // tag id
+```
+
+Same-collection links are not supported. Define another collection when you need
+a different semantic relationship.
+
+## Sources
+
+The lower-level `source()` API remains available when you only need one
+collection definition.
+
 ## Settings
 
 Settings are small persisted primitive values backed by `expo-sqlite/kv-store`.

package/dist/source.cjs

@@ -14,49 +14,205 @@ const deletedDocs = /* @__PURE__ */ new WeakSet();
 function createID() {
 	return (0, expo_crypto.randomUUID)();
 }
+function createDatastore(defaults) {
+	const names = Object.keys(defaults);
+	const nameSet = new Set(names);
+	for (const name of names) {
+		assertSourceName(name);
+		assertFlatDefaults(name, defaults[name]);
+	}
+	if (new Set(names).size !== names.length) throw new Error("Datastore collection names must be unique.");
+	return {
+		names,
+		collectionOptions(name, options = {}) {
+			assertDatastoreCollectionName(nameSet, name);
+			return createSourceCollectionOptions(name, defaults[name], options);
+		},
+		linkCollectionOptions(options = {}) {
+			return createLinkCollectionOptions(names, nameSet, options);
+		}
+	};
+}
 function source(name, defaults) {
 	assertSourceName(name);
 	assertFlatDefaults(name, defaults);
 	if (sourceNames.has(name)) throw new Error(`Source "${name}" is already registered. Define each source once and import the existing source instead.`);
 	sourceNames.add(name);
-	const schema = createSourceSchema(name, defaults);
 	return {
 		name,
 		defaults,
-		schema,
+		schema: createSourceSchema(name, defaults),
 		collectionOptions(options = {}) {
-			return {
-				id: name,
-				getKey: (item) => item.id,
-				schema,
-				startSync: options.startSync,
-				sync: { sync({ begin, write, commit, markReady, truncate }) {
-					const rows = loadRows(name);
-					begin();
-					truncate();
-					for (const row of rows) write({
-						type: "insert",
-						value: row
-					});
-					commit();
-					markReady();
-				} },
-				onInsert: async ({ transaction }) => {
-					await insertRows(name, transaction.mutations.map((mutation) => mutation.modified));
-				},
-				onUpdate: async ({ transaction }) => {
-					await updateRows(name, transaction.mutations);
-				},
-				onDelete: async ({ transaction }) => {
-					await deleteRows(name, transaction.mutations);
-				}
-			};
+			return createSourceCollectionOptions(name, defaults, options);
+		}
+	};
+}
+function createSourceCollectionOptions(name, defaults, options = {}) {
+	return {
+		id: name,
+		getKey: (item) => item.id,
+		schema: createSourceSchema(name, defaults),
+		startSync: options.startSync,
+		sync: { sync({ begin, write, commit, markReady, truncate }) {
+			const rows = loadRows(name);
+			begin();
+			truncate();
+			for (const row of rows) write({
+				type: "insert",
+				value: row
+			});
+			commit();
+			markReady();
+		} },
+		onInsert: async ({ transaction }) => {
+			await insertRows(name, transaction.mutations.map((mutation) => mutation.modified));
+		},
+		onUpdate: async ({ transaction }) => {
+			await updateRows(name, transaction.mutations);
+		},
+		onDelete: async ({ transaction }) => {
+			await deleteRows(name, transaction.mutations);
+		}
+	};
+}
+function createLinkCollectionOptions(names, nameSet, options = {}) {
+	const schema = createLinkSchema();
+	let syncBegin;
+	let syncWrite;
+	let syncCommit;
+	const writeSyncedLink = (type, row) => {
+		if (!syncBegin || !syncWrite || !syncCommit) return;
+		syncBegin();
+		syncWrite({
+			type,
+			value: row
+		});
+		syncCommit();
+	};
+	return {
+		id: "silo-links",
+		getKey: (item) => item.id,
+		schema,
+		startSync: options.startSync,
+		sync: { sync({ begin, write, commit, markReady, truncate }) {
+			syncBegin = begin;
+			syncWrite = write;
+			syncCommit = commit;
+			const rows = loadLinkRows().map((row) => createLinkRow(names, row));
+			begin();
+			truncate();
+			for (const row of rows) write({
+				type: "insert",
+				value: row
+			});
+			commit();
+			markReady();
+		} },
+		onInsert: async ({ transaction }) => {
+			for (const mutation of transaction.mutations) insertLinkRow(extractStoredLinkRow(mutation.modified));
+		},
+		onDelete: async ({ transaction }) => {
+			for (const mutation of transaction.mutations) deleteLinkRow(String(mutation.key));
+		},
+		utils: {
+			async link(collectionA, idA, collectionB, idB) {
+				const row = createStoredLinkRow(nameSet, collectionA, idA, collectionB, idB);
+				const exists = hasLinkRow(row.id);
+				insertLinkRow(row);
+				if (!exists) writeSyncedLink("insert", createLinkRow(names, row));
+			},
+			async unlink(collectionA, idA, collectionB, idB) {
+				const row = createStoredLinkRow(nameSet, collectionA, idA, collectionB, idB);
+				const exists = hasLinkRow(row.id);
+				deleteLinkRow(row.id);
+				if (exists) writeSyncedLink("delete", createLinkRow(names, row));
+			},
+			has(collectionA, idA, collectionB, idB) {
+				return hasLinkRow(createStoredLinkRow(nameSet, collectionA, idA, collectionB, idB).id);
+			}
 		}
 	};
 }
 function assertSourceName(name) {
 	if (!sourceNamePattern.test(name)) throw new Error(`Source names must start with a letter and contain only letters, numbers, underscores, or hyphens. Received "${name}".`);
 }
+function assertDatastoreCollectionName(nameSet, name) {
+	if (!nameSet.has(name)) throw new Error(`Datastore collection "${name}" is not registered.`);
+}
+function assertLinkCollectionName(nameSet, name) {
+	if (!nameSet.has(name)) throw new Error(`Cannot link unknown collection "${name}".`);
+}
+function createStoredLinkRow(nameSet, collectionA, idA, collectionB, idB) {
+	assertLinkCollectionName(nameSet, collectionA);
+	assertLinkCollectionName(nameSet, collectionB);
+	if (collectionA === collectionB) throw new Error(`Links between the same collection are not supported. Received "${collectionA}".`);
+	const [firstCollection, firstId, secondCollection, secondId] = collectionA < collectionB ? [
+		collectionA,
+		idA,
+		collectionB,
+		idB
+	] : [
+		collectionB,
+		idB,
+		collectionA,
+		idA
+	];
+	const collections = encodePair(firstCollection, secondCollection);
+	const ids = encodePair(firstId, secondId);
+	return {
+		id: encodePair(collections, ids),
+		collections,
+		ids,
+		createdAt: (/* @__PURE__ */ new Date()).toISOString()
+	};
+}
+function createLinkRow(names, row) {
+	const [firstCollection, secondCollection] = decodePair(row.collections);
+	const [firstId, secondId] = decodePair(row.ids);
+	const result = {
+		id: row.id,
+		collections: row.collections,
+		ids: row.ids,
+		createdAt: row.createdAt
+	};
+	for (const other of names) {
+		const byCurrent = {};
+		for (const current of names) {
+			let id = null;
+			if (other !== current) {
+				if (current === firstCollection && other === secondCollection) id = firstId;
+				else if (current === secondCollection && other === firstCollection) id = secondId;
+			}
+			byCurrent[current] = { id };
+		}
+		result[other] = byCurrent;
+	}
+	return result;
+}
+function extractStoredLinkRow(row) {
+	if (!isRecord(row)) throw new Error("Expected a link row object.");
+	if (typeof row.id !== "string" || typeof row.collections !== "string" || typeof row.ids !== "string" || typeof row.createdAt !== "string") throw new Error("Link rows must include string id, collections, ids, and createdAt fields.");
+	return {
+		id: row.id,
+		collections: row.collections,
+		ids: row.ids,
+		createdAt: row.createdAt
+	};
+}
+function encodePair(first, second) {
+	return `${encodePart(first)}:${encodePart(second)}`;
+}
+function decodePair(value) {
+	const parts = value.split(":");
+	if (parts.length !== 2) throw new Error(`Invalid encoded link pair "${value}".`);
+	return [decodePart(parts[0]), decodePart(parts[1])];
+}
+function encodePart(value) {
+	return encodeURIComponent(value);
+}
+function decodePart(value) {
+	return decodeURIComponent(value);
+}
 function assertFlatDefaults(sourceName, defaults) {
 	for (const [field, defaultValue] of Object.entries(defaults)) {
 		if (reservedDocumentFields.has(field)) throw new Error(`Source "${sourceName}" field "${field}" is reserved by Silo documents.`);
@@ -85,6 +241,20 @@ function createSourceSchema(sourceName, defaults) {
 		}
 	} };
 }
+function createLinkSchema() {
+	return { "~standard": {
+		version: 1,
+		vendor: "silo",
+		validate(value) {
+			try {
+				extractStoredLinkRow(value);
+				return { value };
+			} catch (error) {
+				return failure(error instanceof Error ? error.message : "Expected a link row.");
+			}
+		}
+	} };
+}
 function createDoc(id, data) {
 	const doc = {};
 	Object.defineProperty(doc, "id", {
@@ -160,6 +330,19 @@ function getDatabase() {
         version INTEGER NOT NULL DEFAULT 1,
         PRIMARY KEY (source, id)
       );
+
+      CREATE TABLE IF NOT EXISTS links (
+        id TEXT PRIMARY KEY,
+        collections TEXT NOT NULL,
+        ids TEXT NOT NULL,
+        createdAt TEXT NOT NULL
+      );
+
+      CREATE UNIQUE INDEX IF NOT EXISTS links_collections_ids_idx
+      ON links(collections, ids);
+
+      CREATE INDEX IF NOT EXISTS links_collections_idx
+      ON links(collections);
     `);
 	}
 	return database;
@@ -211,11 +394,39 @@ function deleteRows(sourceName, mutations) {
 			if (mutation.original) deletedDocs.add(mutation.original);
 			deletedDocs.add(mutation.modified);
 			db.runSync(`DELETE FROM sources WHERE source = ? AND id = ?`, [sourceName, String(mutation.key)]);
+			deleteLinksForSourceRow(sourceName, String(mutation.key));
 		}
 	});
 	return Promise.resolve();
 }
+function loadLinkRows() {
+	return getDatabase().getAllSync(`SELECT id, collections, ids, createdAt FROM links`);
+}
+function insertLinkRow(row) {
+	getDatabase().runSync(`INSERT OR IGNORE INTO links (id, collections, ids, createdAt)
+     VALUES (?, ?, ?, ?)`, [
+		row.id,
+		row.collections,
+		row.ids,
+		row.createdAt
+	]);
+}
+function deleteLinkRow(id) {
+	getDatabase().runSync(`DELETE FROM links WHERE id = ?`, [id]);
+}
+function hasLinkRow(id) {
+	return !!getDatabase().getFirstSync(`SELECT id FROM links WHERE id = ?`, [id]);
+}
+function deleteLinksForSourceRow(sourceName, id) {
+	const rows = loadLinkRows();
+	for (const row of rows) {
+		const [firstCollection, secondCollection] = decodePair(row.collections);
+		const [firstId, secondId] = decodePair(row.ids);
+		if (firstCollection === sourceName && firstId === id || secondCollection === sourceName && secondId === id) deleteLinkRow(row.id);
+	}
+}
 
 //#endregion
+exports.createDatastore = createDatastore;
 exports.createID = createID;
 exports.source = source;

package/dist/source.d.cts

@@ -22,6 +22,30 @@ type SourceRow<T extends object> = Doc<T>;
 type SourceCollectionOptions<T extends object> = {
   startSync?: boolean;
 };
+type DatastoreDefaults<TCollections extends Record<string, object>> = { [Name in keyof TCollections]: SourceDefaults<TCollections[Name]> };
+type LinkRow<TName extends string = string> = {
+  readonly id: string;
+  readonly collections: string;
+  readonly ids: string;
+  readonly createdAt: string;
+} & { readonly [Other in TName]: { readonly [Current in TName]: {
+  readonly id: string | null;
+} } };
+type LinkUtils<TName extends string = string> = {
+  link(collectionA: TName, idA: string, collectionB: TName, idB: string): Promise<void>;
+  unlink(collectionA: TName, idA: string, collectionB: TName, idB: string): Promise<void>;
+  has(collectionA: TName, idA: string, collectionB: TName, idB: string): boolean;
+};
+type Datastore<TCollections extends Record<string, object>> = {
+  readonly names: ReadonlyArray<keyof TCollections & string>;
+  collectionOptions<Name$1 extends keyof TCollections & string>(name: Name$1, options?: SourceCollectionOptions<TCollections[Name$1]>): CollectionConfig<SourceRow<TCollections[Name$1]>, string, StandardSchemaV1<any, SourceRow<TCollections[Name$1]>>> & {
+    schema: StandardSchemaV1<any, SourceRow<TCollections[Name$1]>>;
+  };
+  linkCollectionOptions(options?: SourceCollectionOptions<LinkRow<keyof TCollections & string>>): CollectionConfig<LinkRow<keyof TCollections & string>, string, StandardSchemaV1<any, LinkRow<keyof TCollections & string>>, LinkUtils<keyof TCollections & string>> & {
+    schema: StandardSchemaV1<any, LinkRow<keyof TCollections & string>>;
+    utils: LinkUtils<keyof TCollections & string>;
+  };
+};
 type Source<T extends object> = {
   readonly name: string;
   readonly defaults: SourceDefaults<T>;
@@ -31,6 +55,7 @@ type Source<T extends object> = {
   };
 };
 declare function createID(): string;
+declare function createDatastore<TCollections extends Record<string, object>>(defaults: DatastoreDefaults<TCollections>): Datastore<TCollections>;
 declare function source<T extends object>(name: string, defaults: SourceDefaults<T>): Source<T>;
 //#endregion
-export { DefaultValue, Doc, DocumentData, FieldValue, Source, SourceCollectionOptions, SourceDefaults, SourceInput, SourceRow, createID, source };
+export { Datastore, DatastoreDefaults, DefaultValue, Doc, DocumentData, FieldValue, LinkRow, LinkUtils, Source, SourceCollectionOptions, SourceDefaults, SourceInput, SourceRow, createDatastore, createID, source };

package/dist/source.d.mts

@@ -22,6 +22,30 @@ type SourceRow<T extends object> = Doc<T>;
 type SourceCollectionOptions<T extends object> = {
   startSync?: boolean;
 };
+type DatastoreDefaults<TCollections extends Record<string, object>> = { [Name in keyof TCollections]: SourceDefaults<TCollections[Name]> };
+type LinkRow<TName extends string = string> = {
+  readonly id: string;
+  readonly collections: string;
+  readonly ids: string;
+  readonly createdAt: string;
+} & { readonly [Other in TName]: { readonly [Current in TName]: {
+  readonly id: string | null;
+} } };
+type LinkUtils<TName extends string = string> = {
+  link(collectionA: TName, idA: string, collectionB: TName, idB: string): Promise<void>;
+  unlink(collectionA: TName, idA: string, collectionB: TName, idB: string): Promise<void>;
+  has(collectionA: TName, idA: string, collectionB: TName, idB: string): boolean;
+};
+type Datastore<TCollections extends Record<string, object>> = {
+  readonly names: ReadonlyArray<keyof TCollections & string>;
+  collectionOptions<Name$1 extends keyof TCollections & string>(name: Name$1, options?: SourceCollectionOptions<TCollections[Name$1]>): CollectionConfig<SourceRow<TCollections[Name$1]>, string, StandardSchemaV1<any, SourceRow<TCollections[Name$1]>>> & {
+    schema: StandardSchemaV1<any, SourceRow<TCollections[Name$1]>>;
+  };
+  linkCollectionOptions(options?: SourceCollectionOptions<LinkRow<keyof TCollections & string>>): CollectionConfig<LinkRow<keyof TCollections & string>, string, StandardSchemaV1<any, LinkRow<keyof TCollections & string>>, LinkUtils<keyof TCollections & string>> & {
+    schema: StandardSchemaV1<any, LinkRow<keyof TCollections & string>>;
+    utils: LinkUtils<keyof TCollections & string>;
+  };
+};
 type Source<T extends object> = {
   readonly name: string;
   readonly defaults: SourceDefaults<T>;
@@ -31,6 +55,7 @@ type Source<T extends object> = {
   };
 };
 declare function createID(): string;
+declare function createDatastore<TCollections extends Record<string, object>>(defaults: DatastoreDefaults<TCollections>): Datastore<TCollections>;
 declare function source<T extends object>(name: string, defaults: SourceDefaults<T>): Source<T>;
 //#endregion
-export { DefaultValue, Doc, DocumentData, FieldValue, Source, SourceCollectionOptions, SourceDefaults, SourceInput, SourceRow, createID, source };
+export { Datastore, DatastoreDefaults, DefaultValue, Doc, DocumentData, FieldValue, LinkRow, LinkUtils, Source, SourceCollectionOptions, SourceDefaults, SourceInput, SourceRow, createDatastore, createID, source };

package/dist/source.mjs

@@ -13,49 +13,205 @@ const deletedDocs = /* @__PURE__ */ new WeakSet();
 function createID() {
 	return randomUUID();
 }
+function createDatastore(defaults) {
+	const names = Object.keys(defaults);
+	const nameSet = new Set(names);
+	for (const name of names) {
+		assertSourceName(name);
+		assertFlatDefaults(name, defaults[name]);
+	}
+	if (new Set(names).size !== names.length) throw new Error("Datastore collection names must be unique.");
+	return {
+		names,
+		collectionOptions(name, options = {}) {
+			assertDatastoreCollectionName(nameSet, name);
+			return createSourceCollectionOptions(name, defaults[name], options);
+		},
+		linkCollectionOptions(options = {}) {
+			return createLinkCollectionOptions(names, nameSet, options);
+		}
+	};
+}
 function source(name, defaults) {
 	assertSourceName(name);
 	assertFlatDefaults(name, defaults);
 	if (sourceNames.has(name)) throw new Error(`Source "${name}" is already registered. Define each source once and import the existing source instead.`);
 	sourceNames.add(name);
-	const schema = createSourceSchema(name, defaults);
 	return {
 		name,
 		defaults,
-		schema,
+		schema: createSourceSchema(name, defaults),
 		collectionOptions(options = {}) {
-			return {
-				id: name,
-				getKey: (item) => item.id,
-				schema,
-				startSync: options.startSync,
-				sync: { sync({ begin, write, commit, markReady, truncate }) {
-					const rows = loadRows(name);
-					begin();
-					truncate();
-					for (const row of rows) write({
-						type: "insert",
-						value: row
-					});
-					commit();
-					markReady();
-				} },
-				onInsert: async ({ transaction }) => {
-					await insertRows(name, transaction.mutations.map((mutation) => mutation.modified));
-				},
-				onUpdate: async ({ transaction }) => {
-					await updateRows(name, transaction.mutations);
-				},
-				onDelete: async ({ transaction }) => {
-					await deleteRows(name, transaction.mutations);
-				}
-			};
+			return createSourceCollectionOptions(name, defaults, options);
+		}
+	};
+}
+function createSourceCollectionOptions(name, defaults, options = {}) {
+	return {
+		id: name,
+		getKey: (item) => item.id,
+		schema: createSourceSchema(name, defaults),
+		startSync: options.startSync,
+		sync: { sync({ begin, write, commit, markReady, truncate }) {
+			const rows = loadRows(name);
+			begin();
+			truncate();
+			for (const row of rows) write({
+				type: "insert",
+				value: row
+			});
+			commit();
+			markReady();
+		} },
+		onInsert: async ({ transaction }) => {
+			await insertRows(name, transaction.mutations.map((mutation) => mutation.modified));
+		},
+		onUpdate: async ({ transaction }) => {
+			await updateRows(name, transaction.mutations);
+		},
+		onDelete: async ({ transaction }) => {
+			await deleteRows(name, transaction.mutations);
+		}
+	};
+}
+function createLinkCollectionOptions(names, nameSet, options = {}) {
+	const schema = createLinkSchema();
+	let syncBegin;
+	let syncWrite;
+	let syncCommit;
+	const writeSyncedLink = (type, row) => {
+		if (!syncBegin || !syncWrite || !syncCommit) return;
+		syncBegin();
+		syncWrite({
+			type,
+			value: row
+		});
+		syncCommit();
+	};
+	return {
+		id: "silo-links",
+		getKey: (item) => item.id,
+		schema,
+		startSync: options.startSync,
+		sync: { sync({ begin, write, commit, markReady, truncate }) {
+			syncBegin = begin;
+			syncWrite = write;
+			syncCommit = commit;
+			const rows = loadLinkRows().map((row) => createLinkRow(names, row));
+			begin();
+			truncate();
+			for (const row of rows) write({
+				type: "insert",
+				value: row
+			});
+			commit();
+			markReady();
+		} },
+		onInsert: async ({ transaction }) => {
+			for (const mutation of transaction.mutations) insertLinkRow(extractStoredLinkRow(mutation.modified));
+		},
+		onDelete: async ({ transaction }) => {
+			for (const mutation of transaction.mutations) deleteLinkRow(String(mutation.key));
+		},
+		utils: {
+			async link(collectionA, idA, collectionB, idB) {
+				const row = createStoredLinkRow(nameSet, collectionA, idA, collectionB, idB);
+				const exists = hasLinkRow(row.id);
+				insertLinkRow(row);
+				if (!exists) writeSyncedLink("insert", createLinkRow(names, row));
+			},
+			async unlink(collectionA, idA, collectionB, idB) {
+				const row = createStoredLinkRow(nameSet, collectionA, idA, collectionB, idB);
+				const exists = hasLinkRow(row.id);
+				deleteLinkRow(row.id);
+				if (exists) writeSyncedLink("delete", createLinkRow(names, row));
+			},
+			has(collectionA, idA, collectionB, idB) {
+				return hasLinkRow(createStoredLinkRow(nameSet, collectionA, idA, collectionB, idB).id);
+			}
 		}
 	};
 }
 function assertSourceName(name) {
 	if (!sourceNamePattern.test(name)) throw new Error(`Source names must start with a letter and contain only letters, numbers, underscores, or hyphens. Received "${name}".`);
 }
+function assertDatastoreCollectionName(nameSet, name) {
+	if (!nameSet.has(name)) throw new Error(`Datastore collection "${name}" is not registered.`);
+}
+function assertLinkCollectionName(nameSet, name) {
+	if (!nameSet.has(name)) throw new Error(`Cannot link unknown collection "${name}".`);
+}
+function createStoredLinkRow(nameSet, collectionA, idA, collectionB, idB) {
+	assertLinkCollectionName(nameSet, collectionA);
+	assertLinkCollectionName(nameSet, collectionB);
+	if (collectionA === collectionB) throw new Error(`Links between the same collection are not supported. Received "${collectionA}".`);
+	const [firstCollection, firstId, secondCollection, secondId] = collectionA < collectionB ? [
+		collectionA,
+		idA,
+		collectionB,
+		idB
+	] : [
+		collectionB,
+		idB,
+		collectionA,
+		idA
+	];
+	const collections = encodePair(firstCollection, secondCollection);
+	const ids = encodePair(firstId, secondId);
+	return {
+		id: encodePair(collections, ids),
+		collections,
+		ids,
+		createdAt: (/* @__PURE__ */ new Date()).toISOString()
+	};
+}
+function createLinkRow(names, row) {
+	const [firstCollection, secondCollection] = decodePair(row.collections);
+	const [firstId, secondId] = decodePair(row.ids);
+	const result = {
+		id: row.id,
+		collections: row.collections,
+		ids: row.ids,
+		createdAt: row.createdAt
+	};
+	for (const other of names) {
+		const byCurrent = {};
+		for (const current of names) {
+			let id = null;
+			if (other !== current) {
+				if (current === firstCollection && other === secondCollection) id = firstId;
+				else if (current === secondCollection && other === firstCollection) id = secondId;
+			}
+			byCurrent[current] = { id };
+		}
+		result[other] = byCurrent;
+	}
+	return result;
+}
+function extractStoredLinkRow(row) {
+	if (!isRecord(row)) throw new Error("Expected a link row object.");
+	if (typeof row.id !== "string" || typeof row.collections !== "string" || typeof row.ids !== "string" || typeof row.createdAt !== "string") throw new Error("Link rows must include string id, collections, ids, and createdAt fields.");
+	return {
+		id: row.id,
+		collections: row.collections,
+		ids: row.ids,
+		createdAt: row.createdAt
+	};
+}
+function encodePair(first, second) {
+	return `${encodePart(first)}:${encodePart(second)}`;
+}
+function decodePair(value) {
+	const parts = value.split(":");
+	if (parts.length !== 2) throw new Error(`Invalid encoded link pair "${value}".`);
+	return [decodePart(parts[0]), decodePart(parts[1])];
+}
+function encodePart(value) {
+	return encodeURIComponent(value);
+}
+function decodePart(value) {
+	return decodeURIComponent(value);
+}
 function assertFlatDefaults(sourceName, defaults) {
 	for (const [field, defaultValue] of Object.entries(defaults)) {
 		if (reservedDocumentFields.has(field)) throw new Error(`Source "${sourceName}" field "${field}" is reserved by Silo documents.`);
@@ -84,6 +240,20 @@ function createSourceSchema(sourceName, defaults) {
 		}
 	} };
 }
+function createLinkSchema() {
+	return { "~standard": {
+		version: 1,
+		vendor: "silo",
+		validate(value) {
+			try {
+				extractStoredLinkRow(value);
+				return { value };
+			} catch (error) {
+				return failure(error instanceof Error ? error.message : "Expected a link row.");
+			}
+		}
+	} };
+}
 function createDoc(id, data) {
 	const doc = {};
 	Object.defineProperty(doc, "id", {
@@ -159,6 +329,19 @@ function getDatabase() {
         version INTEGER NOT NULL DEFAULT 1,
         PRIMARY KEY (source, id)
       );
+
+      CREATE TABLE IF NOT EXISTS links (
+        id TEXT PRIMARY KEY,
+        collections TEXT NOT NULL,
+        ids TEXT NOT NULL,
+        createdAt TEXT NOT NULL
+      );
+
+      CREATE UNIQUE INDEX IF NOT EXISTS links_collections_ids_idx
+      ON links(collections, ids);
+
+      CREATE INDEX IF NOT EXISTS links_collections_idx
+      ON links(collections);
     `);
 	}
 	return database;
@@ -210,10 +393,37 @@ function deleteRows(sourceName, mutations) {
 			if (mutation.original) deletedDocs.add(mutation.original);
 			deletedDocs.add(mutation.modified);
 			db.runSync(`DELETE FROM sources WHERE source = ? AND id = ?`, [sourceName, String(mutation.key)]);
+			deleteLinksForSourceRow(sourceName, String(mutation.key));
 		}
 	});
 	return Promise.resolve();
 }
+function loadLinkRows() {
+	return getDatabase().getAllSync(`SELECT id, collections, ids, createdAt FROM links`);
+}
+function insertLinkRow(row) {
+	getDatabase().runSync(`INSERT OR IGNORE INTO links (id, collections, ids, createdAt)
+     VALUES (?, ?, ?, ?)`, [
+		row.id,
+		row.collections,
+		row.ids,
+		row.createdAt
+	]);
+}
+function deleteLinkRow(id) {
+	getDatabase().runSync(`DELETE FROM links WHERE id = ?`, [id]);
+}
+function hasLinkRow(id) {
+	return !!getDatabase().getFirstSync(`SELECT id FROM links WHERE id = ?`, [id]);
+}
+function deleteLinksForSourceRow(sourceName, id) {
+	const rows = loadLinkRows();
+	for (const row of rows) {
+		const [firstCollection, secondCollection] = decodePair(row.collections);
+		const [firstId, secondId] = decodePair(row.ids);
+		if (firstCollection === sourceName && firstId === id || secondCollection === sourceName && secondId === id) deleteLinkRow(row.id);
+	}
+}
 
 //#endregion
-export { createID, source };
+export { createDatastore, createID, source };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "silosdk",
-  "version": "0.0.6",
+  "version": "0.0.7",
   "type": "module",
   "scripts": {
     "build": "tsdown",