fix(naming): rename getRecord[s] to getArNSRecord[s]

README.md

@@ -1,9 +1,12 @@
 # @ar-io/sdk
 
-This is the home of ar.io SDK. This SDK provides functionality for interacting with the ArNS and ar.io ecosystem. It is available for both NodeJS and Web environments.
+This is the home of ar.io SDK. This SDK provides functionality for interacting with the ar.io ecosystem of services (e.g. gateways and observers) and protocols (e.g. ArNS). It is available for both NodeJS and Web environments.
 
 ## Table of Contents
 
+// ALM - Consider hoisting requirements before installation, e.g. Prerequisites header
+
+- [Prerequisites](#prerequisites)
 - [Installation](#installation)
 - [Quick Start](#quick-start)
 - [Usage](#usage)
@@ -20,6 +23,11 @@ This is the home of ar.io SDK. This SDK provides functionality for interacting w
   - [Architecture](#architecture)
 - [Contributing](./CONTRIBUTING.md)
 
+## Prerequisites
+
+- Node XYZ or above
+- npm or yarn package managers
+
 ## Installation
 
 ```shell
@@ -39,11 +47,13 @@ import { ArIO } from '@ar-io/sdk';
 
 const arIO = new ArIO();
 const gateways = arIO.testnet.getGateways();
+
+// PRINT/ EXPLAIN WHATEVER THIS GIVES YOU
 ```
 
 ## Usage
 
-The SDK is provided in both CommonJS and ESM formats, and it's compatible with bundlers such as Webpack, Rollup, and ESbuild. Utilize the appropriately named exports provided by this SDK's [package.json] based on your project's configuration. Refer to the [examples] directory to see how to use the SDK in various environments.
+The SDK is provided in both CommonJS and ESM formats and is compatible with bundlers such as Webpack, Rollup, and ESbuild. Utilize the appropriately named exports provided by this SDK's [package.json] based on your project's configuration. Refer to the [examples] directory to see how to use the SDK in various environments.
 
 ### Web
 
@@ -53,6 +63,9 @@ The SDK is provided in both CommonJS and ESM formats, and it's compatible with b
 import { ArIO } from '@ar-io/sdk';
 
 const arIO = new ArIO();
+// ALM - I DON'T LIKE THIS PATTERN OF SPECIFYING THE ENVIRONMENT ON EACH API CALL.
+// IT WILL BE REDUNDANT CODE IN 99% OF PLACES. FAVOR INSTEAD INSTANTIATING ArIO
+// WITH THE APPROPRIATE ENVIRONMENT CONFIGURATION
 const gateways = arIO.mainnet.getGateways();
 ```
 
@@ -82,17 +95,31 @@ const gateways = await arIO.mainnet.getGateways();
 
 The SDK provides TypeScript types. When you import the SDK in a TypeScript project:
 
+// ALM - "and should be automatically recognized," ... by?
 Types are exported from `./lib/types/[node/web]/index.d.ts` and should be automatically recognized, offering benefits such as type-checking and autocompletion.
 
 ## APIs
 
+// I'd like to see an instantiation example here with explanations about:
+
+- warp configuration
+- using API vs. using warp directly
+- caching configuration options and tradeoffs
+
+// I'd like to see an example of the returned objects in each example below, either a printout of their console log representation or an interface definition.
+
+// ALM - I don't like this pattern. I'm ok with us providing constants for known/trusted contracts. Also worth disambiguating the environenments - i.e. their purposes.
 The contract that the following methods retrieve data from are determined by the `testnet` or `devnet` clients - see examples above for implementation details.
 
 #### `getBalance({ address })`
 
 Retrieves the balance of the specified address.
 
 ```typescript
+// ALM - REPEATING THE new ArIO() pattern in each example might be misconstrued by less
+// sophisticated devs as necessary or beneficial. Better to have the instantiation example
+// explain the benefits of preserving a reference (e.g. caching and memory management) and
+// then use the instantiated reference in each of the subsequent examples.
 const balance = new ArIO().testnet.getBalance({
   address: 'INSERT_WALLET_ADDRESS',
 });
@@ -103,6 +130,9 @@ const balance = new ArIO().testnet.getBalance({
 Retrieves the balances of the ArIO contract.
 
 ```typescript
+// ALM - A part of me wonders whether streaming JSON might be beneficial in the future
+// and if providing streaming versions of these APIs will scale nicely longer term, e.g.
+// arIO.streamBalances({ sortingCriteria: BALANCE_DESC });
 const balances = new ArIO().testnet.getBalances();
 ```
 
@@ -124,20 +154,20 @@ Retrieves the registered gateways of the ArIO contract.
 const gateways = new ArIO().testnet.getGateways();
 ```
 
-#### `getRecord({ domain })`
+#### `getArNSRecord({ domain })`
 
 Retrieves the domain info of the specified ArNS record.
 
 ```typescript
-const record = new ArIO().testnet.getRecord({ domain: 'INSERT_ARNS_NAME' });
+const record = new ArIO().testnet.getArNSRecord({ domain: 'INSERT_ARNS_NAME' });
 ```
 
-#### `getRecords()`
+#### `getArNSRecords()`
 
 Retrieves the registered ArNS domains of the ArIO contract.
 
 ```typescript
-const records = new ArIO().testnet.getRecords();
+const records = new ArIO().testnet.getArNSRecords();
 ```
 
 ## Developers

examples/node/index.cjs

@@ -10,8 +10,8 @@ const {
   const protocolBalance = await arIO.testnet.getBalance({
     address: ARNS_TESTNET_REGISTRY_TX,
   });
-  const ardriveRecord = await arIO.testnet.getRecord({ domain: 'ardrive' });
-  const allRecords = await arIO.testnet.getRecords();
+  const ardriveRecord = await arIO.testnet.getArNSRecord({ domain: 'ardrive' });
+  const allRecords = await arIO.testnet.getArNSRecords();
 
   console.dir(
     {

examples/node/index.mjs

@@ -7,8 +7,8 @@ import { ARNS_TESTNET_REGISTRY_TX, ArIO } from '../../lib/esm/node/index.js';
   const protocolBalance = await arIO.testnet.getBalance({
     address: ARNS_TESTNET_REGISTRY_TX,
   });
-  const ardriveRecord = await arIO.testnet.getRecord({ domain: 'ardrive' });
-  const allRecords = await arIO.testnet.getRecords();
+  const ardriveRecord = await arIO.testnet.getArNSRecord({ domain: 'ardrive' });
+  const allRecords = await arIO.testnet.getArNSRecords();
 
   console.dir(
     {

examples/web/index.html

@@ -95,8 +95,8 @@ <h1 class="text-textPrimary w-full font-bold">Browse Records</h1>
         const balance = await arIO.getBalance({
           address: '7waR8v4STuwPnTck1zFVkQqJh5K9q9Zik4Y5-5dV7nk',
         });
-        const record = await arIO.getRecord({ domain: 'ardrive' });
-        const records = await arIO.getRecords();
+        const record = await arIO.getArNSRecord({ domain: 'ardrive' });
+        const records = await arIO.getArNSRecords();
 
         //  update the UI
 

src/common/caches/arns-remote-cache.ts

@@ -104,7 +104,7 @@ export class ArNSRemoteCache implements ArIOContract {
     return result;
   }
 
-  async getRecord({ domain }: { domain: string }): Promise<ArNSNameData> {
+  async getArNSRecord({ domain }: { domain: string }): Promise<ArNSNameData> {
     this.logger.debug(`Fetching record for ${domain}`);
     const { result } = await this.http.get<
       ArNSStateResponse<'result', ArNSNameData>
@@ -114,7 +114,7 @@ export class ArNSRemoteCache implements ArIOContract {
     return result;
   }
 
-  async getRecords(): Promise<Record<string, ArNSNameData>> {
+  async getArNSRecords(): Promise<Record<string, ArNSNameData>> {
     this.logger.debug(`Fetching all records`);
     const { result } = await this.http.get<
       ArNSStateResponse<'result', Record<string, ArNSNameData>>

src/types/common.ts

@@ -22,8 +22,8 @@ export interface ArIOContract {
   getGateways(): Promise<Record<WalletAddress, Gateway>>;
   getBalance({ address }: { address: WalletAddress }): Promise<number>;
   getBalances(): Promise<Record<WalletAddress, number>>;
-  getRecord({ domain }: { domain: string }): Promise<ArNSNameData>;
-  getRecords(): Promise<Record<string, ArNSNameData>>;
+  getArNSRecord({ domain }: { domain: string }): Promise<ArNSNameData>;
+  getArNSRecords(): Promise<Record<string, ArNSNameData>>;
 }
 
 /* eslint-disable @typescript-eslint/no-explicit-any */

tests/arns-remote-cache.test.ts

@@ -34,23 +34,23 @@ describe('ArNSRemoteCache', () => {
 
   // records tests
   it('should fetch a record', async () => {
-    const record = await remoteCacheProvider.getRecord({
+    const record = await remoteCacheProvider.getArNSRecord({
       domain: 'ar-io',
     });
     expect(record).toBeDefined();
   });
 
   it('should throw NotFound error on non existent record', async () => {
     const error = await remoteCacheProvider
-      .getRecord({
+      .getArNSRecord({
         domain: 'some-domain',
       })
       .catch((e) => e);
     expect(error).toBeInstanceOf(NotFound);
   });
 
   it('should fetch all records', async () => {
-    const records = await remoteCacheProvider.getRecords();
+    const records = await remoteCacheProvider.getArNSRecords();
 
     expect(records).toBeDefined();
   });