Document that "at" and "get" have special meaning on steps

[benjie]

• at should accept a single number argument and implies that the step is list-like (and you're accessing that index)
• get should accept a single string argument and implies that the step is object-like (and you're accessing that key)

If steps implement these methods but don't conform to expectations, then odd things might happen.

[benjie]

See isObjectLikeStep and isListLikeStep functions (the latter is currently on a branch)

[benjie]

@jemgillam please can you add details of this convention to the Grafast docs, probably in the section talking about writing your own step classes (since these are step class methods)?

[jemgillam]

A plan resolver, rather than using access(), SHOULD use .get and .at methods if present on the steps you're interacting with.

This allows the step to learn more about how it is going to be used

eg optimize its fetching to only retrieve the requested attributes (select id, name, avatar from ... rather than select * from ...)

For some steps this is a MUST, for example if $user is a PgSelectSingleStep then $user.get('username') will represent the user's username; but access($user, 'username') will yield undefined since the internal representation of $user is actually a tuple (array) of just the attributes that were requested via .get(colName).

---

When writing a step class, if the step represents an object, you SHOULD implement .get. If a list or array, you SHOULD implement the .at method.

If optimizing isn't a concern, then you can implement those methods but you can defer to access under the hood. This means later you can refactor and optimize without affecting code using that step class.

class MyStep extends ExecutableStep {
  // ...
  
  // For steps representing objects:
  get(key) { return access(this, key); }

  // For steps representing lists:
  at(index) { return access(this, index); }

If your step implements a .at or .get method if MUST conform to the expectations; i.e. get() should accept a single argument, a string, representing an attribute to access on an object-like value, and at() should accept a single argument, an integer, representing the index within the list-like value which should be accessed. Grafast relies on these assumptions, so if your step implements .get() or .at() and does not conform, unexpected behaviors may be observed in some circumstances.

[jemgillam]

#263 might be related

[benjie]

#263 relates to FieldArgs, and though they adhere to the pattern of allowing .get('key') they don't otherwise overlap with this issue.