common: Move non operational functions to util namespace

[hunterachieng]

Summary

• Move non operational functions to util namespace
• Delete obsolete functions from common

Deleted Functions

• alterState()
• jsonValue()
• dataPath()
• dataValue()
• referencePath()
• lastReferenceValue()
• sourceValue()
• join

Moved Functions to util namespace

• asData()
• index()
• field()
• fields()
• source()
• chunk()
• humanProper()
• arrayToString()
• toArray()
• scrubEmojis()
• splitKeys()

Fixes #1118 #1408

Details

Add technical details of what you've changed (and why).

AI Usage

Please disclose how you've used AI in this work (it's cool, we just want to
know!):

• Code generation (copilot but not intellisense)
• Learning or fact checking
• Strategy / design
• Optimisation / refactoring
• Translation / spellchecking / doc gen
• Other
• I have not used AI

You can read more details in our
Responsible AI Policy

Review Checklist

Before merging, the reviewer should check the following items:

• Does the PR do what it claims to do?
• If this is a new adaptor, added the adaptor on marketing website ?
• If this PR includes breaking changes, do we need to update any jobs in
  production? Is it safe to release?
• Are there any unit tests?
• Is there a changeset associated with this PR? Should there be? Note that
  dev only changes don't need a changeset.
• Have you ticked a box under AI Usage?

[josephjclark]

I think we should insulate the other adaptors from a major bump and not force them to also use the util namespace. Not yet.

We can do this by re-writing the export statements to import the utils form the new location, but continue to export on the old interface.

For example if asana looks like this now:

export {
  fn,
  alterState,
  // etc
} from '@openfn/language-common';

We should change it to this:

export {
  fn,
  // etc
} from '@openfn/language-common';
export {
  alterState,
  // etc
} from '@openfn/language-common/util';

We can then migrate util functions out of other adaptors later. Else it's too much disruption

[josephjclark]

Hey @taylordowns2000 @mtuchi - I'm seriously considering dropping the functions listed above. They don't really fit modern job writing. In particular they would answer's Aleksa's call in Nairobi 2024 to "just give us one way to access state".

This is good for humans, but also good for AIs who are reading our docs and using them to write job code.

This would be a major update.

My questions are:

1. How do we feel about this generally?
2. How many workflows, if any, are using the listed functions? Can we tell?

[mtuchi]

@josephjclark i am totally okay on removing the mentioned functions. But we have to do internal audit to see how many jobs are using @latest adaptor with those functions to help communicating this major version bump early on

[mtuchi]

while we are here, can we also delete source

[josephjclark]

We're doing some analysis to try and work out the impact of this

At first glance is it looks like 40 steps on common@latest may be using the affected functions. But most of those are just using Array.join()

I'll do a bit more analysis but basically yes, I want to do this in January, and I want to insulate other adaptors from the changes

EDIT: Maybe just 7 steps that need modifying in practice

b887559c-dc7e-48ae-8cb3-6ab6e2001fff
b11b5447-a3af-4173-824d-1bf14eac5966
18e6ad83-38a4-418e-895d-8a13a40f5d14
8ca5cabd-fd16-4e76-b045-4e26f9a4ccaf
17ea3de3-534e-48e6-8ae7-c8683df4d7be
dbb363fe-17e8-48e2-83c6-ce2092924762
5bdfa76d-74b3-453e-bdc6-b5a8f55e22d6