silosdk 0.0.3 → 0.0.5

package/README.md

@@ -0,0 +1,180 @@
+# Silo SDK
+
+Silo SDK provides local-first persistence primitives for Expo apps. It owns local
+storage and returns TanStack-compatible option objects instead of wrapping
+TanStack hooks.
+
+Silo owns:
+
+- SQLite persistence
+- flat primitive document constraints
+- defaults-first source shape
+- settings storage
+- media file ownership and resolution
+
+TanStack owns:
+
+- `createCollection()` and live collection queries
+- `useQuery()` and `useMutation()`
+- query and mutation state
+
+## Install
+
+```sh
+yarn add silosdk @tanstack/react-db @tanstack/react-query expo-sqlite expo-file-system
+```
+
+## Sources
+
+Sources are SQLite-backed document stores that produce options for TanStack DB
+collections.
+
+```ts
+import { createCollection } from '@tanstack/react-db'
+import { createID, source } from 'silosdk/source'
+
+type Post = {
+  title: string
+  body: string
+  published: boolean
+  coverImage: string | null
+}
+
+export const postsSource = source<Post>('posts', {
+  title: '',
+  body: '',
+  published: false,
+  coverImage: null,
+})
+
+export const posts = createCollection(postsSource.collectionOptions())
+```
+
+Query and mutate with TanStack DB directly:
+
+```tsx
+import { eq, useLiveQuery } from '@tanstack/react-db'
+
+const { data: docs = [] } = useLiveQuery((q) =>
+  q.from({ posts }).where(({ posts }) => eq(posts.published, true)),
+)
+
+const doc = docs[0]
+const post = doc?.data()
+
+doc?.id
+post?.title
+```
+
+```ts
+const id = createID()
+
+const tx = posts.insert({
+  id,
+  data: {
+    title: 'Hello',
+    body: '',
+    published: false,
+    coverImage: null,
+  },
+})
+
+await tx.isPersisted.promise
+
+await posts.update(id, (doc) => {
+  doc.set({ published: true })
+}).isPersisted.promise
+
+await posts.delete(id).isPersisted.promise
+```
+
+Source rows are intentionally flat. Field values must be:
+
+```ts
+type FieldValue = string | number | boolean | null
+```
+
+## Settings
+
+Settings are small persisted primitive values backed by `expo-sqlite/kv-store`.
+They produce TanStack Query options.
+
+```ts
+import { setting } from 'silosdk/settings'
+
+export const theme = setting<'system' | 'light' | 'dark'>('theme', 'system')
+export const reduceMotion = setting('reduceMotion', false)
+```
+
+```tsx
+import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query'
+
+const queryClient = useQueryClient()
+const { data: value } = useQuery(theme.queryOptions())
+const setTheme = useMutation(theme.mutationOptions({ queryClient }))
+
+setTheme.mutate('dark')
+setTheme.mutate((current) => (current === 'dark' ? 'light' : 'dark'))
+```
+
+Setting values must also be flat primitives:
+
+```ts
+type SettingValue = string | number | boolean | null
+```
+
+## Media
+
+Media is singleton infrastructure for app-owned files. Domain documents store
+stable media refs as plain strings, keeping source rows flat.
+
+```ts
+import { media, type MediaRef } from 'silosdk/media'
+```
+
+Import a file with TanStack Query mutation options:
+
+```tsx
+import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query'
+
+const queryClient = useQueryClient()
+const importMedia = useMutation(media.mutationOptions({ queryClient }))
+
+const coverImage = await importMedia.mutateAsync({
+  uri: pickedFile.uri,
+  kind: 'image',
+  name: pickedFile.name,
+  mimeType: pickedFile.type,
+})
+```
+
+Store the returned `media://...` ref in source rows:
+
+```ts
+posts.update(postId, (draft) => {
+  draft.set({ coverImage })
+})
+```
+
+Resolve a media ref to a local file URI:
+
+```tsx
+const { data: uri } = useQuery(media.queryOptions(post.coverImage))
+```
+
+`media.queryOptions()` returns `string | null`. It returns `null` when the ref is
+empty, invalid, unknown, or missing on disk.
+
+## API Shape
+
+Silo exposes definition objects and option factories:
+
+```ts
+createCollection(postsSource.collectionOptions())
+useQuery(theme.queryOptions())
+useMutation(theme.mutationOptions({ queryClient }))
+useQuery(media.queryOptions(ref))
+useMutation(media.mutationOptions({ queryClient }))
+```
+
+There is no Silo provider and no Silo hook wrapper API.

package/dist/media.cjs

@@ -0,0 +1,135 @@
+const require_rolldown_runtime = require('./_virtual/rolldown_runtime.cjs');
+let expo_sqlite = require("expo-sqlite");
+let nanoid = require("nanoid");
+let __tanstack_react_query = require("@tanstack/react-query");
+let expo_file_system = require("expo-file-system");
+
+//#region src/media/index.ts
+const media = {
+	queryOptions(ref) {
+		return (0, __tanstack_react_query.queryOptions)({
+			queryKey: mediaQueryKey(ref),
+			queryFn: () => resolveMediaUri(ref)
+		});
+	},
+	mutationOptions(options = {}) {
+		return (0, __tanstack_react_query.mutationOptions)({
+			mutationKey: [
+				"silo",
+				"media",
+				"import"
+			],
+			mutationFn: async (input) => {
+				const imported = await importMedia(input);
+				options.queryClient?.setQueryData(mediaQueryKey(imported.ref), imported.uri);
+				return imported.ref;
+			}
+		});
+	}
+};
+function isMediaRef(value) {
+	return typeof value === "string" && value.startsWith("media://");
+}
+function mediaQueryKey(ref) {
+	return [
+		"silo",
+		"media",
+		ref ?? null
+	];
+}
+async function importMedia(input) {
+	assertMediaKind(input.kind);
+	const id = (0, nanoid.nanoid)();
+	const ref = createMediaRef(input.kind, id);
+	const source = new expo_file_system.File(input.uri);
+	const name = input.name ?? source.name ?? `${id}${source.extension}`;
+	const destinationDirectory = mediaDirectory(input.kind);
+	destinationDirectory.create({
+		idempotent: true,
+		intermediates: true
+	});
+	const destination = new expo_file_system.File(destinationDirectory, `${id}${extensionFor(name)}`);
+	await source.copy(destination);
+	const info = destination.info();
+	const mimeType = input.mimeType ?? (destination.type || null);
+	const size = info.size ?? destination.size;
+	const timestamp = (/* @__PURE__ */ new Date()).toISOString();
+	insertMediaFile({
+		ref,
+		uri: destination.uri,
+		kind: input.kind,
+		name,
+		mimeType,
+		size,
+		createdAt: timestamp,
+		data: input.data ?? {}
+	});
+	return {
+		ref,
+		uri: destination.uri
+	};
+}
+function resolveMediaUri(ref) {
+	if (!isMediaRef(ref)) return null;
+	const row = getDatabase().getFirstSync(`SELECT ref, uri FROM media_files WHERE ref = ?`, [ref]);
+	if (!row) return null;
+	return new expo_file_system.File(row.uri).exists ? row.uri : null;
+}
+function createMediaRef(kind, id) {
+	return `media://silo/${kindDirectoryName(kind)}/${id}`;
+}
+function mediaDirectory(kind) {
+	return new expo_file_system.Directory(expo_file_system.Paths.document, "silo", "media", kindDirectoryName(kind));
+}
+function kindDirectoryName(kind) {
+	switch (kind) {
+		case "image": return "images";
+		case "video": return "videos";
+		case "audio": return "audio";
+		case "file": return "files";
+	}
+}
+function extensionFor(name) {
+	return name.match(/\.[A-Za-z0-9]+$/)?.[0] ?? "";
+}
+function assertMediaKind(kind) {
+	if (kind !== "image" && kind !== "video" && kind !== "audio" && kind !== "file") throw new Error("Media kind must be one of \"image\", \"video\", \"audio\", or \"file\".");
+}
+let database;
+function getDatabase() {
+	if (!database) {
+		database = (0, expo_sqlite.openDatabaseSync)("silo.db");
+		database.execSync(`
+      PRAGMA journal_mode = WAL;
+
+      CREATE TABLE IF NOT EXISTS media_files (
+        ref TEXT PRIMARY KEY,
+        uri TEXT NOT NULL,
+        kind TEXT NOT NULL,
+        name TEXT NOT NULL,
+        mimeType TEXT,
+        size INTEGER NOT NULL,
+        createdAt TEXT NOT NULL,
+        data TEXT NOT NULL
+      );
+    `);
+	}
+	return database;
+}
+function insertMediaFile(file) {
+	getDatabase().runSync(`INSERT INTO media_files (ref, uri, kind, name, mimeType, size, createdAt, data)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?)`, [
+		file.ref,
+		file.uri,
+		file.kind,
+		file.name,
+		file.mimeType,
+		file.size,
+		file.createdAt,
+		JSON.stringify(file.data)
+	]);
+}
+
+//#endregion
+exports.isMediaRef = isMediaRef;
+exports.media = media;

package/dist/media.d.cts

@@ -0,0 +1,29 @@
+import { QueryClient, UseMutationOptions, UseQueryOptions } from "@tanstack/react-query";
+
+//#region src/media/index.d.ts
+type MediaRef = `media://${string}`;
+type MediaKind = 'image' | 'video' | 'audio' | 'file';
+type MediaJson = string | number | boolean | null | MediaJson[] | {
+  [key: string]: MediaJson;
+};
+type MediaData = {
+  [key: string]: MediaJson;
+};
+type MediaImportInput = {
+  uri: string;
+  kind: MediaKind;
+  name?: string;
+  mimeType?: string | null;
+  data?: MediaData;
+};
+type MediaQueryKey = readonly ['silo', 'media', MediaRef | string | null];
+type MediaMutationOptions = {
+  queryClient?: QueryClient;
+};
+declare const media: {
+  queryOptions(ref: MediaRef | string | null | undefined): UseQueryOptions<string | null, Error, string | null, MediaQueryKey>;
+  mutationOptions(options?: MediaMutationOptions): UseMutationOptions<MediaRef, Error, MediaImportInput>;
+};
+declare function isMediaRef(value: unknown): value is MediaRef;
+//#endregion
+export { MediaData, MediaImportInput, MediaJson, MediaKind, MediaMutationOptions, MediaQueryKey, MediaRef, isMediaRef, media };

package/dist/media.d.mts

@@ -0,0 +1,29 @@
+import { QueryClient, UseMutationOptions, UseQueryOptions } from "@tanstack/react-query";
+
+//#region src/media/index.d.ts
+type MediaRef = `media://${string}`;
+type MediaKind = 'image' | 'video' | 'audio' | 'file';
+type MediaJson = string | number | boolean | null | MediaJson[] | {
+  [key: string]: MediaJson;
+};
+type MediaData = {
+  [key: string]: MediaJson;
+};
+type MediaImportInput = {
+  uri: string;
+  kind: MediaKind;
+  name?: string;
+  mimeType?: string | null;
+  data?: MediaData;
+};
+type MediaQueryKey = readonly ['silo', 'media', MediaRef | string | null];
+type MediaMutationOptions = {
+  queryClient?: QueryClient;
+};
+declare const media: {
+  queryOptions(ref: MediaRef | string | null | undefined): UseQueryOptions<string | null, Error, string | null, MediaQueryKey>;
+  mutationOptions(options?: MediaMutationOptions): UseMutationOptions<MediaRef, Error, MediaImportInput>;
+};
+declare function isMediaRef(value: unknown): value is MediaRef;
+//#endregion
+export { MediaData, MediaImportInput, MediaJson, MediaKind, MediaMutationOptions, MediaQueryKey, MediaRef, isMediaRef, media };

package/dist/media.mjs

@@ -0,0 +1,133 @@
+import { openDatabaseSync } from "expo-sqlite";
+import { nanoid } from "nanoid";
+import { mutationOptions, queryOptions } from "@tanstack/react-query";
+import { Directory, File, Paths } from "expo-file-system";
+
+//#region src/media/index.ts
+const media = {
+	queryOptions(ref) {
+		return queryOptions({
+			queryKey: mediaQueryKey(ref),
+			queryFn: () => resolveMediaUri(ref)
+		});
+	},
+	mutationOptions(options = {}) {
+		return mutationOptions({
+			mutationKey: [
+				"silo",
+				"media",
+				"import"
+			],
+			mutationFn: async (input) => {
+				const imported = await importMedia(input);
+				options.queryClient?.setQueryData(mediaQueryKey(imported.ref), imported.uri);
+				return imported.ref;
+			}
+		});
+	}
+};
+function isMediaRef(value) {
+	return typeof value === "string" && value.startsWith("media://");
+}
+function mediaQueryKey(ref) {
+	return [
+		"silo",
+		"media",
+		ref ?? null
+	];
+}
+async function importMedia(input) {
+	assertMediaKind(input.kind);
+	const id = nanoid();
+	const ref = createMediaRef(input.kind, id);
+	const source = new File(input.uri);
+	const name = input.name ?? source.name ?? `${id}${source.extension}`;
+	const destinationDirectory = mediaDirectory(input.kind);
+	destinationDirectory.create({
+		idempotent: true,
+		intermediates: true
+	});
+	const destination = new File(destinationDirectory, `${id}${extensionFor(name)}`);
+	await source.copy(destination);
+	const info = destination.info();
+	const mimeType = input.mimeType ?? (destination.type || null);
+	const size = info.size ?? destination.size;
+	const timestamp = (/* @__PURE__ */ new Date()).toISOString();
+	insertMediaFile({
+		ref,
+		uri: destination.uri,
+		kind: input.kind,
+		name,
+		mimeType,
+		size,
+		createdAt: timestamp,
+		data: input.data ?? {}
+	});
+	return {
+		ref,
+		uri: destination.uri
+	};
+}
+function resolveMediaUri(ref) {
+	if (!isMediaRef(ref)) return null;
+	const row = getDatabase().getFirstSync(`SELECT ref, uri FROM media_files WHERE ref = ?`, [ref]);
+	if (!row) return null;
+	return new File(row.uri).exists ? row.uri : null;
+}
+function createMediaRef(kind, id) {
+	return `media://silo/${kindDirectoryName(kind)}/${id}`;
+}
+function mediaDirectory(kind) {
+	return new Directory(Paths.document, "silo", "media", kindDirectoryName(kind));
+}
+function kindDirectoryName(kind) {
+	switch (kind) {
+		case "image": return "images";
+		case "video": return "videos";
+		case "audio": return "audio";
+		case "file": return "files";
+	}
+}
+function extensionFor(name) {
+	return name.match(/\.[A-Za-z0-9]+$/)?.[0] ?? "";
+}
+function assertMediaKind(kind) {
+	if (kind !== "image" && kind !== "video" && kind !== "audio" && kind !== "file") throw new Error("Media kind must be one of \"image\", \"video\", \"audio\", or \"file\".");
+}
+let database;
+function getDatabase() {
+	if (!database) {
+		database = openDatabaseSync("silo.db");
+		database.execSync(`
+      PRAGMA journal_mode = WAL;
+
+      CREATE TABLE IF NOT EXISTS media_files (
+        ref TEXT PRIMARY KEY,
+        uri TEXT NOT NULL,
+        kind TEXT NOT NULL,
+        name TEXT NOT NULL,
+        mimeType TEXT,
+        size INTEGER NOT NULL,
+        createdAt TEXT NOT NULL,
+        data TEXT NOT NULL
+      );
+    `);
+	}
+	return database;
+}
+function insertMediaFile(file) {
+	getDatabase().runSync(`INSERT INTO media_files (ref, uri, kind, name, mimeType, size, createdAt, data)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?)`, [
+		file.ref,
+		file.uri,
+		file.kind,
+		file.name,
+		file.mimeType,
+		file.size,
+		file.createdAt,
+		JSON.stringify(file.data)
+	]);
+}
+
+//#endregion
+export { isMediaRef, media };

package/dist/source.cjs

@@ -1,9 +1,19 @@
 const require_rolldown_runtime = require('./_virtual/rolldown_runtime.cjs');
 let expo_sqlite = require("expo-sqlite");
+let nanoid = require("nanoid");
 
 //#region src/source/index.ts
 const sourceNames = /* @__PURE__ */ new Set();
 const sourceNamePattern = /^[A-Za-z][A-Za-z0-9_-]*$/;
+const reservedDocumentFields = new Set([
+	"id",
+	"data",
+	"set"
+]);
+const deletedDocs = /* @__PURE__ */ new WeakSet();
+function createID() {
+	return (0, nanoid.nanoid)();
+}
 function source(name, defaults) {
 	assertSourceName(name);
 	assertFlatDefaults(name, defaults);
@@ -38,7 +48,7 @@ function source(name, defaults) {
 					await updateRows(name, transaction.mutations);
 				},
 				onDelete: async ({ transaction }) => {
-					await deleteRows(name, transaction.mutations.map((mutation) => mutation.key));
+					await deleteRows(name, transaction.mutations);
 				}
 			};
 		}
@@ -48,7 +58,10 @@ 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 assertFlatDefaults(sourceName, defaults) {
-	for (const [field, defaultValue] of Object.entries(defaults)) if (!isFieldValue(resolveDefault(defaultValue))) throw new Error(`Source "${sourceName}" field "${field}" must default to a string, number, boolean, null, or a function returning one of those values.`);
+	for (const [field, defaultValue] of Object.entries(defaults)) {
+		if (reservedDocumentFields.has(field)) throw new Error(`Source "${sourceName}" field "${field}" is reserved by Silo documents.`);
+		if (!isFieldValue(resolveDefault(defaultValue))) throw new Error(`Source "${sourceName}" field "${field}" must default to a string, number, boolean, null, or a function returning one of those values.`);
+	}
 }
 function createSourceSchema(sourceName, defaults) {
 	return { "~standard": {
@@ -56,21 +69,64 @@ function createSourceSchema(sourceName, defaults) {
 		vendor: "silo",
 		validate(value) {
 			if (!isRecord(value)) return failure("Expected a flat source row object.");
-			if (typeof value.id !== "string") return failure("Expected source row field \"id\" to be a string.", ["id"]);
-			const row = { id: value.id };
-			for (const [field, fieldValue] of Object.entries(value)) {
-				if (field === "id") continue;
-				if (!isFieldValue(fieldValue)) return failure(`Source "${sourceName}" field "${field}" must be a string, number, boolean, or null.`, [field]);
-				row[field] = fieldValue;
+			if (typeof value.id !== "string") return failure("Expected source document field \"id\" to be a string.", ["id"]);
+			const inputData = isRecord(value.data) ? value.data : extractDocumentData(value);
+			const data = {};
+			for (const [field, fieldValue] of Object.entries(inputData)) {
+				if (reservedDocumentFields.has(field)) return failure(`Source "${sourceName}" field "${field}" is reserved by Silo documents.`, ["data", field]);
+				if (!isFieldValue(fieldValue)) return failure(`Source "${sourceName}" field "${field}" must be a string, number, boolean, or null.`, ["data", field]);
+				data[field] = fieldValue;
 			}
 			for (const [field, defaultValue] of Object.entries(defaults)) {
-				if (field in row) continue;
-				row[field] = resolveDefault(defaultValue);
+				if (field in data) continue;
+				data[field] = resolveDefault(defaultValue);
 			}
-			return { value: row };
+			return { value: createDoc(value.id, data) };
 		}
 	} };
 }
+function createDoc(id, data) {
+	const doc = {};
+	Object.defineProperty(doc, "id", {
+		value: id,
+		enumerable: true,
+		writable: false,
+		configurable: false
+	});
+	for (const [field, value] of Object.entries(data)) Object.defineProperty(doc, field, {
+		value,
+		enumerable: true,
+		writable: true,
+		configurable: true
+	});
+	Object.defineProperty(doc, "data", {
+		value() {
+			return deletedDocs.has(this) ? null : extractDocumentData(this);
+		},
+		enumerable: true,
+		writable: false,
+		configurable: false
+	});
+	Object.defineProperty(doc, "set", {
+		get() {
+			return function setDocumentData(patch) {
+				Object.assign(this, patch);
+			};
+		},
+		enumerable: true,
+		configurable: false
+	});
+	return doc;
+}
+function extractDocumentData(value) {
+	if (!isRecord(value)) return {};
+	const data = {};
+	for (const [field, fieldValue] of Object.entries(value)) {
+		if (reservedDocumentFields.has(field) || field.startsWith("$") || typeof fieldValue === "function") continue;
+		if (isFieldValue(fieldValue)) data[field] = fieldValue;
+	}
+	return data;
+}
 function resolveDefault(value) {
 	const resolved = typeof value === "function" ? value() : value;
 	if (!isFieldValue(resolved)) throw new Error("Source defaults must resolve to a string, number, boolean, or null.");
@@ -109,21 +165,18 @@ function getDatabase() {
 	return database;
 }
 function loadRows(sourceName) {
-	return getDatabase().getAllSync(`SELECT id, data FROM sources WHERE source = ?`, [sourceName]).map((row) => ({
-		id: row.id,
-		...JSON.parse(row.data)
-	}));
+	return getDatabase().getAllSync(`SELECT id, data FROM sources WHERE source = ?`, [sourceName]).map((row) => createDoc(row.id, JSON.parse(row.data)));
 }
 function insertRows(sourceName, rows) {
 	const db = getDatabase();
 	const timestamp = (/* @__PURE__ */ new Date()).toISOString();
 	db.withTransactionSync(() => {
 		for (const row of rows) {
-			const { id, ...data } = row;
+			const data = extractDocumentData(row);
 			db.runSync(`INSERT INTO sources (source, id, data, createdAt, updatedAt, version)
          VALUES (?, ?, ?, ?, ?, 1)`, [
 				sourceName,
-				id,
+				row.id,
 				JSON.stringify(data),
 				timestamp,
 				timestamp
@@ -137,7 +190,8 @@ function updateRows(sourceName, mutations) {
 	const timestamp = (/* @__PURE__ */ new Date()).toISOString();
 	db.withTransactionSync(() => {
 		for (const mutation of mutations) {
-			const { id, ...data } = mutation.modified;
+			const data = extractDocumentData(mutation.modified);
+			mutation.modified = createDoc(String(mutation.key), data);
 			db.runSync(`UPDATE sources
          SET data = ?, updatedAt = ?, version = version + 1
          WHERE source = ? AND id = ?`, [
@@ -150,13 +204,18 @@ function updateRows(sourceName, mutations) {
 	});
 	return Promise.resolve();
 }
-function deleteRows(sourceName, ids) {
+function deleteRows(sourceName, mutations) {
 	const db = getDatabase();
 	db.withTransactionSync(() => {
-		for (const id of ids) db.runSync(`DELETE FROM sources WHERE source = ? AND id = ?`, [sourceName, String(id)]);
+		for (const mutation of 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)]);
+		}
 	});
 	return Promise.resolve();
 }
 
 //#endregion
+exports.createID = createID;
 exports.source = source;

package/dist/source.d.cts

@@ -9,21 +9,28 @@ type InvalidDocumentKeys<T extends object> = { [K in keyof T]-?: Exclude<T[K], u
 type DocumentData<T extends object> = InvalidDocumentKeys<T> extends never ? T : never;
 type DefaultValue<T> = Exclude<T, undefined> | (() => Exclude<T, undefined>);
 type SourceDefaults<T extends object> = { [K in RequiredKeys<DocumentData<T>>]: DefaultValue<DocumentData<T>[K]> } & { [K in OptionalKeys<DocumentData<T>>]?: DefaultValue<DocumentData<T>[K]> };
-type SourceRow<T extends object> = {
-  id: string;
-} & DocumentData<T>;
 type SourceInput<T extends object> = {
   id: string;
-} & Partial<DocumentData<T>>;
+  data: Partial<DocumentData<T>>;
+};
+type Doc<T extends object> = {
+  readonly id: string;
+  data(): DocumentData<T> | null;
+  readonly set: (patch: Partial<DocumentData<T>>) => void;
+} & DocumentData<T>;
+type SourceRow<T extends object> = Doc<T>;
 type SourceCollectionOptions<T extends object> = {
   startSync?: boolean;
 };
 type Source<T extends object> = {
   readonly name: string;
   readonly defaults: SourceDefaults<T>;
-  readonly schema: StandardSchemaV1<SourceInput<T>, SourceRow<T>>;
-  collectionOptions(options?: SourceCollectionOptions<T>): CollectionConfig<SourceRow<T>, string, StandardSchemaV1<SourceInput<T>, SourceRow<T>>>;
+  readonly schema: StandardSchemaV1<any, SourceRow<T>>;
+  collectionOptions(options?: SourceCollectionOptions<T>): CollectionConfig<SourceRow<T>, string, StandardSchemaV1<any, SourceRow<T>>> & {
+    schema: StandardSchemaV1<any, SourceRow<T>>;
+  };
 };
+declare function createID(): string;
 declare function source<T extends object>(name: string, defaults: SourceDefaults<T>): Source<T>;
 //#endregion
-export { DefaultValue, DocumentData, FieldValue, Source, SourceCollectionOptions, SourceDefaults, SourceInput, SourceRow, source };
+export { DefaultValue, Doc, DocumentData, FieldValue, Source, SourceCollectionOptions, SourceDefaults, SourceInput, SourceRow, createID, source };

package/dist/source.d.mts

@@ -9,21 +9,28 @@ type InvalidDocumentKeys<T extends object> = { [K in keyof T]-?: Exclude<T[K], u
 type DocumentData<T extends object> = InvalidDocumentKeys<T> extends never ? T : never;
 type DefaultValue<T> = Exclude<T, undefined> | (() => Exclude<T, undefined>);
 type SourceDefaults<T extends object> = { [K in RequiredKeys<DocumentData<T>>]: DefaultValue<DocumentData<T>[K]> } & { [K in OptionalKeys<DocumentData<T>>]?: DefaultValue<DocumentData<T>[K]> };
-type SourceRow<T extends object> = {
-  id: string;
-} & DocumentData<T>;
 type SourceInput<T extends object> = {
   id: string;
-} & Partial<DocumentData<T>>;
+  data: Partial<DocumentData<T>>;
+};
+type Doc<T extends object> = {
+  readonly id: string;
+  data(): DocumentData<T> | null;
+  readonly set: (patch: Partial<DocumentData<T>>) => void;
+} & DocumentData<T>;
+type SourceRow<T extends object> = Doc<T>;
 type SourceCollectionOptions<T extends object> = {
   startSync?: boolean;
 };
 type Source<T extends object> = {
   readonly name: string;
   readonly defaults: SourceDefaults<T>;
-  readonly schema: StandardSchemaV1<SourceInput<T>, SourceRow<T>>;
-  collectionOptions(options?: SourceCollectionOptions<T>): CollectionConfig<SourceRow<T>, string, StandardSchemaV1<SourceInput<T>, SourceRow<T>>>;
+  readonly schema: StandardSchemaV1<any, SourceRow<T>>;
+  collectionOptions(options?: SourceCollectionOptions<T>): CollectionConfig<SourceRow<T>, string, StandardSchemaV1<any, SourceRow<T>>> & {
+    schema: StandardSchemaV1<any, SourceRow<T>>;
+  };
 };
+declare function createID(): string;
 declare function source<T extends object>(name: string, defaults: SourceDefaults<T>): Source<T>;
 //#endregion
-export { DefaultValue, DocumentData, FieldValue, Source, SourceCollectionOptions, SourceDefaults, SourceInput, SourceRow, source };
+export { DefaultValue, Doc, DocumentData, FieldValue, Source, SourceCollectionOptions, SourceDefaults, SourceInput, SourceRow, createID, source };

package/dist/source.mjs

@@ -1,8 +1,18 @@
 import { openDatabaseSync } from "expo-sqlite";
+import { nanoid } from "nanoid";
 
 //#region src/source/index.ts
 const sourceNames = /* @__PURE__ */ new Set();
 const sourceNamePattern = /^[A-Za-z][A-Za-z0-9_-]*$/;
+const reservedDocumentFields = new Set([
+	"id",
+	"data",
+	"set"
+]);
+const deletedDocs = /* @__PURE__ */ new WeakSet();
+function createID() {
+	return nanoid();
+}
 function source(name, defaults) {
 	assertSourceName(name);
 	assertFlatDefaults(name, defaults);
@@ -37,7 +47,7 @@ function source(name, defaults) {
 					await updateRows(name, transaction.mutations);
 				},
 				onDelete: async ({ transaction }) => {
-					await deleteRows(name, transaction.mutations.map((mutation) => mutation.key));
+					await deleteRows(name, transaction.mutations);
 				}
 			};
 		}
@@ -47,7 +57,10 @@ 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 assertFlatDefaults(sourceName, defaults) {
-	for (const [field, defaultValue] of Object.entries(defaults)) if (!isFieldValue(resolveDefault(defaultValue))) throw new Error(`Source "${sourceName}" field "${field}" must default to a string, number, boolean, null, or a function returning one of those values.`);
+	for (const [field, defaultValue] of Object.entries(defaults)) {
+		if (reservedDocumentFields.has(field)) throw new Error(`Source "${sourceName}" field "${field}" is reserved by Silo documents.`);
+		if (!isFieldValue(resolveDefault(defaultValue))) throw new Error(`Source "${sourceName}" field "${field}" must default to a string, number, boolean, null, or a function returning one of those values.`);
+	}
 }
 function createSourceSchema(sourceName, defaults) {
 	return { "~standard": {
@@ -55,21 +68,64 @@ function createSourceSchema(sourceName, defaults) {
 		vendor: "silo",
 		validate(value) {
 			if (!isRecord(value)) return failure("Expected a flat source row object.");
-			if (typeof value.id !== "string") return failure("Expected source row field \"id\" to be a string.", ["id"]);
-			const row = { id: value.id };
-			for (const [field, fieldValue] of Object.entries(value)) {
-				if (field === "id") continue;
-				if (!isFieldValue(fieldValue)) return failure(`Source "${sourceName}" field "${field}" must be a string, number, boolean, or null.`, [field]);
-				row[field] = fieldValue;
+			if (typeof value.id !== "string") return failure("Expected source document field \"id\" to be a string.", ["id"]);
+			const inputData = isRecord(value.data) ? value.data : extractDocumentData(value);
+			const data = {};
+			for (const [field, fieldValue] of Object.entries(inputData)) {
+				if (reservedDocumentFields.has(field)) return failure(`Source "${sourceName}" field "${field}" is reserved by Silo documents.`, ["data", field]);
+				if (!isFieldValue(fieldValue)) return failure(`Source "${sourceName}" field "${field}" must be a string, number, boolean, or null.`, ["data", field]);
+				data[field] = fieldValue;
 			}
 			for (const [field, defaultValue] of Object.entries(defaults)) {
-				if (field in row) continue;
-				row[field] = resolveDefault(defaultValue);
+				if (field in data) continue;
+				data[field] = resolveDefault(defaultValue);
 			}
-			return { value: row };
+			return { value: createDoc(value.id, data) };
 		}
 	} };
 }
+function createDoc(id, data) {
+	const doc = {};
+	Object.defineProperty(doc, "id", {
+		value: id,
+		enumerable: true,
+		writable: false,
+		configurable: false
+	});
+	for (const [field, value] of Object.entries(data)) Object.defineProperty(doc, field, {
+		value,
+		enumerable: true,
+		writable: true,
+		configurable: true
+	});
+	Object.defineProperty(doc, "data", {
+		value() {
+			return deletedDocs.has(this) ? null : extractDocumentData(this);
+		},
+		enumerable: true,
+		writable: false,
+		configurable: false
+	});
+	Object.defineProperty(doc, "set", {
+		get() {
+			return function setDocumentData(patch) {
+				Object.assign(this, patch);
+			};
+		},
+		enumerable: true,
+		configurable: false
+	});
+	return doc;
+}
+function extractDocumentData(value) {
+	if (!isRecord(value)) return {};
+	const data = {};
+	for (const [field, fieldValue] of Object.entries(value)) {
+		if (reservedDocumentFields.has(field) || field.startsWith("$") || typeof fieldValue === "function") continue;
+		if (isFieldValue(fieldValue)) data[field] = fieldValue;
+	}
+	return data;
+}
 function resolveDefault(value) {
 	const resolved = typeof value === "function" ? value() : value;
 	if (!isFieldValue(resolved)) throw new Error("Source defaults must resolve to a string, number, boolean, or null.");
@@ -108,21 +164,18 @@ function getDatabase() {
 	return database;
 }
 function loadRows(sourceName) {
-	return getDatabase().getAllSync(`SELECT id, data FROM sources WHERE source = ?`, [sourceName]).map((row) => ({
-		id: row.id,
-		...JSON.parse(row.data)
-	}));
+	return getDatabase().getAllSync(`SELECT id, data FROM sources WHERE source = ?`, [sourceName]).map((row) => createDoc(row.id, JSON.parse(row.data)));
 }
 function insertRows(sourceName, rows) {
 	const db = getDatabase();
 	const timestamp = (/* @__PURE__ */ new Date()).toISOString();
 	db.withTransactionSync(() => {
 		for (const row of rows) {
-			const { id, ...data } = row;
+			const data = extractDocumentData(row);
 			db.runSync(`INSERT INTO sources (source, id, data, createdAt, updatedAt, version)
          VALUES (?, ?, ?, ?, ?, 1)`, [
 				sourceName,
-				id,
+				row.id,
 				JSON.stringify(data),
 				timestamp,
 				timestamp
@@ -136,7 +189,8 @@ function updateRows(sourceName, mutations) {
 	const timestamp = (/* @__PURE__ */ new Date()).toISOString();
 	db.withTransactionSync(() => {
 		for (const mutation of mutations) {
-			const { id, ...data } = mutation.modified;
+			const data = extractDocumentData(mutation.modified);
+			mutation.modified = createDoc(String(mutation.key), data);
 			db.runSync(`UPDATE sources
          SET data = ?, updatedAt = ?, version = version + 1
          WHERE source = ? AND id = ?`, [
@@ -149,13 +203,17 @@ function updateRows(sourceName, mutations) {
 	});
 	return Promise.resolve();
 }
-function deleteRows(sourceName, ids) {
+function deleteRows(sourceName, mutations) {
 	const db = getDatabase();
 	db.withTransactionSync(() => {
-		for (const id of ids) db.runSync(`DELETE FROM sources WHERE source = ? AND id = ?`, [sourceName, String(id)]);
+		for (const mutation of 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)]);
+		}
 	});
 	return Promise.resolve();
 }
 
 //#endregion
-export { source };
+export { createID, source };

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "silosdk",
-  "version": "0.0.3",
+  "version": "0.0.5",
   "type": "module",
   "scripts": {
     "build": "tsdown",
     "watch": "tsdown --watch",
     "test": "vitest run",
-    "publish": "tsdown && npm publish"
+    "pub": "tsdown && npm publish"
   },
   "packageManager": "yarn@1.22.22",
   "files": [
@@ -17,6 +17,7 @@
     "@tanstack/react-query": "^5.101.0",
     "@types/node": "^25.3.0",
     "@types/react": "^19",
+    "expo-file-system": "^56.0.8",
     "expo-sqlite": "*",
     "prettier": "^3.7.4",
     "react-native": "0.85.0",
@@ -26,11 +27,12 @@
   },
   "dependencies": {
     "@standard-schema/spec": "^1.0.0",
-    "@tanstack/react-db": "^0.1.86",
-    "@tanstack/react-query": "^5.101.0",
     "nanoid": "5.1.6"
   },
   "peerDependencies": {
+    "@tanstack/react-db": "^0.1.86",
+    "@tanstack/react-query": "^5.101.0",
+    "expo-file-system": "^56.0.8",
     "expo-sqlite": "*",
     "react": "^19",
     "react-native": "0.85.x"
@@ -56,6 +58,11 @@
       "import": "./dist/settings.mjs",
       "require": "./dist/settings.cjs"
     },
+    "./media": {
+      "types": "./dist/media.d.mts",
+      "import": "./dist/media.mjs",
+      "require": "./dist/media.cjs"
+    },
     "./package.json": "./package.json"
   }
 }