@dfinity/utils 0.0.1 → 0.0.2

package/README.md

@@ -1,3 +1,87 @@
 # utils-js
 
 A collection of utilities and constants for NNS/SNS projects.
+
+[![npm version](https://img.shields.io/npm/v/@dfinity/utils.svg?logo=npm)](https://www.npmjs.com/package/@dfinity/utils) [![GitHub license](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+
+## Table of contents
+
+- [Installation](#installation)
+- [Features](#features)
+
+## Installation
+
+You can use `utils-js` by installing it in your project.
+
+```bash
+npm i @dfinity/utils
+```
+
+The bundle needs peer dependencies, be sure that following resources are available in your project as well.
+
+```bash
+npm i @dfinity/agent @dfinity/candid @dfinity/principal
+```
+
+## Features
+
+`utils-js` implements following features:
+
+<!-- TSDOC_START -->
+
+### :toolbox: Functions
+
+- [defaultAgent](#gear-defaultagent)
+- [createServices](#gear-createservices)
+- [assertNonNullish](#gear-assertnonnullish)
+- [toNullable](#gear-tonullable)
+- [fromNullable](#gear-fromnullable)
+- [fromDefinedNullable](#gear-fromdefinednullable)
+
+#### :gear: defaultAgent
+
+| Function       | Type          |
+| -------------- | ------------- |
+| `defaultAgent` | `() => Agent` |
+
+#### :gear: createServices
+
+| Function         | Type                                                                                                                                                                                                                                                            |
+| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `createServices` | `<T>({ options: { canisterId, serviceOverride, certifiedServiceOverride, agent: agentOption, }, idlFactory, certifiedIdlFactory, }: { options: RequiredCanisterOptions<T>; idlFactory: InterfaceFactory; certifiedIdlFactory: InterfaceFactory; }) => { ...; }` |
+
+#### :gear: assertNonNullish
+
+| Function           | Type                                                                 |
+| ------------------ | -------------------------------------------------------------------- |
+| `assertNonNullish` | `<T>(value: T, message?: string) => asserts value is NonNullable<T>` |
+
+#### :gear: toNullable
+
+| Function     | Type                          |
+| ------------ | ----------------------------- |
+| `toNullable` | `<T>(value?: T) => [] or [T]` |
+
+#### :gear: fromNullable
+
+| Function       | Type                         |
+| -------------- | ---------------------------- |
+| `fromNullable` | `<T>(value: [] or [T]) => T` |
+
+#### :gear: fromDefinedNullable
+
+| Function              | Type                         |
+| --------------------- | ---------------------------- |
+| `fromDefinedNullable` | `<T>(value: [] or [T]) => T` |
+
+### :factory: NullishError
+
+#### Constructors
+
+`public`
+
+Parameters:
+
+- `message`
+
+<!-- TSDOC_END -->

package/dist/cjs/index.cjs.js

@@ -1,2 +1,2 @@
-"use strict";var i=Object.defineProperty;var f=Object.getOwnPropertyDescriptor;var T=Object.getOwnPropertyNames;var d=Object.prototype.hasOwnProperty;var m=(t,e)=>{for(var o in e)i(t,o,{get:e[o],enumerable:!0})},l=(t,e,o,p)=>{if(e&&typeof e=="object"||typeof e=="function")for(let n of T(e))!d.call(t,n)&&n!==o&&i(t,n,{get:()=>e[n],enumerable:!(p=f(e,n))||p.enumerable});return t};var x=t=>l(i({},"__esModule",{value:!0}),t);var y={};m(y,{NullishError:()=>s,assertNonNullish:()=>a,defaultAgent:()=>g,fromNullable:()=>u,toNullable:()=>c});module.exports=x(y);var r=require("@dfinity/agent"),g=()=>new r.HttpAgent({host:"https://ic0.app",identity:new r.AnonymousIdentity});var s=class extends Error{},a=(t,e)=>{if(t==null)throw new s(e)};var c=t=>t?[t]:[],u=t=>t==null?void 0:t[0];0&&(module.exports={NullishError,assertNonNullish,defaultAgent,fromNullable,toNullable});
+"use strict";var p=Object.defineProperty;var y=Object.getOwnPropertyDescriptor;var A=Object.getOwnPropertyNames;var g=Object.prototype.hasOwnProperty;var x=(t,e)=>{for(var o in e)p(t,o,{get:e[o],enumerable:!0})},b=(t,e,o,n)=>{if(e&&typeof e=="object"||typeof e=="function")for(let r of A(e))!g.call(t,r)&&r!==o&&p(t,r,{get:()=>e[r],enumerable:!(n=y(e,r))||n.enumerable});return t};var I=t=>b(p({},"__esModule",{value:!0}),t);var C={};x(C,{NullishError:()=>s,assertNonNullish:()=>m,createServices:()=>N,defaultAgent:()=>a,fromDefinedNullable:()=>O,fromNullable:()=>d,toNullable:()=>S});module.exports=I(C);var f=require("@dfinity/agent");var i=require("@dfinity/agent"),a=()=>new i.HttpAgent({host:"https://ic0.app",identity:new i.AnonymousIdentity});var N=({options:{canisterId:t,serviceOverride:e,certifiedServiceOverride:o,agent:n},idlFactory:r,certifiedIdlFactory:l})=>{let c=n??a(),T=e??f.Actor.createActor(r,{agent:c,canisterId:t}),u=o??f.Actor.createActor(l,{agent:c,canisterId:t});return{service:T,certifiedService:u,agent:c,canisterId:t}};var s=class extends Error{},m=(t,e)=>{if(t==null)throw new s(e)};var S=t=>t?[t]:[],d=t=>t==null?void 0:t[0],O=t=>{let e=d(t);return m(e),e};0&&(module.exports={NullishError,assertNonNullish,createServices,defaultAgent,fromDefinedNullable,fromNullable,toNullable});
 //# sourceMappingURL=index.cjs.js.map

package/dist/cjs/index.cjs.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
-  "sources": ["../../src/index.ts", "../../src/utils/agent.utils.ts", "../../src/utils/asserts.utils.ts", "../../src/utils/did.utils.ts"],
-  "sourcesContent": ["export * from \"./utils/agent.utils\";\nexport * from \"./utils/asserts.utils\";\nexport * from \"./utils/did.utils\";\n", "import type { Agent } from \"@dfinity/agent\";\nimport { AnonymousIdentity, HttpAgent } from \"@dfinity/agent\";\n\n/**\n * @returns The default agent to use. An agent that connects to mainnet with the anonymous identity.\n */\nexport const defaultAgent = (): Agent =>\n  new HttpAgent({\n    host: \"https://ic0.app\",\n    identity: new AnonymousIdentity(),\n  });\n", "export class NullishError extends Error {}\n\nexport const assertNonNullish: <T>(\n  value: T,\n  message?: string\n) => asserts value is NonNullable<T> = <T>(\n  value: T,\n  message?: string\n): void => {\n  if (value === null || value === undefined) {\n    throw new NullishError(message);\n  }\n};\n", "export const toNullable = <T>(value?: T): [] | [T] => {\n  return value ? [value] : [];\n};\n\nexport const fromNullable = <T>(value: [] | [T]): T | undefined => {\n  return value?.[0];\n};\n"],
-  "mappings": "yaAAA,qICCA,MAA6C,0BAKhC,EAAe,IAC1B,GAAI,aAAU,CACZ,KAAM,kBACN,SAAU,GAAI,oBAChB,CAAC,ECVI,GAAM,GAAN,aAA2B,MAAM,CAAC,EAE5B,EAG0B,CACrC,EACA,IACS,CACT,GAAI,GAAU,KACZ,KAAM,IAAI,GAAa,CAAO,CAElC,ECZO,GAAM,GAAa,AAAI,GACrB,EAAQ,CAAC,CAAK,EAAI,CAAC,EAGf,EAAe,AAAI,GACvB,iBAAQ",
+  "sources": ["../../src/index.ts", "../../src/utils/actor.utils.ts", "../../src/utils/agent.utils.ts", "../../src/utils/asserts.utils.ts", "../../src/utils/did.utils.ts"],
+  "sourcesContent": ["export type { CanisterOptions } from \"./types/canister.options\";\nexport * from \"./utils/actor.utils\";\nexport * from \"./utils/agent.utils\";\nexport * from \"./utils/asserts.utils\";\nexport * from \"./utils/did.utils\";\n", "import type { ActorSubclass, Agent } from \"@dfinity/agent\";\nimport { Actor } from \"@dfinity/agent\";\nimport type { IDL } from \"@dfinity/candid\";\nimport type { Principal } from \"@dfinity/principal\";\nimport type { CanisterOptions } from \"../types/canister.options\";\nimport { defaultAgent } from \"./agent.utils\";\n\ntype RequiredCanisterOptions<T> = Required<\n  Pick<CanisterOptions<T>, \"canisterId\">\n> &\n  Omit<CanisterOptions<T>, \"canisterId\">;\n\nexport const createServices = <T>({\n  options: {\n    canisterId,\n    serviceOverride,\n    certifiedServiceOverride,\n    agent: agentOption,\n  },\n  idlFactory,\n  certifiedIdlFactory,\n}: {\n  options: RequiredCanisterOptions<T>;\n  idlFactory: IDL.InterfaceFactory;\n  certifiedIdlFactory: IDL.InterfaceFactory;\n}): {\n  service: ActorSubclass<T>;\n  certifiedService: ActorSubclass<T>;\n  agent: Agent;\n  canisterId: Principal;\n} => {\n  const agent: Agent = agentOption ?? defaultAgent();\n\n  const service: ActorSubclass<T> =\n    serviceOverride ??\n    Actor.createActor<T>(idlFactory, {\n      agent,\n      canisterId,\n    });\n\n  const certifiedService: ActorSubclass<T> =\n    certifiedServiceOverride ??\n    Actor.createActor<T>(certifiedIdlFactory, {\n      agent,\n      canisterId,\n    });\n\n  return { service, certifiedService, agent, canisterId };\n};\n", "import type { Agent } from \"@dfinity/agent\";\nimport { AnonymousIdentity, HttpAgent } from \"@dfinity/agent\";\n\n/**\n * @returns The default agent to use. An agent that connects to mainnet with the anonymous identity.\n */\nexport const defaultAgent = (): Agent =>\n  new HttpAgent({\n    host: \"https://ic0.app\",\n    identity: new AnonymousIdentity(),\n  });\n", "export class NullishError extends Error {}\n\nexport const assertNonNullish: <T>(\n  value: T,\n  message?: string\n) => asserts value is NonNullable<T> = <T>(\n  value: T,\n  message?: string\n): void => {\n  if (value === null || value === undefined) {\n    throw new NullishError(message);\n  }\n};\n", "import { assertNonNullish } from \"./asserts.utils\";\n\nexport const toNullable = <T>(value?: T): [] | [T] => {\n  return value ? [value] : [];\n};\n\nexport const fromNullable = <T>(value: [] | [T]): T | undefined => {\n  return value?.[0];\n};\n\nexport const fromDefinedNullable = <T>(value: [] | [T]): T => {\n  const result = fromNullable(value);\n\n  assertNonNullish(result);\n\n  return result;\n};\n"],
+  "mappings": "yaAAA,oLCCA,MAAsB,0BCAtB,MAA6C,0BAKhC,EAAe,IAC1B,GAAI,aAAU,CACZ,KAAM,kBACN,SAAU,GAAI,oBAChB,CAAC,EDEI,GAAM,GAAiB,CAAI,CAChC,QAAS,CACP,aACA,kBACA,2BACA,MAAO,GAET,aACA,yBAUG,CACH,GAAM,GAAe,GAAe,EAAa,EAE3C,EACJ,GACA,QAAM,YAAe,EAAY,CAC/B,QACA,YACF,CAAC,EAEG,EACJ,GACA,QAAM,YAAe,EAAqB,CACxC,QACA,YACF,CAAC,EAEH,MAAO,CAAE,UAAS,mBAAkB,QAAO,YAAW,CACxD,EEhDO,GAAM,GAAN,aAA2B,MAAM,CAAC,EAE5B,EAG0B,CACrC,EACA,IACS,CACT,GAAI,GAAU,KACZ,KAAM,IAAI,GAAa,CAAO,CAElC,ECVO,GAAM,GAAa,AAAI,GACrB,EAAQ,CAAC,CAAK,EAAI,CAAC,EAGf,EAAe,AAAI,GACvB,iBAAQ,GAGJ,EAAsB,AAAI,GAAuB,CAC5D,GAAM,GAAS,EAAa,CAAK,EAEjC,SAAiB,CAAM,EAEhB,CACT",
   "names": []
 }

package/dist/esm/index.js

@@ -1,2 +1,2 @@
-import{AnonymousIdentity as o,HttpAgent as r}from"@dfinity/agent";var i=()=>new r({host:"https://ic0.app",identity:new o});var e=class extends Error{},l=(t,n)=>{if(t==null)throw new e(n)};var T=t=>t?[t]:[],a=t=>t?.[0];export{e as NullishError,l as assertNonNullish,i as defaultAgent,a as fromNullable,T as toNullable};
+import{Actor as i}from"@dfinity/agent";import{AnonymousIdentity as d,HttpAgent as T}from"@dfinity/agent";var n=()=>new T({host:"https://ic0.app",identity:new d});var b=({options:{canisterId:t,serviceOverride:e,certifiedServiceOverride:c,agent:p},idlFactory:a,certifiedIdlFactory:f})=>{let r=p??n(),l=e??i.createActor(a,{agent:r,canisterId:t}),m=c??i.createActor(f,{agent:r,canisterId:t});return{service:l,certifiedService:m,agent:r,canisterId:t}};var o=class extends Error{},s=(t,e)=>{if(t==null)throw new o(e)};var O=t=>t?[t]:[],u=t=>t?.[0],v=t=>{let e=u(t);return s(e),e};export{o as NullishError,s as assertNonNullish,b as createServices,n as defaultAgent,v as fromDefinedNullable,u as fromNullable,O as toNullable};
 //# sourceMappingURL=index.js.map

package/dist/esm/index.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
-  "sources": ["../../src/utils/agent.utils.ts", "../../src/utils/asserts.utils.ts", "../../src/utils/did.utils.ts"],
-  "sourcesContent": ["import type { Agent } from \"@dfinity/agent\";\nimport { AnonymousIdentity, HttpAgent } from \"@dfinity/agent\";\n\n/**\n * @returns The default agent to use. An agent that connects to mainnet with the anonymous identity.\n */\nexport const defaultAgent = (): Agent =>\n  new HttpAgent({\n    host: \"https://ic0.app\",\n    identity: new AnonymousIdentity(),\n  });\n", "export class NullishError extends Error {}\n\nexport const assertNonNullish: <T>(\n  value: T,\n  message?: string\n) => asserts value is NonNullable<T> = <T>(\n  value: T,\n  message?: string\n): void => {\n  if (value === null || value === undefined) {\n    throw new NullishError(message);\n  }\n};\n", "export const toNullable = <T>(value?: T): [] | [T] => {\n  return value ? [value] : [];\n};\n\nexport const fromNullable = <T>(value: [] | [T]): T | undefined => {\n  return value?.[0];\n};\n"],
-  "mappings": "AACA,kEAKO,GAAM,GAAe,IAC1B,GAAI,GAAU,CACZ,KAAM,kBACN,SAAU,GAAI,EAChB,CAAC,ECVI,GAAM,GAAN,aAA2B,MAAM,CAAC,EAE5B,EAG0B,CACrC,EACA,IACS,CACT,GAAI,GAAU,KACZ,KAAM,IAAI,GAAa,CAAO,CAElC,ECZO,GAAM,GAAa,AAAI,GACrB,EAAQ,CAAC,CAAK,EAAI,CAAC,EAGf,EAAe,AAAI,GACvB,IAAQ",
+  "sources": ["../../src/utils/actor.utils.ts", "../../src/utils/agent.utils.ts", "../../src/utils/asserts.utils.ts", "../../src/utils/did.utils.ts"],
+  "sourcesContent": ["import type { ActorSubclass, Agent } from \"@dfinity/agent\";\nimport { Actor } from \"@dfinity/agent\";\nimport type { IDL } from \"@dfinity/candid\";\nimport type { Principal } from \"@dfinity/principal\";\nimport type { CanisterOptions } from \"../types/canister.options\";\nimport { defaultAgent } from \"./agent.utils\";\n\ntype RequiredCanisterOptions<T> = Required<\n  Pick<CanisterOptions<T>, \"canisterId\">\n> &\n  Omit<CanisterOptions<T>, \"canisterId\">;\n\nexport const createServices = <T>({\n  options: {\n    canisterId,\n    serviceOverride,\n    certifiedServiceOverride,\n    agent: agentOption,\n  },\n  idlFactory,\n  certifiedIdlFactory,\n}: {\n  options: RequiredCanisterOptions<T>;\n  idlFactory: IDL.InterfaceFactory;\n  certifiedIdlFactory: IDL.InterfaceFactory;\n}): {\n  service: ActorSubclass<T>;\n  certifiedService: ActorSubclass<T>;\n  agent: Agent;\n  canisterId: Principal;\n} => {\n  const agent: Agent = agentOption ?? defaultAgent();\n\n  const service: ActorSubclass<T> =\n    serviceOverride ??\n    Actor.createActor<T>(idlFactory, {\n      agent,\n      canisterId,\n    });\n\n  const certifiedService: ActorSubclass<T> =\n    certifiedServiceOverride ??\n    Actor.createActor<T>(certifiedIdlFactory, {\n      agent,\n      canisterId,\n    });\n\n  return { service, certifiedService, agent, canisterId };\n};\n", "import type { Agent } from \"@dfinity/agent\";\nimport { AnonymousIdentity, HttpAgent } from \"@dfinity/agent\";\n\n/**\n * @returns The default agent to use. An agent that connects to mainnet with the anonymous identity.\n */\nexport const defaultAgent = (): Agent =>\n  new HttpAgent({\n    host: \"https://ic0.app\",\n    identity: new AnonymousIdentity(),\n  });\n", "export class NullishError extends Error {}\n\nexport const assertNonNullish: <T>(\n  value: T,\n  message?: string\n) => asserts value is NonNullable<T> = <T>(\n  value: T,\n  message?: string\n): void => {\n  if (value === null || value === undefined) {\n    throw new NullishError(message);\n  }\n};\n", "import { assertNonNullish } from \"./asserts.utils\";\n\nexport const toNullable = <T>(value?: T): [] | [T] => {\n  return value ? [value] : [];\n};\n\nexport const fromNullable = <T>(value: [] | [T]): T | undefined => {\n  return value?.[0];\n};\n\nexport const fromDefinedNullable = <T>(value: [] | [T]): T => {\n  const result = fromNullable(value);\n\n  assertNonNullish(result);\n\n  return result;\n};\n"],
+  "mappings": "AACA,uCCAA,kEAKO,GAAM,GAAe,IAC1B,GAAI,GAAU,CACZ,KAAM,kBACN,SAAU,GAAI,EAChB,CAAC,EDEI,GAAM,GAAiB,CAAI,CAChC,QAAS,CACP,aACA,kBACA,2BACA,MAAO,GAET,aACA,yBAUG,CACH,GAAM,GAAe,GAAe,EAAa,EAE3C,EACJ,GACA,EAAM,YAAe,EAAY,CAC/B,QACA,YACF,CAAC,EAEG,EACJ,GACA,EAAM,YAAe,EAAqB,CACxC,QACA,YACF,CAAC,EAEH,MAAO,CAAE,UAAS,mBAAkB,QAAO,YAAW,CACxD,EEhDO,GAAM,GAAN,aAA2B,MAAM,CAAC,EAE5B,EAG0B,CACrC,EACA,IACS,CACT,GAAI,GAAU,KACZ,KAAM,IAAI,GAAa,CAAO,CAElC,ECVO,GAAM,GAAa,AAAI,GACrB,EAAQ,CAAC,CAAK,EAAI,CAAC,EAGf,EAAe,AAAI,GACvB,IAAQ,GAGJ,EAAsB,AAAI,GAAuB,CAC5D,GAAM,GAAS,EAAa,CAAK,EAEjC,SAAiB,CAAM,EAEhB,CACT",
   "names": []
 }

package/dist/types/index.d.ts

@@ -1,3 +1,5 @@
+export type { CanisterOptions } from "./types/canister.options";
+export * from "./utils/actor.utils";
 export * from "./utils/agent.utils";
 export * from "./utils/asserts.utils";
 export * from "./utils/did.utils";

package/dist/types/types/canister.options.d.ts

@@ -0,0 +1,8 @@
+import type { ActorSubclass, Agent } from "@dfinity/agent";
+import type { Principal } from "@dfinity/principal";
+export interface CanisterOptions<T> {
+    agent?: Agent;
+    canisterId?: Principal;
+    serviceOverride?: ActorSubclass<T>;
+    certifiedServiceOverride?: ActorSubclass<T>;
+}

package/dist/types/utils/actor.utils.d.ts

@@ -0,0 +1,16 @@
+import type { ActorSubclass, Agent } from "@dfinity/agent";
+import type { IDL } from "@dfinity/candid";
+import type { Principal } from "@dfinity/principal";
+import type { CanisterOptions } from "../types/canister.options";
+declare type RequiredCanisterOptions<T> = Required<Pick<CanisterOptions<T>, "canisterId">> & Omit<CanisterOptions<T>, "canisterId">;
+export declare const createServices: <T>({ options: { canisterId, serviceOverride, certifiedServiceOverride, agent: agentOption, }, idlFactory, certifiedIdlFactory, }: {
+    options: RequiredCanisterOptions<T>;
+    idlFactory: IDL.InterfaceFactory;
+    certifiedIdlFactory: IDL.InterfaceFactory;
+}) => {
+    service: ActorSubclass<T>;
+    certifiedService: ActorSubclass<T>;
+    agent: Agent;
+    canisterId: Principal;
+};
+export {};

package/dist/types/utils/did.utils.d.ts

@@ -1,2 +1,3 @@
 export declare const toNullable: <T>(value?: T | undefined) => [] | [T];
 export declare const fromNullable: <T>(value: [] | [T]) => T | undefined;
+export declare const fromDefinedNullable: <T>(value: [] | [T]) => T;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dfinity/utils",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "description": "A collection of utilities and constants for NNS/SNS projects.",
   "license": "Apache-2.0",
   "main": "dist/cjs/index.cjs.js",