artifacts.d.ts

/**
 * Generate the BLAKE3 hash of some input bytes
 */
export function makeReference(bytes: Uint8Array): Uint8Array;
/**
 * Convert the input bytes to a string using base58 encoding
 */
export function encode(bytes: Uint8Array): string;
/**
 * Decode base58-encoded bytes from a string
 */
export function decode(encoded: string): Uint8Array;
/**
 * Generate a unique, valid `Entity`
 */
export function generateEntity(): Uint8Array;
/**
 * Used to specify if an `Instruction` is an assertion or a retraction
 */
export enum InstructionType {
  /**
   * The `Instruction` is an assertion
   */
  Assert = 0,
  /**
   * The `Instruction` is a retraction
   */
  Retract = 1,
}
/**
 * [`ValueDataType`] embodies all types that are able to be represented
 * as a [`Value`].
 */
export enum ValueDataType {
  /**
   * An empty (null) value
   */
  Null = 0,
  /**
   * A byte buffer
   */
  Bytes = 1,
  /**
   * An [`Entity`]
   */
  Entity = 2,
  /**
   * A boolean
   */
  Boolean = 3,
  /**
   * A UTF-8 string
   */
  String = 4,
  /**
   * A 128-bit unsigned integer
   */
  UnsignedInt = 5,
  /**
   * A 128-bit signed integer
   */
  SignedInt = 6,
  /**
   * A floating point number
   */
  Float = 7,
  /**
   * TBD structured data (flatbuffers?)
   */
  Record = 8,
  /**
   * A symbol type, used to distinguish attributes from other strings
   */
  Symbol = 9,
}

/**
 * The predicate of a semantic triple
 */
type Attribute = string;

/**
 * The subject of a semantic triple; it must be exactly 32-bytes long.
 * A valid, unique `Entity` can be created using `generateEntity`.
 */
type Entity = Uint8Array;

/**
 * The object of a semantic triple. It's internal representation will
 * vary based on the value of the `type` property. For more details,
 * see the documentation on `ValueDataType`.
 */
interface Value {
  type: ValueDataType,
  value: null|Uint8Array|string|boolean|number
}

/**
 * An `Artifact` embodies a datum - a semantic triple - that may be stored in or
 * retrieved from `Artifacts`.
 */
interface Artifact {
  the: Attribute,
  of: Entity,
  is: Value
}

/**
 * The instruction variants that are accepted by `Artifacts.commit`.
 */
interface Instruction {
  type: InstructionType,
  artifact: Artifact
}

/**
 * The shape of the "iterable" that is expected by `Artifacts.commit`
 */
type InstructionIterable = Iterable<Instruction>;

/**
 * A basic filter that can be used to query `Artifacts`
 */
interface ArtifactSelector {
  the?: Attribute,
  of?: Entity,
  is?: Value
}

/**
 * The shape of the "async iterable" that is returned by `Artifacts.select`
 */
type ArtifactIterable = AsyncIterable<Artifact>;


/**
 * An async iterator that lazily yields `Artifact`s
 */
export class ArtifactIterator {
  private constructor();
  free(): void;
  /**
   * Get the next `Artifact` yielded by this iterator
   */
  next(): Promise<IteratorResult<Artifact>>;
}
/**
 * A triple store that can be used to store and retrieve semantic triples
 * in the form of `Artifact`s.
 */
export class Artifacts {
  private constructor();
  free(): void;
  /**
   * Construct a new `Artifacts`, backed by a database. If the same name is
   * used for multiple instances (or across sessions), the same database will
   * be used.
   *
   * An optional revision may be provided. If it is, the database will
   * attempt to open with the root at the specified revision.
   *
   * If no revision is specified, the database will start in an empty state
   * (with no query-able data; even when re-using a database that has data
   * stored in it).
   */
  static open(dbName: string, revision?: Uint8Array | null): Promise<Artifacts>;
  /**
   * Get the current revision of the triple store. This value will change on
   * every successful call to `Artifacts.commit`. The returned value is
   * suitable for use with `Artifacts.restore`, for example when re-opening
   * the triple store on future sessions.
   */
  revision(): Promise<Uint8Array | undefined>;
  /**
   * Persist a set of data in the triple store. The returned prommise
   * resolves when all data has been persisted and the revision has been
   * updated. Any data that does not match the expected shape of an
   * `Artifact` is quietly ignored (this is probably bad, but it is
   * expedient). If there is an error during the commit, the change is
   * abandoned and the revision remains the same as it was at the start of
   * the transaction.
   */
  commit(iterable: InstructionIterable): Promise<void>;
  /**
   * Query for `Artifact`s that match the given selector. Matching results
   * are provided via an async iterator.
   */
  select(selector: ArtifactSelector): ArtifactIterable;
}

example.ts

import { Artifacts, generateEntity, InstructionType, ValueDataType } from "dialog-artifacts";

let artifacts = await Artifacts.open("test");

await artifacts.commit([{
    type: InstructionType.Assert,
    artifact: {
        the: "profile/name",
        of: generateEntity(),
        is: {
            type: ValueDataType.String,
            value: "Foo Bar"
        }
    }
}]);

let query = artifacts.select({
    the: "profile/name"
});

for await (const element of query) {
    console.log('The', element.the, 'of', element.of, 'is', element.is);
}