Unverified Commit 39e67fad authored by pospi's avatar pospi Committed by GitHub
Browse files

Merge pull request #60 from valueflows/npm-publish-commands

Npm publish commands & 0.3.0 release
parents ad79c2c3 6d31a5b2
node_modules/
lib/build/
lib/index.d.ts
lib/index.flow.js
lib/LICENSE
lib/README.md
Copyright 2019 ValueFlows contributors
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
......@@ -2,9 +2,6 @@
Reference GraphQL implementation of the ValueFlows spec
**WORK IN PROGRESS!**
Some fields & structures still subject to change and may evolve until the spec settles.
<!-- MarkdownTOC -->
- [Setup](#setup)
......@@ -13,7 +10,9 @@ Some fields & structures still subject to change and may evolve until the spec s
- [Available commands](#available-commands)
- [Contributing](#contributing)
- [Directory structure](#directory-structure)
- [Publishing to NPM](#publishing-to-npm)
- [Implementing](#implementing)
- [License](#license)
<!-- /MarkdownTOC -->
......@@ -54,6 +53,13 @@ The `lib/` directory contains all source of the reference schema & validation he
- `schemas/` contains the actual GraphQL schema definition files. **These are the files you should edit.**
- `build/` and `index.d.ts` are generated from the schema files, using helper code in `lib/scripts/`.
### Publishing to NPM
- You will need to be given access to the [VF NPM org](https://www.npmjs.com/org/valueflows) in order to update the module on the registry. You can request access in https://gitter.im/valueflows/welcome
- Bump the version in `lib/package.json` & commit to the repository
- Run `npm run publish` from this directory
- Tag the current release in git and push the tag to `master`
## Implementing
......@@ -64,3 +70,10 @@ To implement a system gateway compatible with the ValueFlows spec, you will need
- [Scalar type resolvers](https://www.apollographql.com/docs/graphql-tools/scalars.html) for the ISO8601 `DateTime` & `DateInterval` types
For a more detailed example, see the project in `./mock-server/`.
## License
Released under an Apache 2.0 license.
// Generated by scripts/build.js - edit the *.gql file instead!
module.exports = `
##
#
# Agent module
#
# All functionality related to the definition of autonomous agents
# (people, organizations, groups) and their relationships.
#
#
##
"Query parameters for reading \`EconomicResource\`s related to an \`Agent\`"
input agentResourceSearchParams {
searchString: String
resourceClassification: URI
page: Int
}
"Query parameters for reading \`Process\`es related to an \`Agent\`"
input agentProcessSearchParams {
searchString: String
finished: Boolean
}
"Query parameters for reading \`Plan\`s related to an \`Agent\`"
input agentPlanSearchParams {
searchString: String
finished: Boolean
}
"Query parameters for reading \`EconomicEvent\`s related to an \`Agent\`"
input agentEventSearchParams {
searchString: String
action: ID
startDate: DateTime
endDate: DateTime
}
"Query parameters for reading \`Commitment\`s related to an \`Agent\`"
input agentCommitmentSearchParams {
searchString: String
action: ID
startDate: DateTime
endDate: DateTime
finished: Boolean
}
input agentIntentSearchParams {
searchString: String
action: ID
startDate: DateTime
endDate: DateTime
finished: Boolean
}
"""
A person or group or organization with economic agency.
"""
interface Agent {
id: ID!
"An informal or formal textual identifier for an agent. Does not imply uniqueness."
name: String!
"The uri to an image relevant to the agent, such as a logo, avatar, photo, etc."
image: URI
"The main place an agent is located, often an address where activities occur and mail can be sent. This is usually a mappable geographic location. It also could be a website address, as in the case of agents who have no physical location."
primaryLocation: SpatialThing
"A textual description or comment."
note: String
##############################################################################
# inverse relationships and queries
inventoriedEconomicResources(filter: agentResourceSearchParams): [EconomicResource!]
economicEvents(filter: agentEventSearchParams): [EconomicEvent!]
processes(filter: agentProcessSearchParams): [Process!]
commitments(filter: agentCommitmentSearchParams): [Commitment!]
intents(filter: agentIntentSearchParams): [Intent!]
plans(filter: agentPlanSearchParams): [Plan!]
relationships(roleId: ID): [AgentRelationship!] # :TODO: category filtering
relationshipsAsSubject(roleId: ID): [AgentRelationship!] # :TODO: category filtering
relationshipsAsObject(roleId: ID): [AgentRelationship!] # :TODO: category filtering
roles: [AgentRelationshipRole!]
}
# Variants of agents
"""
A natural person.
"""
type Person implements Agent {
id: ID!
"The name that this agent will be referred to by."
name: String!
"The uri to an image relevant to the agent, such as a logo, avatar, photo, etc."
image: URI
"The main place an agent is located, often an address where activities occur and mail can be sent. This is usually a mappable geographic location. It also could be a website address, as in the case of agents who have no physical location."
primaryLocation: SpatialThing
"A textual description or comment."
note: String
##############################################################################
# inverse relationships and queries
inventoriedEconomicResources(filter: agentResourceSearchParams): [EconomicResource!]
economicEvents(filter: agentEventSearchParams): [EconomicEvent!]
processes(filter: agentProcessSearchParams): [Process!]
commitments(filter: agentCommitmentSearchParams): [Commitment!]
intents(filter: agentIntentSearchParams): [Intent!]
plans(filter: agentPlanSearchParams): [Plan!]
relationships(roleId: ID): [AgentRelationship!] # :TODO: category filtering
relationshipsAsSubject(roleId: ID): [AgentRelationship!] # :TODO: category filtering
relationshipsAsObject(roleId: ID): [AgentRelationship!] # :TODO: category filtering
roles: [AgentRelationshipRole!]
}
"""
A formal or informal group, or legal organization.
"""
type Organization implements Agent {
id: ID!
# :TODO: define how people can create further typing of Organization
# type: OrganizationClassification
"The name that this agent will be referred to by."
name: String!
"The uri to an image relevant to the agent, such as a logo, avatar, photo, etc."
image: URI
"The main place an agent is located, often an address where activities occur and mail can be sent. This is usually a mappable geographic location. It also could be a website address, as in the case of agents who have no physical location."
primaryLocation: SpatialThing
"A textual description or comment."
note: String
##############################################################################
# inverse relationships and queries
inventoriedEconomicResources(filter: agentResourceSearchParams): [EconomicResource!]
economicEvents(filter: agentEventSearchParams): [EconomicEvent!]
processes(filter: agentProcessSearchParams): [Process!]
commitments(filter: agentCommitmentSearchParams): [Commitment!]
intents(filter: agentIntentSearchParams): [Intent!]
plans(filter: agentPlanSearchParams): [Plan!]
relationships(roleId: ID): [AgentRelationship!] # :TODO: category filtering
relationshipsAsSubject(roleId: ID): [AgentRelationship!] # :TODO: category filtering
relationshipsAsObject(roleId: ID): [AgentRelationship!] # :TODO: category filtering
roles: [AgentRelationshipRole!]
}
# Relationships between agents
"""
The role of an economic relationship that exists between 2 agents, such as member, trading partner.
"""
type AgentRelationship {
id: ID!
"The subject of a relationship between 2 agents. For example, if Mary is a member of a group, then Mary is the subject."
subject: Agent!
"The object of a relationship between 2 agents. For example, if Mary is a member of a group, then the group is the object."
object: Agent!
"A kind of relationship that exists between 2 agents."
relationship: AgentRelationshipRole!
"Grouping around something to create a boundary or context, used for documenting, accounting, planning."
inScopeOf: [AnyType!]
"A textual description or comment."
note: String
}
"""
A relationship role defining the kind of association one agent can have with another.
"""
type AgentRelationshipRole {
id: ID!
"The human readable name of the role, from the subject to the object."
label: String!
"The human readable name of the role, from the object to the subject."
inverseLabel: String
"A textual description or comment."
note: String
# :TODO: https://github.com/valueflows/valueflows/issues/494
}
# :TODO: how do we want to do this concept?
# """
# Generalized behaviors for agent relationship roles
# """
# enum AgentRelationshipCategory {
# LEGALPARTNER
# MEMBER
# PART
# PEER
# TRADINGPARTNER
# }
`
// Generated by scripts/build.js - edit the *.gql file instead!
module.exports = `
##
#
# Knowledge layer
#
# Provides functionality for classifying and organising other parts of the system, including recipes.
#
#
##
"""
An action verb defining the kind of event, commitment, or intent.
It is recommended that the lowercase action verb should be used as the record ID
in order that references to \`Action\`s elsewhere in the system are easily readable.
"""
type Action {
id: ID!
"A unique verb which defines the action."
label: String!
"The effect of an economic event on a resource, increment, decrement, no effect, or decrement resource and increment 'to' resource."
resourceEffect: String! # "+", "-", "0", "-+"
}
# Core VF action IDs & \`resourceEffect\`s:
# @see https://github.com/valueflows/valueflows/issues/487
# dropoff (+) transported resource or person leaves the process, the same resource will appear in input with vf:pickup verb
# pickup (-) transported resource or person enters the process, the same resource will appear in output with vf:dropoff verb
# consume (-) for example an ingredient composed into the output, after the process the ingredient is gone
# use (0) for example a tool used in process, after the process, the tool still exists
# work (0) labor power towards a process
# cite (0) for example a design file, neither used nor consumed, the file remains available at all times
# produce (+) new resource created in that process or an existing stock resource added to
# accept (0) in processes like repair or maintentance, the same resource will appear in output with vf:modify verb
# modify (0) in processes like repair or maintentance, the same resource will appear in input with vf:accept verb
# pass (0) possible output of a testing or reviewing process, indicating the resource passed, the same resource will appear in input with *vf:accept* verb
# fail (0) possible output of a testing or reviewing process, indicating the resource failed, the same resource will appear in input with *vf:accept* verb
# deliver-service (0) new service produced and delivered (being a service implies that an agent actively receives the service)
# transfer-all-rights (-+) give full (in the human realm) rights and responsibilities to another agent, without transferring physical custody
# transfer-custody (-+) give physical custody and control of a resource, without full accounting or ownership rights
# transfer-complete (-+) give full rights and responsibilities plus physical custody
# move (-+) change location and/or identity of a resource with no change of agent
# raise (+) adjusts a quantity up based on a beginning balance or inventory count
# lower (-) adjusts a quantity down based on a beginning balance or inventory count
"""
Specification of a kind of resource. Could define a material item, service, digital item, currency account, etc.
Used instead of a classification when more information is needed, particularly for recipes.
"""
type ResourceSpecification {
id: ID!
"An informal or formal textual identifier for an object. Does not imply uniqueness."
name: String!
"The uri to an image relevant to the entity, such as a photo, diagram, etc."
image: URI
"A textual description or comment."
note: String
##############################################################################
# inverse relationships and queries
conformingResources: [EconomicResource!]
}
"""
Specifies the resource as part of a recipe, for use in planning from recipe.
"""
type RecipeResource {
id: ID!
"An informal or formal textual identifier for an object. Does not imply uniqueness."
name: String!
"The unit of inventory used for this resource in the recipe."
unitOfResource: Unit
"The unit used for use action on this resource or work action in the recipe."
unitOfEffort: Unit
"The uri to an image relevant to the entity, such as a photo, diagram, etc."
image: URI
"A textual description or comment."
note: String
"The primary resource specification or definition of an existing or potential economic resource. A resource will have only one, as this specifies exactly what the resource is."
resourceConformsTo: ResourceSpecification
"References a concept in a common taxonomy or other classification scheme for purposes of categorization or grouping."
resourceClassifiedAs: [URI!]
"Defines if any resource of that type can be freely substituted for any other resource of that type when used, consumed, traded, etc."
substitutable: Boolean
##############################################################################
# inverse relationships and queries
}
"""
The specification of a resource inflow to, or outflow from, a recipe process.
"""
type RecipeFlow {
id: ID!
"The amount and unit of the economic resource counted or inventoried."
resourceQuantity: QuantityValue
"The amount and unit of the work or use or citation effort-based action. This is often a time duration, but also could be cycle counts or other measures of effort or usefulness."
effortQuantity: QuantityValue
"The resource definition referenced by this flow in the recipe."
recipeFlowResource: RecipeResource
"Relates a process input or output to a verb, such as consume, produce, work, modify, etc."
action: Action!
"Relates an input flow to its process in a recipe."
recipeInputOf: RecipeProcess
"Relates an output flow to its process in a recipe."
recipeOutputOf: RecipeProcess
"References the ProcessSpecification of the last process the desired economic resource went through. Stage is used when the last process is important for finding proper resources, such as where the publishing process wants only documents that have gone through the editing process."
stage: ProcessSpecification
"The state of the desired economic resource (pass or fail), after coming out of a test or review process."
state: Action
"A textual description or comment."
note: String
}
"""
Specifies a process in a recipe for use in planning from recipe.
"""
type RecipeProcess {
id: ID!
"An informal or formal textual identifier for an item. Does not imply uniqueness."
name: String!
"The planned calendar duration of the process as defined for the recipe batch."
hasDuration: Duration
"References a concept in a common taxonomy or other classification scheme for purposes of categorization."
processClassifiedAs: [URI!]
"The standard specification or definition of a process."
processConformsTo: ProcessSpecification!
"A textual description or comment."
note: String
}
"""
Specifies the kind of process.
"""
type ProcessSpecification {
id: ID!
"An informal or formal textual identifier for an item. Does not imply uniqueness."
name: String!
"A textual description or comment."
note: String
}
"""
The type definition of one or more scenarios, such as Yearly Budget.
"""
type ScenarioDefinition {
id: ID!
"An informal or formal textual identifier for an item. Does not imply uniqueness."
name: String!
"The duration of the scenario, often an accounting period."
hasDuration: Duration
"A textual description or comment."
note: String
}
`
This diff is collapsed.
// Generated by scripts/build.js - edit the *.gql file instead!
module.exports = `
##
#
# Observation layer
#
# Record of what actually happened affecting the economic ecosystem.
#
#
##
union ProductionFlowItem = Process | EconomicResource
"""
An observed economic flow, as opposed to a flow planned to happen in the future. This could reflect a change in the quantity of an economic resource. It is also defined by its behavior in relation to the economic resource (see \`Action\`)
"""
type EconomicEvent {
id: ID!
"Relates an economic event to a verb, such as consume, produce, work, improve, etc."
action: Action!
"Defines the process to which this event is an input."
inputOf: Process
"Defines the process for which this event is an output."
outputOf: Process
"The economic agent from whom the actual economic event is initiated."
provider: Agent!
"The economic agent whom the actual economic event is for."
receiver: Agent!
"Economic resource involved in the economic event."
resourceInventoriedAs: EconomicResource
"Additional economic resource on the economic event when needed by the receiver. Used when a transfer or move, or sometimes other actions, requires explicitly identifying an economic resource on the receiving side."
toResourceInventoriedAs: EconomicResource
"References a concept in a common taxonomy or other classification scheme for purposes of categorization or grouping."
resourceClassifiedAs: [URI!]
"The primary resource specification or definition of an existing or potential economic resource. A resource will have only one, as this specifies exactly what the resource is."
resourceConformsTo: ResourceSpecification
"The amount and unit of the economic resource counted or inventoried. This is the quantity that could be used to increment or decrement a resource, depending on the type of resource and resource effect of action."
resourceQuantity: QuantityValue
"The amount and unit of the work or use or citation effort-based action. This is often a time duration, but also could be cycle counts or other measures of effort or usefulness."
effortQuantity: QuantityValue
"The beginning of the economic event."
hasBeginning: DateTime
"The end of the economic event."
hasEnd: DateTime
"The date/time at which the economic event occurred. Can be used instead of beginning and end."
hasPointInTime: DateTime
"The economic event occurred prior to this date/time."
before: DateTime
"The economic event occurred after this date/time."
after: DateTime
"The place where an economic event occurs. Usually mappable."
atLocation: SpatialThing
"A textual description or comment."
note: String
"Grouping around something to create a boundary or context, used for documenting, accounting, planning."
inScopeOf: [AnyType!]
"Reference to an agreement between agents which specifies the rules or policies or calculations which govern this economic event."
agreedIn: URI
"This economic event occurs as part of this agreement."
realizationOf: Agreement
"References another economic event that implied this economic event, often based on a prior agreement."
triggeredBy: EconomicEvent
##############################################################################
# inverse relationships and queries
"The commitment which is completely or partially fulfilled by an economic event."
fulfills: [Fulfillment!]
"An intent satisfied fully or partially by an economic event or commitment."
satisfies: [Satisfaction!]
appreciationOf: [EconomicEvent!]
appreciatedBy: [EconomicEvent!]
track: [ProductionFlowItem!]
trace: [ProductionFlowItem!]
"The economic event can be safely deleted, has no dependent information."
deletable: Boolean
}
"""
A resource which is useful to people or the ecosystem.
"""
type EconomicResource {
id: ID!
"An informal or formal textual identifier for an item. Does not imply uniqueness."
name: String
"References one or more concepts in a common taxonomy or other classification scheme for purposes of categorization or grouping."
classifiedAs: [URI!]
"The primary resource specification or definition of an existing or potential economic resource. A resource will have only one, as this specifies exactly what the resource is."
conformsTo: ResourceSpecification!
"Sometimes called serial number, used when each item must have a traceable identifier (like a computer). Could also be used for other unique tracking identifiers needed for resources."
trackingIdentifier: String
"Lot or batch of an economic resource, used to track forward or backwards to all occurrences of resources of that lot. Note more than one resource can be of the same lot."
lot: ProductBatch
"The uri to an image relevant to the resource, such as a photo, diagram, etc."
image: URI
"The current amount and unit of the economic resource for which the agent has primary rights and responsibilities, sometimes thought of as ownership. This can be either stored or derived from economic events affecting the resource."
accountingQuantity: QuantityValue
"The current amount and unit of the economic resource which is under direct control of the agent. It may be more or less than the accounting quantity. This can be either stored or derived from economic events affecting the resource."
onhandQuantity: QuantityValue
"A textual description or comment."
note: String
"The unit used for use or work or cite actions for this resource."
unitOfEffort: Unit
"References the ProcessSpecification of the last process the desired economic resource went through. Stage is used when the last process is important for finding proper resources, such as where the publishing process wants only documents that have gone through the editing process."
stage: ProcessSpecification
"The state of the desired economic resource (pass or fail), after coming out of a test or review process. Can be derived from the last event if a pass or fail event."
state: Action
"Used when a stock economic resource contains items also defined as economic resources."
containedIn: EconomicResource
"The current place an economic resource is located. Could be at any level of granularity, from a town to an address to a warehouse location. Usually mappable."
currentLocation: SpatialThing