@hozon/store-blob 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Paul Le Cam
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,46 @@
-# Temporary Holding Version
+# @hozon/store-blob
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Content-addressed blob metadata, persistent chunk manifests, and resumable transfer progress.
+Byte storage and digest verification belong to the caller.
+
+```sh
+pnpm add @hozon/store-blob @hozon/db
+```
+
+```ts
+import { blobStoreDefinition, getBlobStore } from '@hozon/store-blob'
+
+db.register(blobStoreDefinition)
+const blobs = await getBlobStore(db)
+await blobs.insertEntry(
+  {
+    blobID: 'content-key',
+    contentLength: 0,
+    chunkSize: 4,
+    state: 'local',
+    createdAt: Date.now(),
+  },
+  [],
+)
+```
+
+Entries map integer flags to booleans and expose camelCase fields.
+Encryption and key IDs are optional metadata that the store does not interpret.
+Repeated entry and manifest inserts preserve existing rows.
+
+For a known remote entry, `beginTransfer` records its manifest and sets its state to `partial`.
+Retries with the same chunk size preserve manifest digests and progress.
+Changing chunk size while a manifest exists rejects with `Cannot change chunk size for blob <blobID>: manifest already exists`.
+Record each verified chunk with `recordTransferChunk`, then call `finalizeTransfer` when all chunks are present.
+Finalisation preserves the manifest, clears transfer progress, and sets the entry state to `local`.
+`beginTransfer`, `recordTransferChunk`, and `finalizeTransfer` reject absent entries with `Blob entry <blobID> not found`.
+`recordTransferChunk` rejects unknown manifest indexes with `Blob chunk <blobID> at index <index> not found`.
+Finalisation rejects missing chunks with `Cannot finalize transfer <blobID>: <count> chunk(s) missing`.
+`deleteEntry` removes the entry, manifest, and transfer progress together.
+Manifest chunks reference entries, and transfer rows reference manifest chunks, with cascading deletion preventing orphan progress.
+
+Tables follow the database's configured prefix, which defaults to `hozon`.
+Multi-statement mutations are atomic and reuse a provider transaction.
+Manifest inserts use batches of 166 rows to stay below 500 bound parameters.
+
+See the [store reference](../../docs/reference/stores/blob.md).

package/lib/api.d.ts

@@ -0,0 +1,5 @@
+import type { Adapter } from '@hozon/adapter';
+import type { Kysely } from '@hozon/db';
+import type { BlobTables } from './tables.js';
+import type { BlobStoreAPI } from './types.js';
+export declare function createBlobStoreAPI(db: Kysely<BlobTables>, adapter: Adapter): BlobStoreAPI;

package/lib/api.js

@@ -0,0 +1,121 @@
+import { chunk, withStoreTransaction } from '@hozon/db';
+export function createBlobStoreAPI(db, adapter) {
+    async function insertManifest(trx, blobID, chunks) {
+        const rows = chunks.map((item)=>({
+                blob_id: blobID,
+                index: item.index,
+                digest: adapter.encodeBinary(item.digest)
+            }));
+        // Three bindings per row leave each statement below 500 parameters.
+        for (const batch of chunk(rows, 166)){
+            await trx.insertInto('blob_chunks').values(batch).onConflict((oc)=>oc.columns([
+                    'blob_id',
+                    'index'
+                ]).doNothing()).execute();
+        }
+    }
+    return {
+        async insertEntry (entry, chunks) {
+            await withStoreTransaction(db, async (trx)=>{
+                await trx.insertInto('blob_entries').values({
+                    blob_id: entry.blobID,
+                    content_length: entry.contentLength,
+                    encrypted: entry.encrypted ? 1 : 0,
+                    key_id: entry.keyID ?? null,
+                    chunk_size: entry.chunkSize,
+                    state: entry.state,
+                    pinned: entry.pinned ? 1 : 0,
+                    created_at: entry.createdAt
+                }).onConflict((oc)=>oc.column('blob_id').doNothing()).execute();
+                await insertManifest(trx, entry.blobID, chunks);
+            });
+        },
+        async getEntry (blobID) {
+            const row = await db.selectFrom('blob_entries').selectAll().where('blob_id', '=', blobID).executeTakeFirst();
+            return row === undefined ? null : {
+                blobID: row.blob_id,
+                contentLength: row.content_length,
+                encrypted: row.encrypted === 1,
+                keyID: row.key_id,
+                chunkSize: row.chunk_size,
+                state: row.state,
+                pinned: row.pinned === 1,
+                createdAt: row.created_at
+            };
+        },
+        async getChunkDigests (blobID) {
+            const rows = await db.selectFrom('blob_chunks').select('digest').where('blob_id', '=', blobID).orderBy('index', 'asc').execute();
+            return rows.map((row)=>row.digest);
+        },
+        async setPinned (blobID, pinned) {
+            await db.updateTable('blob_entries').set({
+                pinned: pinned ? 1 : 0
+            }).where('blob_id', '=', blobID).execute();
+        },
+        async deleteEntry (blobID) {
+            await withStoreTransaction(db, async (trx)=>{
+                await trx.deleteFrom('blob_transfers').where('blob_id', '=', blobID).execute();
+                await trx.deleteFrom('blob_chunks').where('blob_id', '=', blobID).execute();
+                await trx.deleteFrom('blob_entries').where('blob_id', '=', blobID).execute();
+            });
+        },
+        async beginTransfer (blobID, chunkSize, chunks) {
+            await withStoreTransaction(db, async (trx)=>{
+                let query = trx.selectFrom('blob_entries').select([
+                    'blob_id',
+                    'chunk_size'
+                ]).where('blob_id', '=', blobID);
+                if (adapter.kind === 'postgres') query = query.forUpdate();
+                const entry = await query.executeTakeFirst();
+                if (entry === undefined) throw new Error(`Blob entry ${blobID} not found`);
+                if (entry.chunk_size !== chunkSize) {
+                    const manifest = await trx.selectFrom('blob_chunks').select('index').where('blob_id', '=', blobID).executeTakeFirst();
+                    if (manifest !== undefined) {
+                        throw new Error(`Cannot change chunk size for blob ${blobID}: manifest already exists`);
+                    }
+                }
+                await trx.updateTable('blob_entries').set({
+                    chunk_size: chunkSize,
+                    state: 'partial'
+                }).where('blob_id', '=', blobID).execute();
+                await insertManifest(trx, blobID, chunks);
+            });
+        },
+        async recordTransferChunk (blobID, index) {
+            await withStoreTransaction(db, async (trx)=>{
+                const entry = await trx.selectFrom('blob_entries').select('blob_id').where('blob_id', '=', blobID).executeTakeFirst();
+                if (entry === undefined) throw new Error(`Blob entry ${blobID} not found`);
+                const chunk = await trx.selectFrom('blob_chunks').select('index').where('blob_id', '=', blobID).where('index', '=', index).executeTakeFirst();
+                if (chunk === undefined) throw new Error(`Blob chunk ${blobID} at index ${index} not found`);
+                await trx.insertInto('blob_transfers').values({
+                    blob_id: blobID,
+                    index
+                }).onConflict((oc)=>oc.columns([
+                        'blob_id',
+                        'index'
+                    ]).doNothing()).execute();
+            });
+        },
+        async getPresentChunkIndexes (blobID) {
+            const rows = await db.selectFrom('blob_transfers').select('index').where('blob_id', '=', blobID).orderBy('index', 'asc').execute();
+            return rows.map((row)=>row.index);
+        },
+        async finalizeTransfer (blobID) {
+            await withStoreTransaction(db, async (trx)=>{
+                const entry = await trx.selectFrom('blob_entries').select('blob_id').where('blob_id', '=', blobID).executeTakeFirst();
+                if (entry === undefined) throw new Error(`Blob entry ${blobID} not found`);
+                const manifest = await trx.selectFrom('blob_chunks').select('index').where('blob_id', '=', blobID).execute();
+                const present = await trx.selectFrom('blob_transfers').select('index').where('blob_id', '=', blobID).execute();
+                const presentSet = new Set(present.map((row)=>row.index));
+                const missing = manifest.filter((row)=>!presentSet.has(row.index));
+                if (missing.length > 0) {
+                    throw new Error(`Cannot finalize transfer ${blobID}: ${missing.length} chunk(s) missing`);
+                }
+                await trx.updateTable('blob_entries').set({
+                    state: 'local'
+                }).where('blob_id', '=', blobID).execute();
+                await trx.deleteFrom('blob_transfers').where('blob_id', '=', blobID).execute();
+            });
+        }
+    };
+}

package/lib/definition.d.ts

@@ -0,0 +1,6 @@
+import type { StoreDefinition, StoreProvider } from '@hozon/db';
+import type { BlobTables } from './tables.js';
+import type { BlobStoreAPI } from './types.js';
+export declare const BLOB_STORE = "blob";
+export declare const blobStoreDefinition: StoreDefinition<BlobTables, BlobStoreAPI>;
+export declare function getBlobStore(provider: StoreProvider): Promise<BlobStoreAPI>;

package/lib/definition.js

@@ -0,0 +1,11 @@
+import { createBlobStoreAPI } from './api.js';
+import { blobStoreMigrations } from './migrations.js';
+export const BLOB_STORE = 'blob';
+export const blobStoreDefinition = {
+    name: BLOB_STORE,
+    migrations: blobStoreMigrations,
+    createAPI: createBlobStoreAPI
+};
+export async function getBlobStore(provider) {
+    return provider.getStore(BLOB_STORE);
+}

package/lib/index.d.ts

@@ -0,0 +1,3 @@
+export { BLOB_STORE, blobStoreDefinition, getBlobStore } from './definition.js';
+export type { BlobChunkTable, BlobEntryTable, BlobTables, BlobTransferTable } from './tables.js';
+export type { BlobChunkInput, BlobEntry, BlobEntryInput, BlobState, BlobStoreAPI } from './types.js';

package/lib/index.js

@@ -0,0 +1 @@
+export { BLOB_STORE, blobStoreDefinition, getBlobStore } from './definition.js';

package/lib/migrations.d.ts

@@ -0,0 +1,2 @@
+import type { Migration, MigrationContext } from '@hozon/db';
+export declare function blobStoreMigrations(ctx: MigrationContext): Record<string, Migration>;

package/lib/migrations.js

@@ -0,0 +1,33 @@
+export function blobStoreMigrations(ctx) {
+    return {
+        '0-init': {
+            async up (db) {
+                await db.schema.createTable('blob_entries').addColumn('blob_id', ctx.types.text, (column)=>column.notNull().primaryKey())// Byte lengths and epoch milliseconds can exceed int32.
+                .addColumn('content_length', ctx.types.bigint, (column)=>column.notNull()).addColumn('encrypted', 'integer', (column)=>column.notNull().defaultTo(0)).addColumn('key_id', ctx.types.text).addColumn('chunk_size', 'integer', (column)=>column.notNull()).addColumn('state', ctx.types.text, (column)=>column.notNull()).addColumn('pinned', 'integer', (column)=>column.notNull().defaultTo(0)).addColumn('created_at', ctx.types.bigint, (column)=>column.notNull()).execute();
+                await db.schema.createTable('blob_chunks').addColumn('blob_id', ctx.types.text, (column)=>column.notNull()).addColumn('index', 'integer', (column)=>column.notNull()).addColumn('digest', ctx.types.binary, (column)=>column.notNull()).addPrimaryKeyConstraint(`${ctx.tablePrefix}_blob_chunks_pkey`, [
+                    'blob_id',
+                    'index'
+                ]).addForeignKeyConstraint(`${ctx.tablePrefix}_blob_chunks_entry_fkey`, [
+                    'blob_id'
+                ], 'blob_entries', [
+                    'blob_id'
+                ], (constraint)=>constraint.onDelete('cascade')).execute();
+                await db.schema.createTable('blob_transfers').addColumn('blob_id', ctx.types.text, (column)=>column.notNull()).addColumn('index', 'integer', (column)=>column.notNull()).addPrimaryKeyConstraint(`${ctx.tablePrefix}_blob_transfers_pkey`, [
+                    'blob_id',
+                    'index'
+                ]).addForeignKeyConstraint(`${ctx.tablePrefix}_blob_transfers_chunk_fkey`, [
+                    'blob_id',
+                    'index'
+                ], 'blob_chunks', [
+                    'blob_id',
+                    'index'
+                ], (constraint)=>constraint.onDelete('cascade')).execute();
+            },
+            async down (db) {
+                await db.schema.dropTable('blob_transfers').execute();
+                await db.schema.dropTable('blob_chunks').execute();
+                await db.schema.dropTable('blob_entries').execute();
+            }
+        }
+    };
+}

package/lib/tables.d.ts

@@ -0,0 +1,25 @@
+import type { BlobState } from './types.js';
+export type BlobEntryTable = {
+    blob_id: string;
+    content_length: number;
+    encrypted: number;
+    key_id: string | null;
+    chunk_size: number;
+    state: BlobState;
+    pinned: number;
+    created_at: number;
+};
+export type BlobChunkTable = {
+    blob_id: string;
+    index: number;
+    digest: Uint8Array;
+};
+export type BlobTransferTable = {
+    blob_id: string;
+    index: number;
+};
+export type BlobTables = {
+    blob_entries: BlobEntryTable;
+    blob_chunks: BlobChunkTable;
+    blob_transfers: BlobTransferTable;
+};

package/lib/tables.js

@@ -0,0 +1 @@
+export { };

package/lib/types.d.ts

@@ -0,0 +1,36 @@
+export type BlobState = 'local' | 'partial' | 'remote-only';
+export type BlobEntryInput = {
+    blobID: string;
+    contentLength: number;
+    encrypted?: boolean;
+    keyID?: string | null;
+    chunkSize: number;
+    state: BlobState;
+    pinned?: boolean;
+    createdAt: number;
+};
+export type BlobChunkInput = {
+    index: number;
+    digest: Uint8Array;
+};
+export type BlobEntry = {
+    blobID: string;
+    contentLength: number;
+    encrypted: boolean;
+    keyID: string | null;
+    chunkSize: number;
+    state: BlobState;
+    pinned: boolean;
+    createdAt: number;
+};
+export type BlobStoreAPI = {
+    insertEntry(entry: BlobEntryInput, chunks: Array<BlobChunkInput>): Promise<void>;
+    getEntry(blobID: string): Promise<BlobEntry | null>;
+    getChunkDigests(blobID: string): Promise<Array<Uint8Array>>;
+    setPinned(blobID: string, pinned: boolean): Promise<void>;
+    deleteEntry(blobID: string): Promise<void>;
+    beginTransfer(blobID: string, chunkSize: number, chunks: Array<BlobChunkInput>): Promise<void>;
+    recordTransferChunk(blobID: string, index: number): Promise<void>;
+    getPresentChunkIndexes(blobID: string): Promise<Array<number>>;
+    finalizeTransfer(blobID: string): Promise<void>;
+};

package/lib/types.js

@@ -0,0 +1,2 @@
+// Persists metadata and transfer progress. Callers own byte storage and verification.
+export { };

package/package.json

@@ -1,6 +1,42 @@
 {
   "name": "@hozon/store-blob",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.1",
+  "description": "Content-addressed blob metadata and resumable transfer store for Hozon",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TairuFramework/hozon.git",
+    "directory": "packages/store-blob"
+  },
+  "license": "MIT",
+  "sideEffects": false,
+  "type": "module",
+  "exports": {
+    ".": "./lib/index.js"
+  },
+  "files": [
+    "lib/*"
+  ],
+  "dependencies": {
+    "@hozon/adapter": "^0.1.0",
+    "@hozon/db": "^0.2.1"
+  },
+  "devDependencies": {
+    "@hozon/node-sqlite": "^0.1.0",
+    "@types/node": "^26.6.4",
+    "del-cli": "^7.0.0",
+    "vitest": "5.0.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "pnpm run build:clean && pnpm run build:js && pnpm run build:types",
+    "build:clean": "del-cli lib",
+    "build:js": "del-cli \"lib/**/*.js\" && swc src -d ./lib --config-file ../../node_modules/@kigu/dev/swc.json --strip-leading-paths",
+    "build:types": "del-cli \"lib/**/*.d.ts\" \"lib/**/*.d.ts.map\" && tsc --emitDeclarationOnly --skipLibCheck",
+    "build:types:ci": "tsc --emitDeclarationOnly --skipLibCheck --declarationMap false",
+    "test": "pnpm run test:types && pnpm run test:unit",
+    "test:types": "tsc --noEmit --skipLibCheck -p tsconfig.test.json",
+    "test:unit": "vitest run"
+  }
 }