@ucanto/interface - npm Package Compare versions

Comparing version 7.1.0 to 8.0.0

dist/src/lib.d.ts

@@ -146,2 +146,9 @@ import { Ability, Block as UCANBlock, ByteView, Capabilities, Capability, DID, Fact, Link as UCANLink, MultihashHasher, MultihashDigest, MultibaseDecoder, MultibaseEncoder, Phantom, Resource, Signature, SignatureView, Principal, MulticodecCode, SigAlg, ToJSON, SignatureJSON, JSONUnknown, Crypto, JSONObject } from '@ipld/dag-ucan';
     delegate(): Await<Delegation<C>>;
+    archive(): Await<Result<Uint8Array, Error>>;
+    /**
+     * Attach a block to the delegation DAG so it would be included in the
+     * block iterator.
+     * ⚠️ You can only attach blocks that are referenced from the `capabilities`
+     * or `facts`.
+     */
     attach(block: Block): void;
@@ -283,5 +290,17 @@ }
 }
+/**
+ * Represents invocation in pre-invocation spec, which is simply a UCAN
+ * delegation with a single capability.
+ */
+export type ImpliedInvocationModel<C extends Capability = Capability> = UCAN.UCAN<[C]>;
+/**
+ * Currently we represent effects in non-standard format that uses links to
+ * {@link ImpliedInvocationModel} as opposed {@link InstructionModel}. We do
+ * such a representation because we do not have an invocation spec implemented
+ * yet and most things expect {@link ImpliedInvocationModel} in place if
+ * invocations & instructions.
+ */
 export interface EffectsModel {
-    fork: readonly Link<InstructionModel>[];
-    join?: Link<InstructionModel>;
+    fork: readonly Link<ImpliedInvocationModel>[];
+    join?: Link<ImpliedInvocationModel>;
 }
@@ -306,2 +325,55 @@ export interface Effects extends EffectsModel {
 /**
+ * Defines result & effect pair, used by provider that wish to return
+ * results that have effects.
+ */
+export type Transaction<T = unknown, X extends {} = {}> = Variant<{
+    ok: T;
+    error: X;
+    do: Do<T, X>;
+}>;
+export type InferTransaction<T extends Transaction> = T extends Transaction<infer Ok, infer Error> ? {
+    ok: Ok;
+    error: Error;
+} : never;
+export type Run = Link<ImpliedInvocationModel>;
+export interface Do<T = unknown, X extends {} = {}> {
+    out: Result<T, X>;
+    fx: Effects;
+}
+export interface OkBuilder<T extends unknown = undefined, X extends {} = {}> {
+    ok: T;
+    error?: undefined;
+    do?: undefined;
+    result: Result<T, X>;
+    effects: Effects;
+    fork(fx: Run): ForkBuilder<T, X>;
+    join(fx: Run): JoinBuilder<T, X>;
+}
+export interface ErrorBuilder<T extends unknown = undefined, X extends {} = {}> {
+    ok?: undefined;
+    error: X;
+    do?: undefined;
+    result: Result<T, X>;
+    effects: Effects;
+    fork(fx: Run): ForkBuilder<T, X>;
+    join(fx: Run): JoinBuilder<T, X>;
+}
+export interface ForkBuilder<T extends unknown = undefined, X extends {} = {}> {
+    ok?: undefined;
+    error?: undefined;
+    do: Do<T, X>;
+    result: Result<T, X>;
+    effects: Effects;
+    fork(fx: Run): ForkBuilder<T, X>;
+    join(fx: Run): JoinBuilder<T, X>;
+}
+export interface JoinBuilder<T extends unknown = unknown, X extends {} = {}> {
+    ok?: undefined;
+    error?: undefined;
+    do: Do<T, X>;
+    result: Result<T, X>;
+    effects: Effects;
+    fork(fx: Run): JoinBuilder<T, X>;
+}
+/**
  * @see {@link https://en.wikipedia.org/wiki/Unit_type|Unit type - Wikipedia}
@@ -367,2 +439,9 @@ */
     delegate(): Await<Delegation<[C]>>;
+    /**
+     * Attach a block to the invocation DAG so it would be included in the
+     * block iterator.
+     * ⚠️ You should only attach blocks that are referenced from the `capabilities`
+     * or `facts`, if that is not the case you probably should reconsider.
+     * ⚠️ Once a delegation is de-serialized the attached blocks will not be re-attached.
+     */
     attach(block: Block): void;
@@ -385,4 +464,10 @@ }
 export interface ServiceMethod<I extends Capability, O extends {}, X extends {}> {
-    (input: Invocation<I>, context: InvocationContext): Await<Result<O, X | InvocationError>>;
+    (input: Invocation<I>, context: InvocationContext): Await<Transaction<O, X | InvocationError>>;
 }
+export interface ProviderInput<T extends ParsedCapability> {
+    capability: T;
+    invocation: Invocation<Capability<T['can'], T['with'], T['nb']>>;
+    context: InvocationContext;
+}
+export type ProviderMethod<I extends ParsedCapability, O extends Transaction> = (input: ProviderInput<I>) => Await<O>;
 /**
@@ -394,3 +479,3 @@ * Error types returned by the framework during invocation that are not
 export interface InvocationContext extends ValidatorOptions {
-    id: Verifier;
+    id: Signer;
     resolve?: (proof: UCANLink) => Await<Result<Delegation, UnavailableProof>>;
@@ -397,0 +482,0 @@ principal: PrincipalParser;

package.json

 {
   "name": "@ucanto/interface",
   "description": "interface definitions for ucanto",
-  "version": "7.1.0",
+  "version": "8.0.0",
   "types": "./dist/src/lib.d.ts",
@@ -6,0 +6,0 @@ "main": "./src/lib.js",

src/lib.ts

@@ -85,3 +85,3 @@ import {
 
-export type BlockStore <T> = Map<ToString<Link>, Block<T, number, number, 1>>
+export type BlockStore<T> = Map<ToString<Link>, Block<T, number, number, 1>>
 export type AttachedLinkSet = Set<ToString<Link>>
@@ -250,2 +250,10 @@
 
+  archive(): Await<Result<Uint8Array, Error>>
+
+  /**
+   * Attach a block to the delegation DAG so it would be included in the
+   * block iterator.
+   * ⚠️ You can only attach blocks that are referenced from the `capabilities`
+   * or `facts`.
+   */
   attach(block: Block): void
@@ -460,8 +468,23 @@ }
 
+/**
+ * Represents invocation in pre-invocation spec, which is simply a UCAN
+ * delegation with a single capability.
+ */
+export type ImpliedInvocationModel<C extends Capability = Capability> =
+  UCAN.UCAN<[C]>
+
+/**
+ * Currently we represent effects in non-standard format that uses links to
+ * {@link ImpliedInvocationModel} as opposed {@link InstructionModel}. We do
+ * such a representation because we do not have an invocation spec implemented
+ * yet and most things expect {@link ImpliedInvocationModel} in place if
+ * invocations & instructions.
+ */
 export interface EffectsModel {
-  fork: readonly Link<InstructionModel>[]
-  join?: Link<InstructionModel>
+  fork: readonly Link<ImpliedInvocationModel>[]
+  join?: Link<ImpliedInvocationModel>
 }
 
 export interface Effects extends EffectsModel {}
+
 export interface InstructionModel<
@@ -490,2 +513,74 @@ Op extends Ability = Ability,
 /**
+ * Defines result & effect pair, used by provider that wish to return
+ * results that have effects.
+ */
+export type Transaction<T = unknown, X extends {} = {}> = Variant<{
+  ok: T
+  error: X
+  do: Do<T, X>
+}>
+
+export type InferTransaction<T extends Transaction> = T extends Transaction<
+  infer Ok,
+  infer Error
+>
+  ? { ok: Ok; error: Error }
+  : never
+
+export type Run = Link<ImpliedInvocationModel>
+
+export interface Do<T = unknown, X extends {} = {}> {
+  out: Result<T, X>
+  fx: Effects
+}
+
+export interface OkBuilder<T extends unknown = undefined, X extends {} = {}> {
+  ok: T
+  error?: undefined
+  do?: undefined
+
+  result: Result<T, X>
+  effects: Effects
+
+  fork(fx: Run): ForkBuilder<T, X>
+  join(fx: Run): JoinBuilder<T, X>
+}
+
+export interface ErrorBuilder<
+  T extends unknown = undefined,
+  X extends {} = {}
+> {
+  ok?: undefined
+  error: X
+  do?: undefined
+
+  result: Result<T, X>
+  effects: Effects
+
+  fork(fx: Run): ForkBuilder<T, X>
+  join(fx: Run): JoinBuilder<T, X>
+}
+
+export interface ForkBuilder<T extends unknown = undefined, X extends {} = {}> {
+  ok?: undefined
+  error?: undefined
+  do: Do<T, X>
+  result: Result<T, X>
+  effects: Effects
+
+  fork(fx: Run): ForkBuilder<T, X>
+  join(fx: Run): JoinBuilder<T, X>
+}
+
+export interface JoinBuilder<T extends unknown = unknown, X extends {} = {}> {
+  ok?: undefined
+  error?: undefined
+  do: Do<T, X>
+  result: Result<T, X>
+  effects: Effects
+
+  fork(fx: Run): JoinBuilder<T, X>
+}
+
+/**
  * @see {@link https://en.wikipedia.org/wiki/Unit_type|Unit type - Wikipedia}
@@ -556,2 +651,10 @@ */
   delegate(): Await<Delegation<[C]>>
+
+  /**
+   * Attach a block to the invocation DAG so it would be included in the
+   * block iterator.
+   * ⚠️ You should only attach blocks that are referenced from the `capabilities`
+   * or `facts`, if that is not the case you probably should reconsider.
+   * ⚠️ Once a delegation is de-serialized the attached blocks will not be re-attached.
+   */
   attach(block: Block): void
@@ -591,6 +694,18 @@ }
   (input: Invocation<I>, context: InvocationContext): Await<
-    Result<O, X | InvocationError>
+    Transaction<O, X | InvocationError>
   >
 }
 
+export interface ProviderInput<T extends ParsedCapability> {
+  capability: T
+  invocation: Invocation<Capability<T['can'], T['with'], T['nb']>>
+
+  context: InvocationContext
+}
+
+export type ProviderMethod<
+  I extends ParsedCapability,
+  O extends Transaction
+> = (input: ProviderInput<I>) => Await<O>
+
 /**
@@ -607,3 +722,3 @@ * Error types returned by the framework during invocation that are not
 export interface InvocationContext extends ValidatorOptions {
-  id: Verifier
+  id: Signer
 
@@ -610,0 +725,0 @@ resolve?: (proof: UCANLink) => Await<Result<Delegation, UnavailableProof>>

No alert changes

Improved metrics

Total package byte prevSize

140924

increased by6.57%

Lines of code

2885

increased by6.61%

No dependency changes