silosdk 0.0.3 → 0.0.4

package/README.md

@@ -0,0 +1,162 @@
+# 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 { 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 = [] } = useLiveQuery((q) =>
+  q.from({ posts }).where(({ posts }) => eq(posts.published, true)),
+)
+
+const tx = posts.insert({
+  id: crypto.randomUUID(),
+  title: 'Hello',
+  body: '',
+  published: false,
+  coverImage: null,
+})
+
+await tx.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.coverImage = 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 __tanstack_react_query = require("@tanstack/react-query");
+let expo_file_system = require("expo-file-system");
+let nanoid = require("nanoid");
+
+//#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 { mutationOptions, queryOptions } from "@tanstack/react-query";
+import { Directory, File, Paths } from "expo-file-system";
+import { nanoid } from "nanoid";
+
+//#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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "silosdk",
-  "version": "0.0.3",
+  "version": "0.0.4",
   "type": "module",
   "scripts": {
     "build": "tsdown",
@@ -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"
   }
 }