Binary
Class: Binary<T>
Defined in: packages/core/src/services/binary.service.ts:386
One Binary instance — single-cardinality binary attribute on a CoreModel.
Tagged as a Behavior so the compiler picks it up via the same path as every
other @WebdaBehavior class. Its @Action-decorated methods are exposed
as model-scoped operations (<Model>.<Attribute>.<Action>) and routed by
RESTOperationsTransport.exposeBehaviorRoutes.
Constructor takes no required arguments because the transformer-emitted
__hydrateBehaviors calls new Binary() with zero args before stamping
the parent reference into WEBDA_STORAGE["__parent__"]. Legacy 2-arg
usage (new Binary(attribute, model)) is still supported for direct
callers and tests; when present, the constructor eagerly resolves the
service and copies the existing model attribute value so callers can call
isEmpty() and hash/size immediately.
Read Only
Webda Behavior
Webda/Binary
Extends
BinaryMap<T>
Type Parameters
T
T extends object = { }
Constructors
Constructor
new Binary<
T>(attribute?,model?):Binary<T>
Defined in: packages/core/src/services/binary.service.ts:402
Create a new Binary.
Callable with no arguments (the Behavior-hydration path the transformer
emits) or with the legacy (attribute, model) pair for direct
instantiation in tests / non-hydrated code.
Parameters
attribute?
string
the model attribute name (legacy form)
model?
Model
the parent model (legacy form)
Returns
Binary<T>
Overrides
Properties
[WEBDA_STORAGE]
[WEBDA_STORAGE]:
object
Defined in: packages/core/src/services/binary.service.ts:304
Link to the binary store
service
service:
BinaryService
Inherited from
challenge?
optionalchallenge?:string
Defined in: packages/core/src/services/binary.service.ts:143
Proof of possession of the content: hash of the content prefixed by 'WEBDA', computed by the client of the challenge and by the service on upload. Never persisted on a model nor sent to clients: it is not part of the schema of a binary attribute
Schema Ignore
Inherited from
hash?
optionalhash?:string
Defined in: packages/core/src/services/binary.service.ts:149
Will be computed by the service
hash of the content
Inherited from
metadata?
optionalmetadata?:T
Defined in: packages/core/src/services/binary.service.ts:153
Metadatas stored along with the binary
Inherited from
mimetype
mimetype:
string
Defined in: packages/core/src/services/binary.service.ts:136
Mimetype of the binary
Inherited from
name
name:
string
Defined in: packages/core/src/services/binary.service.ts:124
Current name
Inherited from
originalname?
optionaloriginalname?:string
Defined in: packages/core/src/services/binary.service.ts:128
Original name
Inherited from
size
size:
number
Defined in: packages/core/src/services/binary.service.ts:132
Size of the binary
Inherited from
Methods
attach()
attach():
Promise<void>
Defined in: packages/core/src/services/binary.service.ts:544
Direct (multipart / raw) upload from an HTTP request.
POST /<plural>/{uuid}/<attribute> — accepts the binary content as the
request body, hashes it, stores it on the BinaryService, and updates
this Binary's metadata. Returns early if the new content's hash matches
what we already hold (idempotent on duplicate uploads).
Migrated from DomainService.binaryPut; the parent-loading step is
unnecessary here because the Behavior is already attached to its parent
by __hydrateBehaviors.
Returns
Promise<void>
attachChallenge()
attachChallenge(
body?):Promise<any>
Defined in: packages/core/src/services/binary.service.ts:573
Challenge-based upload handshake.
PUT /<plural>/{uuid}/<attribute> — the client sends { hash, challenge, size?, name?, mimetype?, metadata? }; we ask the BinaryService for a
pre-signed upload URL (or a "done" flag if dedup matched) and return it.
Migrated from DomainService.binaryChallenge.
Parameters
body?
BinaryFileInfo<{ }> & object
the challenge body forwarded by resolveArguments; falls
back to context.getInput() when undefined.
Returns
Promise<any>
{ url?, method?, headers?, done, md5 }
complete()
complete(
hash):Promise<void>
Defined in: packages/core/src/services/binary.service.ts:606
Declare a direct upload finished.
POST /<plural>/{uuid}/<attribute>/complete/{hash} — after the client PUT the bytes to the URL returned by
attachChallenge, the BinaryService verifies the uploaded object and only then attaches it. A no-op when
the hash is already linked.
Parameters
hash
string
the hash announced in the challenge
Returns
Promise<void>
computeHashes()
computeHashes():
Promise<{challenge:string;hash:string; }>
Defined in: packages/core/src/services/binary.service.ts:199
Compute the hashes from the content, whatever hash or challenge is already set
The hash is the md5 of the bytes, the challenge the md5 of "WEBDA" followed by the bytes
Returns
Promise<{ challenge: string; hash: string; }>
the computed hash and challenge
Inherited from
delete()
delete(
hash):Promise<void>
Defined in: packages/core/src/services/binary.service.ts:518
Delete this binary from storage and clear local state.
Exposed as a Behavior @Action (DELETE on {uuid}/<attribute>/{hash}).
The URL {hash} must match the current binary's hash; this guards
against accidental deletes when the client raced a metadata update.
Migrated from DomainService.binaryAction (action="delete",
single-cardinality branch).
Parameters
hash
string
the URL-supplied hash; must match this.hash
Returns
Promise<void>
download()
download():
Promise<void>
Defined in: packages/core/src/services/binary.service.ts:633
Stream the binary to the response, or 302-redirect to a signed URL.
GET /<plural>/{uuid}/<attribute> — if the underlying BinaryService
supports redirect URLs (e.g. S3) we 302 to the signed URL; otherwise we
pipe the bytes directly through the response.
Named download (not get) so the parent BinaryMap.get(): Readable
accessor isn't shadowed — Behavior
Returns
Promise<void>
Action
methods can't change the
parent type's contract, and a plain get() overload that returns
void would break callers that consume the Readable.
Migrated from DomainService.binaryGet (single-cardinality branch).
downloadTo()
downloadTo(
filename):Promise<void>
Defined in: packages/core/src/services/binary.service.ts:362
Download the binary to a path
Shortcut to call Binary.downloadTo with current object
Parameters
filename
string
the filename
Returns
Promise<void>
the result
Inherited from
downloadUrl()
downloadUrl():
Promise<{Location:string;Map:BinaryMap<T>; }>
Defined in: packages/core/src/services/binary.service.ts:672
Return a JSON { Location, Map } describing where to fetch the binary.
GET /<plural>/{uuid}/<attribute>/url — variant of download() that
returns the URL as JSON instead of redirecting. Used by clients that
want to discover the URL without following the redirect.
Migrated from DomainService.binaryGet's returnUrl branch.
Returns
Promise<{ Location: string; Map: BinaryMap<T>; }>
{ Location, Map }
get()
get():
Promise<Readable>
Defined in: packages/core/src/services/binary.service.ts:323
Get the binary data
Returns
Promise<Readable>
the result
Inherited from
getAsBuffer()
getAsBuffer():
Promise<Buffer<ArrayBufferLike>>
Defined in: packages/core/src/services/binary.service.ts:350
Get into a buffer
Returns
Promise<Buffer<ArrayBufferLike>>
the result
Inherited from
getHashes()
getHashes():
Promise<{challenge:string;hash:string; }>
Defined in: packages/core/src/services/binary.service.ts:220
Create hashes, computed from the content unless a hash is already set
Returns
Promise<{ challenge: string; hash: string; }>
the result
Inherited from
getParent()
protectedgetParent():object
Defined in: packages/core/src/services/binary.service.ts:457
Read the Behavior parent reference. The transformer-emitted parent
getter on @WebdaBehavior classes returns the same slot, but Binary
may also be used in code paths where the transformer hasn't run (e.g.
unit tests that hand-roll instances), so we read the slot directly.
Returns
object
the parent reference or undefined
attribute
attribute:
string
instance
instance:
Storable
getService()
protectedgetService():BinaryService
Defined in: packages/core/src/services/binary.service.ts:438
Resolve the BinaryService lazily via the Behavior parent reference.
The transformer-emitted __hydrateBehaviors writes
WEBDA_STORAGE["__parent__"] after construction, and the per-Behavior
parent getter (also emitted by the transformer) surfaces it as
this.parent. We resolve the service on first call and cache it on the
storage slot so subsequent calls don't re-walk the binary registry.
Returns
the BinaryService that owns this Binary's parent attribute
isEmpty()
isEmpty():
any
Defined in: packages/core/src/services/binary.service.ts:465
isEmpty
Returns
any
the result
set()
set(
info):void
Defined in: packages/core/src/services/binary.service.ts:484
Ensure empty is set correctly.
BinaryFile's constructor calls this.set(info) before subclass class-field
initializers run, so this[WEBDA_STORAGE] is still undefined the first
time we get here when constructing a fresh new Binary() (the no-args
path used by the transformer's __hydrateBehaviors). Initialize the
slot lazily on the first set call to keep that boot path crash-free —
the class-field initializer on BinaryMap will then OVERWRITE this on
its way back from super, but that's fine because it preserves the
shape { service?, empty?, ... } and we've passed through set only
once at this point.
Parameters
info
the information object
Returns
void
Overrides
setMetadata()
setMetadata(
hash,metadata):Promise<void>
Defined in: packages/core/src/services/binary.service.ts:712
Update the metadata sidecar attached to this binary.
PUT /<plural>/{uuid}/<attribute>/{hash} — verifies the URL {hash}
matches the current binary, applies the new metadata, and persists via
parent.instance.patch(...). Metadata payload is capped at 4 KB to
mirror the existing DomainService.binaryAction rule.
Migrated from DomainService.binaryAction (action="metadata" branch).
Parameters
hash
string
the URL-supplied hash; must match this.hash
metadata
T
the new metadata blob (≤ 4 KB JSON)
Returns
Promise<void>
toBinaryFileInfo()
toBinaryFileInfo():
BinaryFileInfo<T>
Defined in: packages/core/src/services/binary.service.ts:179
Retrieve a plain BinaryFileInfo object
Returns
the result
Inherited from
toJSON()
toJSON():
StoredBinaryInfo<T>
Defined in: packages/core/src/services/binary.service.ts:739
Return undefined at runtime if no hash; the type annotation deliberately
narrows to the populated shape so the schema generator follows
BinaryFileInfo<T> for the Output/Stored schemas.
Returns
the result
Overrides
upload()
upload(
file):Promise<void>
Defined in: packages/core/src/services/binary.service.ts:497
Replace the binary by uploading a new file. Direct programmatic use
(non-HTTP). Equivalent to the attach(...) HTTP action minus the
context handling.
Parameters
file
BinaryFile<T>
the binary file to upload
Returns
Promise<void>
the result