@coasys/ad4m / Exports / PerspectiveProxy
Class: PerspectiveProxy
PerspectiveProxy provides a high-level interface for working with AD4M Perspectives - agent-centric semantic graphs that store and organize links between expressions.
A Perspective is fundamentally a collection of links (subject-predicate-object triples) that represent an agent's view of their digital world. Through PerspectiveProxy, you can:
- Add, remove, and query links
- Work with Social DNA (subject classes and flows)
- Subscribe to real-time updates
- Share perspectives as Neighbourhoods
- Execute Prolog queries for complex graph patterns
Example
// Create and work with links
const perspective = await ad4m.perspective.add("My Space");
await perspective.add({
source: "did:key:alice",
predicate: "knows",
target: "did:key:bob"
});
// Query links
const friends = await perspective.get({
source: "did:key:alice",
predicate: "knows"
});
// Use Social DNA
await perspective.addSdna(todoClass, "subject_class");
const todo = await perspective.createSubject("Todo", "expression://123");
// Subscribe to changes
perspective.addListener("link-added", (link) => {
console.log("New link added:", link);
});
Table of contents
Constructors
Properties
- #client
- #handle
- #perspectiveLinkAddedCallbacks
- #perspectiveLinkRemovedCallbacks
- #perspectiveLinkUpdatedCallbacks
- #perspectiveSyncStateChangeCallbacks
- name
- neighbourhood
- sharedUrl
- state
- uuid
Accessors
Methods
- add
- addLinkExpression
- addLinks
- addListener
- addSdna
- addSyncStateChangeListener
- availableFlows
- buildQueryFromTemplate
- createExpression
- createSubject
- ensureSDNASubjectClass
- executeAction
- expressionsInFlowState
- flowActions
- flowState
- get
- getAllSubjectInstances
- getAllSubjectProxies
- getExpression
- getNeighbourhoodProxy
- getSdna
- getSingleTarget
- getSubjectData
- getSubjectProxy
- infer
- isSubjectInstance
- linkMutations
- loadSnapshot
- remove
- removeLinks
- removeListener
- removeSubject
- runFlowAction
- sdnaFlows
- setSingleTarget
- snapshot
- startFlow
- stringOrTemplateObjectToSubjectClassName
- subjectClasses
- subjectClassesByTemplate
- subscribeInfer
- update
Constructors
constructor
• new PerspectiveProxy(handle
, ad4m
)
Creates a new PerspectiveProxy instance. Note: Don't create this directly, use ad4m.perspective.add() instead.
Parameters
Name | Type |
---|---|
handle | PerspectiveHandle |
ad4m | PerspectiveClient |
Defined in
perspectives/PerspectiveProxy.ts:246
Properties
#client
• Private
#client: PerspectiveClient
Defined in
perspectives/PerspectiveProxy.ts:236
#handle
• Private
#handle: PerspectiveHandle
Defined in
perspectives/PerspectiveProxy.ts:235
#perspectiveLinkAddedCallbacks
• Private
#perspectiveLinkAddedCallbacks: LinkCallback
[]
Defined in
perspectives/PerspectiveProxy.ts:237
#perspectiveLinkRemovedCallbacks
• Private
#perspectiveLinkRemovedCallbacks: LinkCallback
[]
Defined in
perspectives/PerspectiveProxy.ts:238
#perspectiveLinkUpdatedCallbacks
• Private
#perspectiveLinkUpdatedCallbacks: LinkCallback
[]
Defined in
perspectives/PerspectiveProxy.ts:239
#perspectiveSyncStateChangeCallbacks
• Private
#perspectiveSyncStateChangeCallbacks: SyncStateChangeCallback
[]
Defined in
perspectives/PerspectiveProxy.ts:240
name
• name: string
Human-readable name of this perspective
Defined in
perspectives/PerspectiveProxy.ts:224
neighbourhood
• neighbourhood: NeighbourhoodExpression
If this perspective is shared, this contains the Neighbourhood metadata
Defined in
perspectives/PerspectiveProxy.ts:230
sharedUrl
• sharedUrl: string
If this perspective is shared as a Neighbourhood, this is its URL
Defined in
perspectives/PerspectiveProxy.ts:227
state
• state: PerspectiveState
Current sync state if this perspective is shared
Defined in
perspectives/PerspectiveProxy.ts:233
uuid
• uuid: string
Unique identifier of this perspective
Defined in
perspectives/PerspectiveProxy.ts:221
Accessors
ai
• get
ai(): AIClient
Returns a proxy object for working with AI capabilities.
Returns
AIClient instance
Example
// Use AI to analyze perspective content
const summary = await perspective.ai.summarize();
// Generate new content
const suggestion = await perspective.ai.suggest("next action");
Defined in
perspectives/PerspectiveProxy.ts:1007
Methods
add
▸ add(link
, status?
): Promise
<LinkExpression
>
Adds a new link to the perspective.
Parameters
Name | Type | Default value | Description |
---|---|---|---|
link | Link | undefined | The link to add |
status | LinkStatus | 'shared' | Whether the link should be shared in a Neighbourhood |
Returns
Promise
<LinkExpression
>
The created LinkExpression
Example
// Add a simple relationship
await perspective.add({
source: "did:key:alice",
predicate: "follows",
target: "did:key:bob"
});
// Add a local-only link
await perspective.add({
source: "note://123",
predicate: "tag",
target: "private"
}, "local");
Defined in
perspectives/PerspectiveProxy.ts:403
addLinkExpression
▸ addLinkExpression(link
, status?
): Promise
<LinkExpression
>
Adds a pre-signed LinkExpression to the perspective.
Parameters
Name | Type | Default value | Description |
---|---|---|---|
link | LinkExpression | undefined | The signed LinkExpression to add |
status | LinkStatus | 'shared' | Whether the link should be shared |
Returns
Promise
<LinkExpression
>
The added LinkExpression
Defined in
perspectives/PerspectiveProxy.ts:448
addLinks
▸ addLinks(links
, status?
): Promise
<LinkExpression
[]>
Adds multiple links to the perspective in a single operation. More efficient than adding links one by one.
Parameters
Name | Type | Default value | Description |
---|---|---|---|
links | Link [] | undefined | Array of links to add |
status | LinkStatus | 'shared' | Whether the links should be shared |
Returns
Promise
<LinkExpression
[]>
Array of created LinkExpressions
Defined in
perspectives/PerspectiveProxy.ts:415
addListener
▸ addListener(type
, cb
): Promise
<void
>
Subscribes to link changes in the perspective.
Parameters
Name | Type | Description |
---|---|---|
type | PerspectiveListenerTypes | Type of change to listen for |
cb | LinkCallback | Callback function |
Returns
Promise
<void
>
Example
// Listen for new links
perspective.addListener("link-added", (link) => {
console.log("New link:", link);
});
// Listen for removed links
perspective.addListener("link-removed", (link) => {
console.log("Link removed:", link);
});
Defined in
perspectives/PerspectiveProxy.ts:511
addSdna
▸ addSdna(name
, sdnaCode
, sdnaType
): Promise
<boolean
>
Adds the given Social DNA code to the perspective's SDNA code
Parameters
Name | Type |
---|---|
name | string |
sdnaCode | string |
sdnaType | "subject_class" | "flow" | "custom" |
Returns
Promise
<boolean
>
Defined in
perspectives/PerspectiveProxy.ts:701
addSyncStateChangeListener
▸ addSyncStateChangeListener(cb
): Promise
<void
>
Subscribes to sync state changes if this perspective is shared.
Parameters
Name | Type | Description |
---|---|---|
cb | SyncStateChangeCallback | Callback function |
Returns
Promise
<void
>
Example
perspective.addSyncStateChangeListener((state) => {
console.log("Sync state:", state);
});
Defined in
perspectives/PerspectiveProxy.ts:533
availableFlows
▸ availableFlows(exprAddr
): Promise
<string
[]>
Returns all Social DNA flows that can be started from the given expression
Parameters
Name | Type |
---|---|
exprAddr | string |
Returns
Promise
<string
[]>
Defined in
perspectives/PerspectiveProxy.ts:650
buildQueryFromTemplate
▸ Private
buildQueryFromTemplate(obj
): string
Parameters
Name | Type |
---|---|
obj | object |
Returns
string
Defined in
perspectives/PerspectiveProxy.ts:862
createExpression
▸ createExpression(content
, languageAddress
): Promise
<string
>
Creates a new Expression in the specified Language.
Parameters
Name | Type | Description |
---|---|---|
content | any | Content for the new Expression |
languageAddress | string | Address of the Language to use |
Returns
Promise
<string
>
URI of the created Expression
Defined in
perspectives/PerspectiveProxy.ts:488
createSubject
▸ createSubject<T
>(subjectClass
, exprAddr
): Promise
<T
>
Creates a new subject instance by running its (SDNA defined) constructor, which means adding links around the given expression address so that it conforms to the given subject class.
Type parameters
Name |
---|
T |
Parameters
Name | Type | Description |
---|---|---|
subjectClass | T | Either a string with the name of the subject class, or an object with the properties of the subject class. In the latter case, the first subject class that matches the given properties will be used. |
exprAddr | string | The address of the expression to be turned into a subject instance |
Returns
Promise
<T
>
Defined in
perspectives/PerspectiveProxy.ts:737
ensureSDNASubjectClass
▸ ensureSDNASubjectClass(jsClass
): Promise
<void
>
Takes a JS class (its constructor) and assumes that it was decorated by the
Parameters
Name | Type |
---|---|
jsClass | any |
Returns
Promise
<void
>
Subject Class
etc. decorators. It then tests if there is a subject class already present in the perspective's SDNA that matches the given class. If there is no such class, it gets the JS class's SDNA by calling its static generateSDNA() function and adds it to the perspective's SDNA.
Defined in
perspectives/PerspectiveProxy.ts:978
executeAction
▸ executeAction(actions
, expression
, parameters
): Promise
<boolean
>
Executes a set of actions on an expression with optional parameters. Used internally by Social DNA flows and subject class operations.
Actions are specified as an array of commands that modify links in the perspective. Each action is an object with the following format:
{
action: "addLink" | "removeLink" | "setSingleTarget" | "collectionSetter",
source: string, // Usually "this" to reference the current expression
predicate: string, // The predicate URI
target: string // The target value or "value" for parameters
}
Available commands:
addLink
: Creates a new linkremoveLink
: Removes an existing linksetSingleTarget
: Removes all existing links with the same source/predicate and adds a new onecollectionSetter
: Special command for setting collection properties
When used with parameters, the special value "value" in the target field will be replaced with the actual parameter value.
Parameters
Name | Type | Description |
---|---|---|
actions | any | Array of action objects to execute |
expression | any | Target expression address (replaces "this" in actions) |
parameters | Parameter [] | Optional parameters that replace "value" in actions |
Returns
Promise
<boolean
>
Example
// Add a state link and remove an old one
await perspective.executeAction([
{
action: "addLink",
source: "this",
predicate: "todo://state",
target: "todo://doing"
},
{
action: "removeLink",
source: "this",
predicate: "todo://state",
target: "todo://ready"
}
], "expression://123");
// Set a property using a parameter
await perspective.executeAction([
{
action: "setSingleTarget",
source: "this",
predicate: "todo://title",
target: "value"
}
], "expression://123", [
{ name: "title", value: "New Title" }
]);
Defined in
perspectives/PerspectiveProxy.ts:323
expressionsInFlowState
▸ expressionsInFlowState(flowName
, flowState
): Promise
<string
[]>
Returns all expressions in the given state of given Social DNA flow
Parameters
Name | Type |
---|---|
flowName | string |
flowState | number |
Returns
Promise
<string
[]>
Defined in
perspectives/PerspectiveProxy.ts:664
flowActions
▸ flowActions(flowName
, exprAddr
): Promise
<string
[]>
Returns available action names, with regard to Social DNA flow and expression's flow state
Parameters
Name | Type |
---|---|
flowName | string |
exprAddr | string |
Returns
Promise
<string
[]>
Defined in
perspectives/PerspectiveProxy.ts:676
flowState
▸ flowState(flowName
, exprAddr
): Promise
<number
>
Returns the given expression's flow state with regard to given Social DNA flow
Parameters
Name | Type |
---|---|
flowName | string |
exprAddr | string |
Returns
Promise
<number
>
Defined in
perspectives/PerspectiveProxy.ts:670
get
▸ get(query
): Promise
<LinkExpression
[]>
Retrieves links from the perspective that match the given query.
Parameters
Name | Type | Description |
---|---|---|
query | LinkQuery | Query parameters to filter links |
Returns
Promise
<LinkExpression
[]>
Array of matching LinkExpressions
Example
// Get all links where Alice knows someone
const links = await perspective.get({
source: "did:key:alice",
predicate: "knows"
});
// Get all comments on a post
const comments = await perspective.get({
source: "post://123",
predicate: "comment"
});
Defined in
perspectives/PerspectiveProxy.ts:348
getAllSubjectInstances
▸ getAllSubjectInstances<T
>(subjectClass
): Promise
<T
[]>
Returns all subject instances of the given subject class as proxy objects.
Type parameters
Name |
---|
T |
Parameters
Name | Type | Description |
---|---|---|
subjectClass | T | Either a string with the name of the subject class, or an object with the properties of the subject class. In the latter case, all subject classes that match the given properties will be used. |
Returns
Promise
<T
[]>
Defined in
perspectives/PerspectiveProxy.ts:824
getAllSubjectProxies
▸ getAllSubjectProxies<T
>(subjectClass
): Promise
<T
[]>
Returns all subject proxies of the given subject class.
Type parameters
Name |
---|
T |
Parameters
Name | Type | Description |
---|---|---|
subjectClass | T | Either a string with the name of the subject class, or an object with the properties of the subject class. In the latter case, all subject classes that match the given properties will be used. |
Returns
Promise
<T
[]>
Defined in
perspectives/PerspectiveProxy.ts:846
getExpression
▸ getExpression(expressionURI
): Promise
<ExpressionRendered
>
Retrieves and renders an Expression referenced in this perspective.
Parameters
Name | Type | Description |
---|---|---|
expressionURI | string | URI of the Expression to retrieve |
Returns
Promise
<ExpressionRendered
>
The rendered Expression
Defined in
perspectives/PerspectiveProxy.ts:477
getNeighbourhoodProxy
▸ getNeighbourhoodProxy(): NeighbourhoodProxy
Returns
Defined in
perspectives/PerspectiveProxy.ts:989
getSdna
▸ getSdna(): Promise
<string
[]>
Returns the perspective's Social DNA code This will return all SDNA code elements in an array.
Returns
Promise
<string
[]>
Defined in
perspectives/PerspectiveProxy.ts:692
getSingleTarget
▸ getSingleTarget(query
): Promise
<string
| void
>
Gets a single target value matching a query. Useful when you expect only one result.
Parameters
Name | Type | Description |
---|---|---|
query | LinkQuery | Query to find the target |
Returns
Promise
<string
| void
>
Target value or void if not found
Example
// Get a user's name
const name = await perspective.getSingleTarget({
source: "did:key:alice",
predicate: "name"
});
Defined in
perspectives/PerspectiveProxy.ts:603
getSubjectData
▸ getSubjectData<T
>(subjectClass
, exprAddr
): Promise
<T
>
Type parameters
Name |
---|
T |
Parameters
Name | Type |
---|---|
subjectClass | T |
exprAddr | string |
Returns
Promise
<T
>
Defined in
perspectives/PerspectiveProxy.ts:752
getSubjectProxy
▸ getSubjectProxy<T
>(base
, subjectClass
): Promise
<T
>
For an existing subject instance (existing in the perspective's links) this function returns a proxy object that can be used to access the subject's properties and methods.
Type parameters
Name |
---|
T |
Parameters
Name | Type | Description |
---|---|---|
base | string | URI of the subject's root expression |
subjectClass | T | Either a string with the name of the subject class, or an object with the properties of the subject class. In the latter case, the first subject class that matches the given properties will be used. |
Returns
Promise
<T
>
Defined in
perspectives/PerspectiveProxy.ts:809
infer
▸ infer(query
): Promise
<any
>
Executes a Prolog query against the perspective's knowledge base. This is a powerful way to find complex patterns in the graph.
Parameters
Name | Type | Description |
---|---|---|
query | string | Prolog query string |
Returns
Promise
<any
>
Query results or false if no results
Example
// Find friends of friends
const results = await perspective.infer(`
triple(A, "knows", B),
triple(B, "knows", C),
A \= C
`);
// Find all active todos
const todos = await perspective.infer(`
instance(Todo, "Todo"),
property_getter("Todo", Todo, "state", "active")
`);
Defined in
perspectives/PerspectiveProxy.ts:375
isSubjectInstance
▸ isSubjectInstance<T
>(expression
, subjectClass
): Promise
<boolean
>
Checks if the given expression is a subject instance of the given subject class
Type parameters
Name |
---|
T |
Parameters
Name | Type | Description |
---|---|---|
expression | string | The expression to be checked |
subjectClass | T | Either a string with the name of the subject class, or an object with the properties of the subject class. In the latter case, the first subject class that matches the given properties will be used. |
Returns
Promise
<boolean
>
Defined in
perspectives/PerspectiveProxy.ts:785
linkMutations
▸ linkMutations(mutations
, status?
): Promise
<LinkExpressionMutations
>
Applies a set of link mutations (adds and removes) in a single operation. Useful for atomic updates to the perspective.
Parameters
Name | Type | Default value | Description |
---|---|---|---|
mutations | LinkMutations | undefined | Object containing links to add and remove |
status | LinkStatus | 'shared' | Whether new links should be shared |
Returns
Promise
<LinkExpressionMutations
>
Object containing results of the mutations
Defined in
perspectives/PerspectiveProxy.ts:437
loadSnapshot
▸ loadSnapshot(snapshot
): Promise
<void
>
Loads a perspective snapshot, replacing current content.
Parameters
Name | Type | Description |
---|---|---|
snapshot | Perspective | Perspective snapshot to load |
Returns
Promise
<void
>
Defined in
perspectives/PerspectiveProxy.ts:574
remove
▸ remove(link
): Promise
<{ perspectiveRemoveLink
: boolean
}>
Removes a link from the perspective.
Parameters
Name | Type | Description |
---|---|---|
link | LinkExpressionInput | The link to remove |
Returns
Promise
<{ perspectiveRemoveLink
: boolean
}>
Defined in
perspectives/PerspectiveProxy.ts:467
removeLinks
▸ removeLinks(links
): Promise
<LinkExpression
[]>
Removes multiple links from the perspective.
Parameters
Name | Type | Description |
---|---|---|
links | LinkExpressionInput [] | Array of links to remove |
Returns
Promise
<LinkExpression
[]>
Array of removed LinkExpressions
Defined in
perspectives/PerspectiveProxy.ts:425
removeListener
▸ removeListener(type
, cb
): Promise
<void
>
Unsubscribes from link changes.
Parameters
Name | Type | Description |
---|---|---|
type | PerspectiveListenerTypes | Type of change to stop listening for |
cb | LinkCallback | The callback function to remove |
Returns
Promise
<void
>
Defined in
perspectives/PerspectiveProxy.ts:543
removeSubject
▸ removeSubject<T
>(subjectClass
, exprAddr
): Promise
<void
>
Removes a subject instance by running its (SDNA defined) destructor, which means removing links around the given expression address
Type parameters
Name |
---|
T |
Parameters
Name | Type | Description |
---|---|---|
subjectClass | T | Either a string with the name of the subject class, or an object with the properties of the subject class. In the latter case, the first subject class that matches the given properties will be used. |
exprAddr | string | The address of the expression to be turned into a subject instance |
Returns
Promise
<void
>
Defined in
perspectives/PerspectiveProxy.ts:768
runFlowAction
▸ runFlowAction(flowName
, exprAddr
, actionName
): Promise
<void
>
Runs given Social DNA flow action
Parameters
Name | Type |
---|---|
flowName | string |
exprAddr | string |
actionName | string |
Returns
Promise
<void
>
Defined in
perspectives/PerspectiveProxy.ts:682
sdnaFlows
▸ sdnaFlows(): Promise
<string
[]>
Returns all the Social DNA flows defined in this perspective
Returns
Promise
<string
[]>
Defined in
perspectives/PerspectiveProxy.ts:644
setSingleTarget
▸ setSingleTarget(link
, status?
): Promise
<void
>
Sets a single target value, removing any existing targets.
Parameters
Name | Type | Default value | Description |
---|---|---|---|
link | Link | undefined | Link defining the new target |
status | LinkStatus | 'shared' | Whether the link should be shared |
Returns
Promise
<void
>
Example
// Set a user's status
await perspective.setSingleTarget({
source: "did:key:alice",
predicate: "status",
target: "online"
});
Defined in
perspectives/PerspectiveProxy.ts:628
snapshot
▸ snapshot(): Promise
<Perspective
>
Creates a snapshot of the current perspective state. Useful for backup or sharing.
Returns
Promise
<Perspective
>
Perspective object containing all links
Defined in
perspectives/PerspectiveProxy.ts:565
startFlow
▸ startFlow(flowName
, exprAddr
): Promise
<void
>
Starts the Social DNA flow
Parameters
Name | Type | Description |
---|---|---|
flowName | string | on the expression |
exprAddr | string |
Returns
Promise
<void
>
Defined in
perspectives/PerspectiveProxy.ts:656
stringOrTemplateObjectToSubjectClassName
▸ stringOrTemplateObjectToSubjectClassName<T
>(subjectClass
): Promise
<string
>
Type parameters
Name |
---|
T |
Parameters
Name | Type |
---|---|
subjectClass | T |
Returns
Promise
<string
>
Defined in
perspectives/PerspectiveProxy.ts:714
subjectClasses
▸ subjectClasses(): Promise
<string
[]>
Returns all the Subject classes defined in this perspectives SDNA
Returns
Promise
<string
[]>
Defined in
perspectives/PerspectiveProxy.ts:706
subjectClassesByTemplate
▸ subjectClassesByTemplate(obj
): Promise
<string
[]>
Returns all subject classes that match the given template object. This function looks at the properties of the template object and its setters and collections to create a Prolog query that finds all subject classes that would be converted to a proxy object with exactly the same properties and collections.
Since there could be multiple subject classes that match the given criteria, this function returns a list of class names.
Parameters
Name | Type | Description |
---|---|---|
obj | object | The template object |
Returns
Promise
<string
[]>
Defined in
perspectives/PerspectiveProxy.ts:962
subscribeInfer
▸ subscribeInfer(query
): Promise
<QuerySubscriptionProxy
>
Creates a subscription for a Prolog query that updates in real-time.
Parameters
Name | Type | Description |
---|---|---|
query | string | Prolog query string |
Returns
Promise
<QuerySubscriptionProxy
>
QuerySubscriptionProxy instance
Example
// Subscribe to active todos
const subscription = await perspective.subscribeInfer(`
instance(Todo, "Todo"),
property_getter("Todo", Todo, "state", "active")
`);
subscription.onResult((todos) => {
console.log("Active todos:", todos);
});
Defined in
perspectives/PerspectiveProxy.ts:1030
update
▸ update(oldLink
, newLink
): Promise
<LinkExpression
>
Updates an existing link with new data.
Parameters
Name | Type | Description |
---|---|---|
oldLink | LinkExpressionInput | The existing link to update |
newLink | Link | The new link data |
Returns
Promise
<LinkExpression
>
Defined in
perspectives/PerspectiveProxy.ts:458