source/teaql-ts/examples/object-storage/README.md

Context owned object storage

Tracking: TypeScript #53, shared contract #122.

Core exports contain portable typed values and asynchronous byte-stream contracts. The optional server-only @teaql/teaql/object-storage/s3 entry requires the pinned @aws-sdk/client-s3 and @aws-sdk/s3-request-presigner peers (3.1151.0), Node 20+, and filesystem access. It is not imported by the browser core entry point. SDK credentials, endpoints and buckets are configured at trusted startup.

import {UserContext,ObjectKey,ObjectPutOptions} from '@teaql/teaql';
import {S3ObjectStorage} from '@teaql/teaql/object-storage/s3';

const provider = new S3ObjectStorage(sdkClient, 'attachments');
const storage = new UserContext().withObjectStorage(provider)
  .objectStorage('store payment receipt attachment');
const key = new ObjectKey('receipts/opaque-reference.pdf');
await storage.put(key, source, new ObjectPutOptions(contentLength, 'create_only'));
const link = await storage.getReadUrl(key);
// Return link.url to an authorized caller; never log it.
const response = await storage.get(key);
try { for await (const block of response.stream) { /* consume bytes */ } }
finally { await response.close(); }

Upload iterators are finalized on every exit. The adapter stages to a private temporary file with bounded buffers and exact length checks, capped at 5 GiB. It reopens the staged body for at most three transport/service retry attempts; conditional PUT remains atomic. Downloads stream and must be consumed or closed. getBytes(key, maximumBytes) requires an explicit memory ceiling. Replacement is explicit; permissions and outages never become false absence.

Keys are durable; five-minute read URLs are reusable bearer links and can expire early with credentials/policy. Issuing a URL does not check existence or grant domain permission. Core inspection/diagnostic events exclude keys, metadata, body, credentials, URLs and SDK messages. The observer/telemetry resource is installed on Context (objectStorageObserver / runtimeTelemetry). S3 writes remain independent of SQL transactions.

After installing this checkout's dependencies, set TEAQL_S3_ENDPOINT, TEAQL_S3_BUCKET, TEAQL_S3_ACCESS_KEY, TEAQL_S3_SECRET_KEY to a dedicated test service and run bash examples/object-storage/verify.sh twice. The example uses a fresh local build, creates its fixture bucket if missing and removes only its unique keys. The production provider never creates buckets. The gate qualifies the dedicated fixture; other compatible services require their own tests. Multipart, list/copy/range, signed upload and browser credentials are outside this first server adapter.