@nestm/storage 0.1.0-alpha.14 → 0.1.0-alpha.16

package/dist/workspace/storage-text-draft.d.ts

@@ -0,0 +1,20 @@
+import type { StorageStagedContent } from '../core/storage-staged-content.js';
+import type { StorageFileDraftRecord, StorageFileWorkflowLimits, StorageFileWorkflowTransaction } from './storage-file-workflow.types.js';
+/** Stage bytes outside the host transaction, then atomically publish all part references. */
+export declare function stageStorageTextDraft<Scope, Receipt>(options: {
+    readonly scope: Scope;
+    readonly signal: AbortSignal;
+    readonly limits: Readonly<StorageFileWorkflowLimits>;
+    readonly content: StorageStagedContent<Scope>;
+    readonly idempotencyKey: string;
+    readonly fingerprint: string;
+    readonly requireMutation: (expectedEtag: string | null) => void;
+    readonly transaction: <T>(work: (tx: StorageFileWorkflowTransaction<Receipt>) => Promise<T>) => Promise<T>;
+    readonly load: () => Promise<{
+        content: string;
+        path: string;
+        expectedEtag: string | null;
+        source: StorageFileDraftRecord<Receipt> | null;
+    }>;
+}): Promise<StorageFileDraftRecord<Receipt>>;
+//# sourceMappingURL=storage-text-draft.d.ts.map

package/dist/workspace/storage-text-draft.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage-text-draft.d.ts","sourceRoot":"","sources":["../../src/workspace/storage-text-draft.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,mCAAmC,CAAC;AAC9E,OAAO,KAAK,EACV,sBAAsB,EAEtB,yBAAyB,EACzB,8BAA8B,EAC/B,MAAM,kCAAkC,CAAC;AAE1C,6FAA6F;AAC7F,wBAAsB,qBAAqB,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE;IACnE,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,yBAAyB,CAAC,CAAC;IACrD,QAAQ,CAAC,OAAO,EAAE,oBAAoB,CAAC,KAAK,CAAC,CAAC;IAC9C,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,eAAe,EAAE,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,CAAC;IAChE,QAAQ,CAAC,WAAW,EAAE,CAAC,CAAC,EACtB,IAAI,EAAE,CAAC,EAAE,EAAE,8BAA8B,CAAC,OAAO,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,KAC9D,OAAO,CAAC,CAAC,CAAC,CAAC;IAChB,QAAQ,CAAC,IAAI,EAAE,MAAM,OAAO,CAAC;QAC3B,OAAO,EAAE,MAAM,CAAC;QAChB,IAAI,EAAE,MAAM,CAAC;QACb,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;QAC5B,MAAM,EAAE,sBAAsB,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC;KAChD,CAAC,CAAC;CACJ,GAAG,OAAO,CAAC,sBAAsB,CAAC,OAAO,CAAC,CAAC,CAuF3C"}

package/dist/workspace/storage-text-draft.js

@@ -0,0 +1,80 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { StorageError } from '../storage.error.js';
+import { storageBytesStream } from '../core/storage-streams.js';
+/** Stage bytes outside the host transaction, then atomically publish all part references. */
+export async function stageStorageTextDraft(options) {
+    const { transaction, signal, limits } = options;
+    const replay = async (tx) => {
+        const prior = await tx.findDraftByKey(options.idempotencyKey);
+        if (prior !== null) {
+            options.requireMutation(prior.expectedEtag);
+            if (prior.requestFingerprint !== options.fingerprint)
+                throw new StorageError('Draft key was already used for different input.', { code: 'CONFLICT' });
+        }
+        return prior;
+    };
+    const prior = await transaction(replay);
+    if (prior !== null)
+        return prior;
+    const loaded = await options.load();
+    options.requireMutation(loaded.expectedEtag);
+    if (/[\uD800-\uDFFF]/u.test(loaded.content))
+        throw new StorageError('Text must be well-formed UTF-8.', {
+            code: 'INVALID_ARGUMENT',
+        });
+    const bytes = new TextEncoder().encode(loaded.content);
+    if (bytes.byteLength > limits.maxTextBytes)
+        throw new StorageError('Text checkpoint exceeds the buffered text limit.', {
+            code: 'LIMIT_EXCEEDED',
+        });
+    if (limits.maxChunkBytes < 4)
+        throw new StorageError('Text checkpoints require a chunk limit of at least four bytes.', { code: 'LIMIT_EXCEEDED' });
+    const parts = [];
+    for (let offset = 0; offset < bytes.length;) {
+        signal.throwIfAborted();
+        let end = Math.min(bytes.length, offset + limits.maxChunkBytes);
+        while (end < bytes.length && (bytes[end] & 0xc0) === 0x80)
+            end--;
+        const chunk = bytes.subarray(offset, end);
+        const body = await options.content.write(options.scope, storageBytesStream(chunk), { maxBytes: limits.maxChunkBytes, signal });
+        if (body.size !== chunk.length ||
+            body.sha256 !== createHash('sha256').update(chunk).digest('hex'))
+            throw new StorageError('Invalid text chunk receipt.', {
+                code: 'PROVIDER',
+            });
+        parts.push({ offset, size: body.size, sha256: body.sha256, body });
+        offset = end;
+    }
+    return transaction(async (tx) => {
+        const concurrent = await replay(tx);
+        if (concurrent !== null)
+            return concurrent;
+        if (loaded.source !== null) {
+            const current = await tx.getDraft(loaded.source.id);
+            if (current === null ||
+                current.size !== loaded.source.size ||
+                !['open', 'sealed'].includes(current.status))
+                throw new StorageError('The source draft changed while editing. Read its latest size.', { code: 'CONFLICT' });
+            await tx.saveDraft({ ...current, status: 'sealed' });
+        }
+        const draft = {
+            id: randomUUID(),
+            path: loaded.path,
+            expectedEtag: loaded.expectedEtag,
+            sourceDraftId: loaded.source?.id ?? null,
+            text: true,
+            status: 'sealed',
+            size: bytes.length,
+            result: null,
+            createdAt: new Date().toISOString(),
+            idempotencyKey: options.idempotencyKey,
+            requestFingerprint: options.fingerprint,
+            body: null,
+        };
+        await tx.saveDraft(draft);
+        for (const part of parts)
+            await tx.putPart(draft.id, part);
+        return draft;
+    });
+}
+//# sourceMappingURL=storage-text-draft.js.map

package/dist/workspace/storage-text-draft.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage-text-draft.js","sourceRoot":"","sources":["../../src/workspace/storage-text-draft.ts"],"names":[],"mappings":"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","sourcesContent":["import { createHash, randomUUID } from 'node:crypto';\nimport { StorageError } from '../storage.error.js';\nimport { storageBytesStream } from '../core/storage-streams.js';\nimport type { StorageStagedContent } from '../core/storage-staged-content.js';\nimport type {\n  StorageFileDraftRecord,\n  StorageFilePartRecord,\n  StorageFileWorkflowLimits,\n  StorageFileWorkflowTransaction,\n} from './storage-file-workflow.types.js';\n\n/** Stage bytes outside the host transaction, then atomically publish all part references. */\nexport async function stageStorageTextDraft<Scope, Receipt>(options: {\n  readonly scope: Scope;\n  readonly signal: AbortSignal;\n  readonly limits: Readonly<StorageFileWorkflowLimits>;\n  readonly content: StorageStagedContent<Scope>;\n  readonly idempotencyKey: string;\n  readonly fingerprint: string;\n  readonly requireMutation: (expectedEtag: string | null) => void;\n  readonly transaction: <T>(\n    work: (tx: StorageFileWorkflowTransaction<Receipt>) => Promise<T>,\n  ) => Promise<T>;\n  readonly load: () => Promise<{\n    content: string;\n    path: string;\n    expectedEtag: string | null;\n    source: StorageFileDraftRecord<Receipt> | null;\n  }>;\n}): Promise<StorageFileDraftRecord<Receipt>> {\n  const { transaction, signal, limits } = options;\n  const replay = async (tx: StorageFileWorkflowTransaction<Receipt>) => {\n    const prior = await tx.findDraftByKey(options.idempotencyKey);\n    if (prior !== null) {\n      options.requireMutation(prior.expectedEtag);\n      if (prior.requestFingerprint !== options.fingerprint)\n        throw new StorageError(\n          'Draft key was already used for different input.',\n          { code: 'CONFLICT' },\n        );\n    }\n    return prior;\n  };\n  const prior = await transaction(replay);\n  if (prior !== null) return prior;\n  const loaded = await options.load();\n  options.requireMutation(loaded.expectedEtag);\n  if (/[\\uD800-\\uDFFF]/u.test(loaded.content))\n    throw new StorageError('Text must be well-formed UTF-8.', {\n      code: 'INVALID_ARGUMENT',\n    });\n  const bytes = new TextEncoder().encode(loaded.content);\n  if (bytes.byteLength > limits.maxTextBytes)\n    throw new StorageError('Text checkpoint exceeds the buffered text limit.', {\n      code: 'LIMIT_EXCEEDED',\n    });\n  if (limits.maxChunkBytes < 4)\n    throw new StorageError(\n      'Text checkpoints require a chunk limit of at least four bytes.',\n      { code: 'LIMIT_EXCEEDED' },\n    );\n  const parts: StorageFilePartRecord[] = [];\n  for (let offset = 0; offset < bytes.length;) {\n    signal.throwIfAborted();\n    let end = Math.min(bytes.length, offset + limits.maxChunkBytes);\n    while (end < bytes.length && (bytes[end]! & 0xc0) === 0x80) end--;\n    const chunk = bytes.subarray(offset, end);\n    const body = await options.content.write(\n      options.scope,\n      storageBytesStream(chunk),\n      { maxBytes: limits.maxChunkBytes, signal },\n    );\n    if (\n      body.size !== chunk.length ||\n      body.sha256 !== createHash('sha256').update(chunk).digest('hex')\n    )\n      throw new StorageError('Invalid text chunk receipt.', {\n        code: 'PROVIDER',\n      });\n    parts.push({ offset, size: body.size, sha256: body.sha256, body });\n    offset = end;\n  }\n  return transaction(async (tx) => {\n    const concurrent = await replay(tx);\n    if (concurrent !== null) return concurrent;\n    if (loaded.source !== null) {\n      const current = await tx.getDraft(loaded.source.id);\n      if (\n        current === null ||\n        current.size !== loaded.source.size ||\n        !['open', 'sealed'].includes(current.status)\n      )\n        throw new StorageError(\n          'The source draft changed while editing. Read its latest size.',\n          { code: 'CONFLICT' },\n        );\n      await tx.saveDraft({ ...current, status: 'sealed' });\n    }\n    const draft: StorageFileDraftRecord<Receipt> = {\n      id: randomUUID(),\n      path: loaded.path,\n      expectedEtag: loaded.expectedEtag,\n      sourceDraftId: loaded.source?.id ?? null,\n      text: true,\n      status: 'sealed',\n      size: bytes.length,\n      result: null,\n      createdAt: new Date().toISOString(),\n      idempotencyKey: options.idempotencyKey,\n      requestFingerprint: options.fingerprint,\n      body: null,\n    };\n    await tx.saveDraft(draft);\n    for (const part of parts) await tx.putPart(draft.id, part);\n    return draft;\n  });\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nestm/storage",
-  "version": "0.1.0-alpha.14",
+  "version": "0.1.0-alpha.16",
   "description": "Framework-neutral storage clients, capability-scoped agent workspaces, NestJS 12 integration, and guarded HTTP access.",
   "license": "MIT",
   "author": "Kauan Guesser",