Neon.Bucket reference

Bucket

Source: src/Neon/Bucket.ts

Branch-local S3 object storage. Writes do not change an ancestor’s data. The management credential is tracked separately and revoked after bucket cleanup. Neon does not expose a supported visibility update API; changing access fails explicitly instead of replacing a populated bucket. Policies and ACL writes are not supported. A private bucket has no anonymously readable object URL. Adopting an inherited bucket materializes its configuration on the child branch without changing ancestor tags, CORS, or object data.

Bucket: Creating a Bucket

const uploads = yield* Neon.Bucket("Uploads", {
  branch,
  cors: [{ AllowedOrigins: ["https://app.example.com"], AllowedMethods: ["PUT", "GET"] }],
});

BucketEventSource

Source: src/Neon/BucketEventSource.ts

Subscribe a Neon Function to successful uploads in a same-branch bucket. Registers the handler route and creates a tracked FunctionTrigger automatically. Provide BucketEventSourceHttp on the Function initialization Effect. The trigger is deleted before its Function/bucket. Use invocationId for application idempotency. Delivery is HTTP POST, not a queue: no acknowledgement, retry or exactly-once policy is added. Local development does not generate cloud upload events.

BucketEventSource: Process Uploads

yield* Neon.BucketEventSource(uploads, { name: "Uploads", prefix: "incoming/" }, event => Effect.log(event.objectKey));

BucketEventSourceHttp

Source: src/Neon/BucketEventSourceHttp.ts Kind: Layer · Provides: Neon.BucketEventSource

Neon Function HTTP object-event dispatch and deployment wiring.

BucketEventSourceHttp: Subscribe to uploads

const application = Effect.gen(function* () {
  yield* Neon.BucketEventSource(uploads, { name: "Uploads" }, event =>
    Effect.log(event.objectKey),
  );
  return { fetch: Effect.succeed(HttpServerResponse.text("ok")) };
}).pipe(Effect.provide(Neon.BucketEventSourceHttp));

Object

Source: src/Neon/Object.ts

A typed declarative object. JSON values are serialized automatically and their type is retained by ReadObject and WriteObject. A generic alone is not runtime validation; add a schema when external writers may violate the contract. Declared content is infrastructure desired state, not mutable application data.

Object: JSON Values

const settings = yield* Neon.Object("Settings", {
  bucket: uploads, key: "settings.json", value: { theme: "system", pageSize: 25 },
});

Object: File Content

const logo = yield* Neon.Object("Logo", {
  bucket: assets, key: "logo.svg", source: "./assets/logo.svg", contentType: "image/svg+xml",
});

ReadBucket

Source: src/Neon/ReadBucket.ts

Read/list storage on a branch. The bucket name limits this client’s surface, not credential authorization. Injected Function credentials remain available to the entire process; this is not a Function-level security sandbox.

ReadBucket: Read Objects

const files = yield* Neon.ReadBucket(uploads);
const object = yield* files.get("welcome.txt");

ReadBucketHttp

Source: src/Neon/ReadBucketHttp.ts Kind: Layer · Provides: ReadBucket

Use injected same-branch Neon credentials, otherwise manage a scoped credential.

ReadObject

Source: src/Neon/ReadObject.ts

Bind an object’s key and JSON type without repeating either. A TypeScript generic is an application contract, not runtime validation; an optional schema rejects invalid external writes. No object-only credential scope is claimed.

ReadObject: Typed Reads

const settings = yield* Neon.ReadObject(settingsObject);
const value = yield* settings.get();

ReadObjectHttp

Source: src/Neon/ReadObjectHttp.ts Kind: Layer · Provides: ReadObject

Typed object reads using injected or automatically scoped credentials.

ReadWriteBucket

Source: src/Neon/ReadWriteBucket.ts

Read and mutate a bucket with one credential granting storage:read and storage:write, or the Function’s injected credentials. No per-bucket policy is manufactured.

ReadWriteBucket: Read and Write

const files = yield* Neon.ReadWriteBucket(uploads);

ReadWriteBucketHttp

Source: src/Neon/ReadWriteBucketHttp.ts Kind: Layer · Provides: ReadWriteBucket

One injected or managed credential for both interfaces.

WriteBucket

Source: src/Neon/WriteBucket.ts

Mutate a bucket. Managed clients request storage:read and storage:write because the current S3 service requires explicit read scope, despite the documented write-implies-read contract. Credentials reach descendant branches.

WriteBucket: Upload Objects

const files = yield* Neon.WriteBucket(uploads);
yield* files.put("message.txt", "hello", { ContentType: "text/plain" });

WriteBucketHttp

Source: src/Neon/WriteBucketHttp.ts Kind: Layer · Provides: WriteBucket

Use injected same-branch credentials, otherwise manage explicit read/write scopes.

WriteObject

Source: src/Neon/WriteObject.ts

Bind an object’s key and value type for writes. Declarative reconciliation restores the resource’s declared value; use WriteBucket for application data. Managed writers request both storage:read and storage:write: write-only credentials currently fail S3 authorization. These scopes cover the branch lineage, not only this object’s key.

WriteObject: Typed Writes

const settings = yield* Neon.WriteObject(settingsObject);
yield* settings.put({ theme: "dark", pageSize: 50 });

WriteObjectHttp

Source: src/Neon/WriteObjectHttp.ts Kind: Layer · Provides: WriteObject

Typed object writes using injected or automatically scoped credentials.